 |
 |
|
|
       |
|||
|
|||||||||
|
|
|||||||||
| Related Syntax | Related Concepts | ||||||||
| control structure | catch | ||||||||
Syntax
catch catch-parameter*
You can use catch to mark the point in your program where execution will resume following a throw. A catch has a name, so you can have multiple active catches with different names. Each throw must name the catch it throws to. A catch introduces a block of code which is executed once the throw is caught.
declare catch no-planet
global stream planet
process
output "Hello "
throw no-planet when planet isnt attached
output planet
catch no-planet
output "world!"
This program is designed to run with the value of the stream "planet" supplied on the command line. If this is not done, the throw transfers execution to the catch statement.
(Obviously this simple example would be better handled with a simple do when ... else ... done construct. Catch and throw is intended for large-scale flow control, just as "do when" is intended for small-scale flow control. We use simple examples to illustrate the syntax. We do not recommend using throw and catch where "do when" or other, simpler structures would do as well.)
For information on how catch and throw work together, see throw.
Since catches are named, you must declare the name, just like any other name you introduce into your OmniMark program. The catch declaration can also declare parameters, following the same form as function parameters. Read only, value, and remainder parameters are supported, but not modifiable. Parameters may not be declared optional. See declare function for a full description of function parameters.
The following is an example of a catch declaration with parameters:
declare catch invalid-item
value stream the-item
error value stream the-error
times value integer num-times
Catches can use either the heralded or parameterized form for declaring arguments, just like function definitions. The same considerations as for functions apply to choosing one or the other.
In addition to the catches you declare yourself, you can also catch two predefined OmniMark throws, #program-error and #external-exception.
A catch is active only when it is in the current execution scope of your program. OmniMark will look for the catch named in a throw in the current scope. If the named catch does not exist in the current scope, OmniMark looks for it in the parent scope, and so on. Once the named catch is found, OmniMark closes the current scope and all intervening scopes as required to reach the catch. Execution is then transferred to the catch.
If the named catch is not found, OmniMark raises an error which will be caught by the first available catch of #program-error.
It is a compile-time error to use a catch that has not been declared. It is also a compile-time error to declare the same catch twice.
You can catch the same catch name at different points in your program, but there can be only one catch of a particular catch name in any one lexical scope. Only the catch in the innermost execution scope is active at any given point in program execution.
Many OmniMark constructs can result in a rule or function being called recursively. Therefore, a single lexical catch may exist at many different levels of execution scope when a program is run.
Catch statements are always at the end of a scope. That is to say, a catch ends the current lexical scope and the body of the catch is outside the normal flow of that scope. Execution does not fall through into a catch body. The code in a catch body can only be executed as a result of a throw to that catch. A throw initiated inside a catch body or an associated always cannot be caught in the local scope. Throws within a catch or always block must be caught at a wider scope of execution.
Catch and throw versus function calls
Catch and throw has much in common with function calls. Both declare and use parameters to pass information, and both cause a transfer in execution to a new part of the program. They differ in the following principal ways:
|
Related Syntax #program-error #external-exception always throw rethrow declare catch |
Related Concepts Catch and throw |
| ---- |
