Error Handling¶

Error Reporting Methods¶

The error_… methods in Lasso allow reporting custom errors and provide access to the most recently reported error by the code executing in the current Lasso page. This allows a developer to check for specific errors and respond, if necessary, with an error message or with code to correct the error.

Lasso maintains a single error code and error message, which is set by any method that reports an error. The error code and error message should be checked immediately after a method that may report an error. If any intervening methods or expressions report errors, the original error code and error message will be lost.

Custom errors can be created using the error_setErrorMessage and error_setErrorCode methods. Once set, the error_currentError method or error_code and error_msg methods return the custom error code and message. A developer can use these methods to incorporate both built-in and custom error codes into the error recovery mechanisms for a site.

error_currentError(-errorCode=?)¶

Returns the current error message. An optional -errorCode parameter will return the current error code instead.

error_code()¶

Returns the current error code.

error_msg()¶

Returns the current error message.

error_obj()¶

Returns the current error name from the Lasso variable $_err_obj, or “null” if no error object is present.

error_push()¶

Pushes the current error condition onto a stack and resets the current error code and error message.

error_pop()¶

Restores the most recent error condition stored using error_push.

error_reset()¶

Resets the current error code and error message.

error_setErrorCode(code)¶

Sets the current error code to a custom value.

error_setErrorMessage(msg)¶

Sets the current error message to a custom value.

error_stack()¶

Returns the stack trace for the current error.

'The current error is ' + error_code + ': ' + error_msg
// => The current error is 0: No Error

'The current error is ' + error_currentError(-errorCode) + ': ' + error_currentError
// => The current error is 0: No Error

error_setErrorMessage('A custom error occurred')
error_setErrorCode(-1)

'The current error is ' + error_code + ': ' + error_msg
// => The current error is -1: A custom error occurred

error_msg = 'A custom error occurred'
error_code = -1

error_push  // Push error onto stack

protect => { // Protect from failure
   handle_failure => {
      // Handle any errors generated within the protect block
   }
   // ...
}

error_pop  // Retrieve error from stack

define myMethod() => {
   // Push current error onto stack
   error_push

   // ... code that may generate an error ...

   // Retrieve error from stack
   error_pop

   return 'myValue'
}

error_code = -1
error_msg  = 'Too slow'
error_code + ': ' + error_msg

// => -1: Too slow

error_reset
error_code + ': ' + error_msg

// => 0: No error

Lasso Errors¶

The table below lists Lasso’s standard error codes and values.

Error Handling Methods¶

fail(msg::string)¶

fail(code::integer, msg::string, stack::string=?)

Halts execution and generates the specified error. Can be called with just an error message, an error code and an error message, or an error code, message, and stack trace.

fail_if(cond, msg::string)¶

fail_if(cond, code::integer, msg::string)

Conditionally halts execution and generates the specified error if the specified condition evaluates to “true”. Takes two or three parameters: a conditional expression, an optional integer error code, and a string error message.

handle(cond=?)¶

Conditionally executes a given capture block after the code in the current capture block or Lasso page has completed or a fail method is called. May take a conditional expression as a parameter that limits executing the capture block to when the conditional statement evaluates to “true”. If an error occurs in the Lasso code before the handle block is defined, the handle’s capture block will not be executed.

handle_failure(cond=?)¶

Functions the same as handle except that the contents are executed only if an error was reported in the surrounding capture block or Lasso page.

protect()¶

Protects a portion of a page. If code inside the given capture block throws an error or a fail method is executed inside the capture block, the error is not allowed to propagate outside the protected capture block. This means that a fail will only halt the execution of the rest of the code in the protect capture, and execution will resume starting with the code following that capture.

abort()¶

Sets the current error code to error_code_aborted and stops Lasso from continuing execution. This cannot be stopped with protect.

handle and handle_failure¶

