TRY

The function TRY tries to return the result of a given Airscript expression, but if that expression results in an error, it will return the result of a different given Airscript expression rather than throwing an error.

This function takes two Airscript expressions as input. If the first Airscript expression can be evaluated without throwing an error, it returns the result. If full evaluation of the first Airscript expression would result in throwing an error, it instead returns the result of the second Airscript function.

Declaration

TRY(expression, expression_on_error) -> expression_result

Parameters

expression (required, type: any)

The Airscript expression to try.

expression_on_error (required, type: any)

The Airscript expression to evaluate and return upon the first expression throwing an error.

This expression has access to a special internal variable, caughtError. caughtError is generated by the error that would have been thrown by the first expression. It is an object with the following properties:

• details (type: object)

• details.airkitErrorType (type: string)

• details.sourceProject (type: string)

• details.name (type: string)

• details.identifier (type: string)

• details.metadata (type: object)

• details.httpStatus: (type: Number)

The following is an example of a potential caughtError value:

{
  "details": {
    "airkitErrorType": "ApplicationError",
    "sourceProject": "cxr-undefined",
    "name": "ApplicationError",
    "identifier": "error.application.airscript.function.parse-phone",
    "metadata": {
      "message": "invalid-country-code"
    },
    "httpStatus": 400
  }
}

Referencing caughtError within expression_on_error can make the circumstances of the error more immediately visible.

Return Values

expression_result (type: any)

If expression does not result in an error, the result of expression. Otherwise, the result of expression_on_error.

Examples

For the sake of example, consider the PARSE_PHONE function, which throws an error if it is given a string that does not represent a value phone number:

PARSE_PHONE("not a phone number") -> ERROR

If the first expression given to the TRY function is a PARSE_PHONE function that has been given an invalid phone number, the TRY function will return the result of the second expression. In the following example, that's a simple string that reads, "That's not a phone number.":

TRY(
  PARSE_PHONE("not a phone number"),
  "That's not a phone number."
) -> "That's not a phone number."

The above example showcased an expression_on_error that could be returned as-is. However, if the *expression_on_error contains variables, functions, or operators, the TRY function will evaluate them before returning the results. The following example uses an expression_on_error value that contains the Addition operator. Note how this is evaluated:

TRY(
  PARSE_PHONE("not a phone number"),
  2 + 2
) -> 4

Not all initial expressions will result in an error. If, for instance, the PARSE_PHONE expression is given a valid phone number and country as input, then the TRY function will return the result of that expression, uninfluenced by the value of expression_on_error:

TRY(PARSE_PHONE("7167762323", "US"), 2 + 2) -> [phone]

A common application of the TRY function is to test Airscript expressions while an application is still in development, as it makes potential errors details visible without the need to throw an error. The TO_JSON function can be used in tandem with the variable caughtError.details to return information on the sort of error that would have been thrown, had the TRY function not prevented it:

TRY(PARSE_PHONE("not a phone number"), TO_JSON(caughtError.details)) -> {
   "airkitErrorType":"ApplicationError",
   "sourceProject":"cxr-undefined",
   "name":"ApplicationError",
   "identifier":"error.application.airscript.function.parse-phone",
   "metadata":{
      "message":"invalid-country-code"
   },
   "httpStatus":400
}

Individual properties of the caughtError variable can be properly isolated through dot notation:

TRY(PARSE_PHONE("not a phone number"), caughtError.details.identifier) -> "error.application.airscript.function.parse-phone"

The TRY function can also be combined with the THROW function, which throws custom errors. For instance, the following example uses the THROW function to throw an error, and then the TO_JSON function to view details of the error that would have been thrown. Note how the metadata passed by the THROW function ("err" and "err message") appear in the output:

TRY(
  THROW("err", "err message"),
  TO_JSON(caughtError.details)
)
->
{
   "airkitErrorType":"ApplicationError",
   "sourceProject":"cxr-undefined",
   "name":"ApplicationError",
   "identifier":"error.application.user-defined-error",
   "metadata":{
      "identifier":"err",
      "message":"err message",
      "metadata":{
         
      }
   },
   "httpStatus":400
}