Taking Action

Taking action is the primary reason for executing rules. Ironically, the basis for this most basic and important part of KRL is surprisingly simple. There are just a few fundamental actions. The rest are built from these.

Before I describe the specific actions, you need to understand the structure of actions. Actions have a name, a set of required parameters, and a set of optional parameters. Optional parameters are specified using a with clause followed by a list of name-value pairs. The name and value are paired using an equal sign (=) and the name-value pairs are separated with the keyword and:

foo("hello", 5) with 
  x = "world" and
  y = 6 + 5

This action has a name, foo, and two parameters, "hello" and 5. The action also has two optional parameters, x with the value "world" and y with the value 11. The parameters, required and optional, can be any valid KRL expression and will be evaluated prior to the action being taken. More formally, parameters are evaluated in applicative order.

The following basic actions are available in KRL:

send_directive(<expr>). This returns a directive with the name given by the expression <expr>. (Don't confuse action names, send_directive in this case, and directive names given as the required parameter to the action.) Optional parameters provided to send_directive are passed through to the options structure of the directive as name-value pairs. This action is the primary means of creating directive documents for endpoints. For example, the following action produces the directive document below it:

send_directive("say") with
  something = "Hello World" 


{"directives":
 [{"options":{"something":"Hello World"},
   "name":"say",
   "meta":{
     "rule_name":"hello_world",
     "txn_id":"8FF45D92-7EDB-11DF-B34A-4BA9F4723EB4",
     "rid":"a16x66"
   }
  }
 ]
}

See the send_directive() documentation for more details. 

send_javascript(<expr>). This returns its argument as a JavaScript closure application whose body is given by <expr>. The names of any optional parameters are used as parameters in the closure. The closure is applied to the values of any optional parameters. This action is used for communicating with browser endpoints. For example, the following action produces the JavaScript below it. (The <|...|> syntax, called clown hats, is a type of KRL extended quote for producing JavaScript. Values in clown hats are assumed to be JavaScript. White space is not necessarily preserved and templating mechanisms are available.)

send_javascript(<|x + y|>) with
  x = 5 and
  y = 6 

(function(x, y) { x + y } (5, 6));

http:post(<expr>). This makes an HTTP POST to the URL given by <expr>. Any optional parameters are added as name-value pairs in the query string of the URL. This action is useful for interacting with Web services that aren't formally part of KEA. For example, the following action makes an HTTP POST to the given URL, form-encoding the optional parameter q and sending it as the body of the POST:

http:post("http://google.com/search") with
  q = "hello"

send_raw(<type>). This returns raw content. This is especially useful for returning content with a mime-type different from application/json or returning raw JSON without the enclosing directive. See the send_raw() documentation for more information. 

(Classic) Web Actions discusses actions that are specific to the Web. See also User Defined Actions and Compound Actions.