The handle method is used to specify a block of code that will be executed after the current code segment is completed. The handle method can take a single parameter that is a conditional expression, defaulting to “true”. If the conditional expression evaluates as “true”, the code in the given capture block is executed.

All handle and handle_failure methods are processed sequentially, giving each a chance to be executed in the order they were specified and allowing for execution of multiple handle blocks. Therefore, it is necessary to define them before logic that could halt execution. Any handle methods that are defined after a script failure will not be executed. It is generally good practice to place handle and handle_failure methods at the start of the parent capture block, most commonly a protect capture block. (This is a change from previous versions of Lasso and increases the reliability of executing fault-condition fallbacks.)

The handle methods will not be executed if a syntax error occurs while Lasso is parsing a page. When Lasso encounters a syntax error it will return an error page instead of processing the code on the page.

The handle methods will be executed if a logical error occurs while Lasso is processing a page. However, the returned result will be an error message rather than the output of the page. Code within the handle capture block can redirect the user to another page using redirect_url or can replace the contents of the page being served.

There are two ways to use handle methods within a Lasso page:

1. When used on their own in a Lasso page, the code inside the handle methods will be conditionally executed after all the rest of the code in the Lasso page has completed. The handle methods can provide post-processing code for a Lasso page.
2. When used within any Lasso capture block, the code inside the handle methods will be conditionally executed after the capture block is executed. The handle methods will most commonly be used within a protect block to provide error handling.

fail and fail_if¶

The fail method allows an error to be triggered from within Lasso code. Use of the fail method immediately halts execution of the current page and starts execution of any registered handle method contained within.

The fail method can be used in the following ways:

• To report an unrecoverable error. Just as Lasso automatically halts execution of a Lasso page when a syntax error or internal error is encountered, Lasso code can use the fail method to report an error that cannot be recovered from:

  fail(-1, 'An unrecoverable error occurred')
  

• To trigger immediate execution of the page’s handle methods. If an error is handled by one of the handle methods specified in the Lasso page (outside of any other capture blocks), the code within the handle capture block will be executed. The handle block can recover from the error and allow execution to continue by using the error_reset method.

• To trigger immediate execution of a protect capture block’s handle block, which is described in the next section.

The fail_if method allows conditional execution of a fail without using a full if/else conditional. The first parameter to fail_if is a conditional expression. The last two parameters are the same integer error code and string error message as in the fail method. In the following example the fail_if method is only executed if the variable “x” does not equal “0”:

fail_if(#x != 0, 100, "Value does not equal 0.")

protect¶

The protect method is used to catch any errors that occur within the code surrounded by the capture block. They create a protected environment from which errors cannot propagate to the page itself. Even if Lasso reports an internal error it will be caught by the protect method, allowing the rest of the page to execute successfully.

Any fail or fail_if methods called within protect capture blocks will halt execution only of the code contained within the protect capture block. Any handle capture blocks contained within the protect capture blocks will be conditionally executed. However, Lasso requires these handle capture blocks to be present before the error occurs, so put them at the top of the protect capture block. The Lasso page will continue executing normally after the closing of the protect capture block.

The protect capture blocks can be used for the following purposes:

• To protect a portion of a page so that any errors that would normally result in an error message being displayed to the user are instead handled in the internal handle capture blocks.
• To provide advanced flow control in a page. Code within the protect capture blocks is executed normally until a fail signal is encountered. The code then jumps immediately to the internal handle block.

protect => {
   $myVar = null
}

protect => {^
   handle => {^
      if(error_code == -1)
         '... Handle custom error -1 ...'
      else(error_code == -2)
         '... Handle custom error -2 ...'
      else
         '... Another error has occurred ...'
      /if
   ^}

   'Before the fail_if\n'

   local(
      condition_one = false,
      condition_two = true
   )
   fail_if(#condition_one, -1, 'Custom error -1')
   fail_if(#condition_two, -2, 'Custom error -2')

   '\nAfter the fail_if'
^}

// =>
// Before the fail_if
// ... Handle custom error -2 ...