XMREngine.trycatch

EXCEPTION HANDLING

Provide a mechanism for catching exceptions.

Enabled by: xmroption trycatch;

Keywords

   catch
   exception
   finally
   throw
   try

Statements

   'try' '{' statements ... '}'
   [ 'catch' '(' 'exception' name ')' '{' statements ... '}' ]
   [ 'finally' '{' statements ... '}' ]

   'throw' expression ';'

   'throw' ';'     // rethrow from within a 'catch' clause

   A single try can include any number (greater than zero) of catch and/or 
   finally clauses, in any order.  They are stepped through one-by-one and 
   executed as needed.  try/catch/finally can be nested in any combination.

   The expression of a throw statement within a try clause can be of any type, 
   eg, integer, string, script-defined object type.  Any finally clauses 
   between the throw and the corresponding catch are executed before the 
   catch.  Then the single catch is executed.  If the catch rethrows the 
   execption, then the search for a catch clause resumes, executing finally 
   clauses until a match is found.  If a catch does not rethrow the execption, 
   all finally clauses outside the catch are executed and all catch clauses 
   outside the catch are ignored.

   If an exception is thrown and no catch clause is found, all finally clauses 
   are executed in order and the script is terminated and an error message is 
   printed.  This also applies to an exception thrown outside any try clause 
   trivially as there can't be any catch clauses for it and there won't be any 
   finally clauses to execute either, the script is simply terminated and an 
   error message is printed.

Related built-in functions

       string xmrExceptionMessage(exception)

           get an human readable error message associated with the exception.

       string xmrExceptionStackTrace(exception)

           gets a string indicating where in the script the exception occurred.

       object xmrExceptionThrownValue(exception)

           given the value from the catch clause, return the object from the 
           throw statement that threw the exception.  If the exception was not 
           from a throw statement (ie, some internal exception), this call 
           throws an "InvalidCastException".

       string xmrExceptionTypeName(exception)

           given the value from the catch clause, return a string giving the 
           type of the exception, eg, "ScriptThrownException" for a throw 
           statement.  Other types can be "NullReferenceException", etc.

Example

   xmroption arrays;
   xmroption trycatch;
       state_entry ()
       {
           try {
               CallSomethingThatThrows ("try to catch this!");
           } finally {
               llOwnerSay ("finished one way or another");
           } catch (exception ex) {
               PrintOutException (ex);
           }
   
           try {
               llOwnerSay (((array)(object)undef).count);
           } catch (exception ex) {
               PrintOutException (ex);
           }
       }
   }
   
   CallSomethingThatThrows (string s)
   {
       llOwnerSay ("say something so we don't get inlined");
       throw s;
   }
   
   PrintOutException (exception ex)
   {
       llOwnerSay ("   typename: " + xmrExceptionTypeName (ex));
       llOwnerSay ("    message: " + xmrExceptionMessage (ex));
       try {
           object tv = xmrExceptionThrownValue (ex);
           llOwnerSay ("thrownvalue: " + tv);
       } catch (exception ex2) {
           if (xmrExceptionTypeName (ex2) != "InvalidCastException") throw;
       }
       llOwnerSay (" stacktrace:\n" + xmrExceptionStackTrace (ex));
   }

...generates this output:

   say something so we don't get inlined
   finished one way or another
      typename: ScriptThrownException
       message: try to catch this!
   thrownvalue: try to catch this!
    stacktrace:
   at CallSomethingThatThrows(string) <trycatchexample.lsl(27,4)>
   at default state_entry <trycatchexample.lsl(9,36)>
   
      typename: NullReferenceException
       message: Object reference not set to an instance of an object
    stacktrace:
   at default state_entry <trycatchexample.lsl(17,23)>