Events are a natural way to handle errors. KRL makes use of its built in event system to process errors. Raising events for errors and then handling them with rule sets gives developers a great deal of flexibility in dealing with exceptional situations in their code.

System-Raised Errors

KRE will raise errors for various system-level errors that happen during the execution of a KRL rule set. For example, KRL will raise an error when a rule attempts to take an undefined action or for a type mismatch on an operator—for example, applying the length() operator to an integer.

When KRE raises an error event, it uses the event domain system and the event type error. The following event attributes are attached to the event:

• level. The level of the event: error, warn, info, or debug. Processing of the rule continues for all levels except error where execution is terminated.
• msg. A string giving details about the error.
• error_rid. The rule set ID of the offending rule set.
• rule_name. The name of the offending rule.
• genus. A token from the top level of the error taxonomy (described momentarily), indicating the first-level classification of the error.
• species. A token from the second level of the error taxonomy, indicating the classification of the error within the genus

Because one error often cascades into others, KRE limits the number of errors from a single event to just one. 

The KRL error taxonomy provides a two-level classification of errors. Unless otherwise noted, all of the errors in the following taxonomy are raised at the warn level.

• action
  • undefined
• data
  • conversion failed
  • source unavailable
• expression
  • invalid operator
  • type mismatch
  • recursion threshold exceeded
  • array reference undefined
  • function undefined
• module
  • function undefined
  • module undefined
• operator
  • type mismatch
• system
  • malformed event
  • ruleset_not_installed
  • unknown

Program-Raised Errors

In addition to system errors, KRL programs can also raise errors explicitly in the rule postlude. User-raised errors have the event domain system and the event type error. The genus is set to user.

The syntax of an explicit error statement is as follows:

error <level> <expr>

In this statement, <level> is one of error, warn, info or debug, and <expr> is any valid KRL expression that results in a string (or something that can be cast as a string, such as a number). The expression will be sent as an event attribute with name msg. 

The following example would raise an event with domain system, type error, genus user, level info and a message with the value of a variable named query if the rule were to fire:

fired {
  error info "query:"+query
}

The following would only raise the event if the query variable were empty:

fired {
  error info "Empty query" if(query like "^$")
}

Explicit errors set the rid and rule_name attributes from the current rule set ID and rule name. 

Handling Errors

Handling errors is as easy as creating a rule with the right select statement. For example, the following rule will use the send_error() action from the errorstack module (aliased as es) to record an error using the Error Stack service:

rule process_error {
  select when system error
  pre{
    genus = event:attr("genus");
    species = event:attr("species");
  }
  es:send_error("(#{genus}:#{species}) " + event:attr("msg"))
    with rule_name = event:attr("rule_name")
     and rid = event:attr("rid");
}

Like any other event, if an error event is raised and no rule is selected for it, nothing happens.

Because developers often want to process all errors from several rule sets in a consistent way, KRL provides a way of routing error events from one rule set to another. In the meta section of a rule set, developers can declare another rule set that is the designated error handler. For example, if the preceding process_error rule were defined inside rule set a16x88, then the following declaration would automatically route error events from the current rule set to a16x88 for processing:

meta {
  errors to a16x88
}