(Classic) Raising Explicit Events in the Postlude

Explicit events are raised in the rule postlude with a raise statement. You can raise explicit events from a postlude like so:

raise <domain> event <expr> [for <expr>] [with <modifier_clause> | attributes <expr>] 

The event <domain> is can be one of

  • explicit
  • http
  • system
  • notification
  • pds
  • error

The event name is given by the <expr>. The expression is evaluated and the resulting string is used as the event name.

Because the event name is an expression, you should use a string for fixed event names rather than using a bare word. A bare word will be treated as a string for reasons of backward compatibility unless it is previously defined (i.e. in a rule prelude) in which case it evaluated and its value will be used as the event name. Save yourself the grief of accidentally having a bare word evaluated and use a string.

Attributes

Attributes for the explicit event can be given using either the modifier clause denoted by the keyword with or the attributes clause denoted by the keyword attributes. You can use a modifier clause or an attributes clause, but not both. 

Modifier Clause

The modifier clause allows the developer to add event parameters to the explicit event. The right side of the individual bindings in the with clause can be any KRL expression. The modifier clause takes the following form:

with <var> = <expr> [and <var> = <expr>]* 

Any variable in a modifier clause is used (with its associated value) as an event parameter.  

The following example illustrates this

raise explicit event "foo"
  with a = "hello"
   and b = 4 + x;

Engine Compatibility

In the node pico engine, the modifier clause has this form (note, no "and"):

with <var> = <expr> [ <var> = <expr> ]*

making the example

raise explicit event "foo"

with a = "hello"

b = 4 + x

Attributes Clause

The attributes clause also allows the developer to add event attributes to the explicit event. The expression that follows the attributes key word must evaluate to a map. The keys and values in the map will be used as event attributes. This is particularly useful when you want to pass thru all, or most, of the attributes that the current rule received:

raise explicit event "foo"
  attributes event:attrs()

This raises the event explicit:foo with all of the attributes that were passed into the enclosing rule.

Automatic Attributes

When a rule is raised, the following automatic attributes are added for convenience:

  • _generatedby - the ruleset ID and version of the ruleset of the rule where the raise statement is processed given as <rid>.<version>

What Rulesets See an Explicit Event?

You can control which rulesets see an explicit event using the optional for clause. 

The for clause is followed by an expression that is evaluated to determine which rule sets should see the event. The result must be a string, giving the target ruleset ID or an array of target rulesets. A target ruleset ID has the form <rid[.<ver>]> where the optional version may be the keyword "prod" for the production ruleset or a version number for the explicit version. If the version is unspecified, the system will match the target version to the version of the current ruleset.

In the Sky Event API, explicit events will be raised to any ruleset that an entity has installed unless a for clause is present. You can specify the current ruleset using the meta:rid() functions from the meta library.  Normally the API is determined by what API was used to raise the event that caused processing to commence. You can ensure that the behavior of explicit events will follow the Sky API behavior by specifying that the Sky API be used as follows:

raise explicit event "foo"
  with a = "hello"
   and b = 4 + x
   and _api = "sky";

In the (Classic) Blue Event API, explicit events will be raised to the current ruleset unless a ruleset or an array of rulesets is specified using the for clause.

Like any other postlude statement, explicit events can be guarded:

raise explicit event "foo"
  with a = "hello"
   and b = 4 + x
 if (flipper eq "two");

The event in the preceding example will only be raised if the variable flipper has the value "two".

Explicit events allow KRL programmers to chain rules together. Rule chaining is good for modularization, error handling, preprocessing, and abstraction as you can see in the Examples

Copyright Picolabs | Licensed under Creative Commons.