User-Defined Actions

User defined actions are created using the defaction keyword. The defaction keyword closely follows the syntax of functions. User-defined actions allow for data preprocessing and the execution of one or more actions. User-defined actions are useful for wrapping actions to allow for composite actions or a cleaner syntax surrounding existing actions for a common use case.

defaction(<arguments>) {
  configure using key1 = value1 and 
                  key2 = value2 and 
                  ...
                  keyN = valueN
  <declaration0>
  ...
  <declarationN>
  <action block>
}

The arguments are a possibly empty, comma-separated list of variable names. Optional arguments can be specified with the configure statement, as shown here, and are given default values. Zero or more declarations can be included to prepare data for the action block.

The action block is the same as the action block in a rule. Any action, including a user-defined action, can be used in the action block. Actions can be simple or compound. A simple action is a valid action block. For example, the following defines an action called send_warning using the notify action:

send_warning = defection(msg) {
notify("Warning!", msg);
}

Compound actions must be enclosed in curly brackets ({...}). Suppose, for example, that in addition to putting up a notification, you wished to place the warning message in a <div/> element on the page:

send_warning = defection(msg) {
  {notify("Warning!", msg);
   append("#warning_div", msg)
  }
}

You can use optional parameters to modify send_warning so that it is sticky by default. (The default behavior for notify is for the notification to fade after six seconds. When the sticky parameter is true, notifications are permanent until the user closes them.)

send_warning = defaction(msg) {
  configure using transitory = false
  notify("Warning!", msg)
    with sticky = not transitory
}

The variable send_warning only has meaning in an action context within a rule. The following shows the use of send_warning and its optional parameter in the action of a rule:

if error_level > 12 && error_level < 15 then
  send_warning("Abnormal error levels")
    with transitory = true

Because user-defined actions are first-class values (i.e., they can be returned as the result of executing an expression), they can be passed into functions or other user-defined actions and returned as the result from a function. You can thus write recursive actions.