Water 5-Flow Control and Boolean-Error Handling
method try
Contract
Return typewob
Parameter keyDefault valueType
if_errornull with ekind of expressionwob
if_timed_out"timed_out" with ekind of expressionwob
finallyopt with ekind of expressionwob
time_limitnull
Parameter kindDefault valueType
Other unkeyed argumentsopt with ekind of expressionwob
Water Contract
<method try
  if_error    =null=wob=ekind.expression
  if_timed_out="timed_out"=wob=ekind.expression
  finally     =opt=wob=ekind.expression
  time_limit  =null
  _other_unkeyed=opt=wob=ekind.expression="_body"/>

See also: error, do

Try executes its body and returns the value of the last expression in the body unless there's an error, in which case it executes its if_error argument and returns the last value of the content.
<try if_error="busted">
   123
   456
</try>
456

a wob
Parameter keyDefault valueType
"if_error"false
The if_error has an ekind of expression meaning it is not executed every time a call to try is executed.

<try if_error="we had an error">
    234
    <error "busted"/> 
    567 
   </try>
"we had an error"
First 234 is executed to get 234, then the call to error is executed but this will error because, well that's what a call to "error" does. Due to the error, the if_error argument to 'try' will be executed. This returns the string "we had an error".
<try if_error="there was an error" > 234 567 </try>
567
Above there is no error so the if_error argument of the call to try is never executed.
a wob
"if_error"=error_object
When the if_error argument of a try is executed, a local variable named error_object is bound to the string of the error message that was created by executing the attributes to try.
<try if_error="This call had: ".<join error_object/> >
     234 
     <error "busted"/> 
     567
    </try>
"This call had: Runtime error:
busted"
If the body of a call to 'try' causes an error, try executes the code up to the error in the body, and, with no if_error argument, just returns null without erroring.
Example: No if_error argument
<try>
  <error "got an e"/>
</try>
null
Since the call to try above doesn't actally error, any code after the call to try will be executed.
<do
<try>
  <error "got an e"/>
</try>
 33
/>
33
If you want to return the "error_object" (which is just string), you can:
Example: Return the error object.
<try if_error=error_object>
  <error "got an e"/>
</try>
"Runtime error: got an e"
Beware, though, that the call to try does not result in an error, and processing continues on after the call to try:
<do 
  <try if_error=error_object>
    <error "got an e"/>
  </try>
  33
/>
33
If what you're after is to call the try and have it error when its content errors:
<do
  <try if_error=<error error_object/>>
    <error "got an e"/>
  </try>
  33
/>
error
The above code is the same as:
<do <error "got an e"/> 33/>error
So you wouldn't bother using the try at all. More likely though, is that you'd want to do something before causing the error in the if_error argument. You might want to write some 'clean-up' code before erroring. Here we simulate our clean-up code with an echo statement:
<do
  <try if_error=<do <echo "cleanup 'got an e' error"/> 
                    <error error_object/>
                 />
      >
    <error "got an e"/>
  </try>
  33
/>
error
If you want to protect against the if_error argument of a try call causing an error, wrap another try statement all around your original call to try. busted Here's the order of execution above:
  1. 123 is executed
  2. <error "a bug"/> is executed causing an error.
  3. <error "some code that errors"/> is executed
  4. "busted" is executed.

a wob
Parameter keyDefault valueType
if_timed_out"timed_out" with ekind of expressionwob
You can limit the amount of time that try will attempt to execute its content before calling the error code in the content.

<try time_limit=20 if_timed_out="timed out">
   <for_each forever=true> null </>
  </try>
"timed out"
Since the for_each is an infinite loop, it will not terminate until your computer runs out of resources. However our time_limit argument specifies that it will only run for 20 milliseconds until try itself terminates the infinite loop and executes the code in the if_error argument of the call to try.