Rulesets API

Notes

For all functions, enter the parameters in the order listed.
Italicized parameters are optional.
Received Events are events of the "wrangler" domain that Wrangler will respond to
Raised Events are events that can be selected on within any ruleset in the pico when they occur
Sent Events are events that the pico will send elsewhere as a result of triggering a Wrangler event.

Functions

installedRulesets

Returns an array of all of the rulesets installed on the pico

Returns

An array of strings, with each string being an RID (ruleset identifier)

Example

installed_rulesets = wrangler:installedRulesets()
/*
  ["io.picolabs.pico", ...]
 
*/

registeredRulesets

Returns an array of all the registered rulesets on the pico engine that the pico is running on.

Returns

An array of strings, with each string being an RID (ruleset identifier)

Example

registered_rulesets = wrangler:registeredRulesets()
/*
    ["io.picolabs.pico", "io.picolabs.logging"]
*/

rulesetsInfo

Returns an array that contains full ruleset descriptions for the requested ruleset(s)

Parameters

Parameter

Datatype

Description

rids

Array

String

The RIDs of the rulesets to be described. Each RID can be an entry in an array, or in a semicolon denoted list (e.g. "io.picolabs.ruleset_one;io.picolabs.ruleset_two").

Returns

A an array where each entry is a requested ruleset's description.

See the example for an idea of what each description (represented as a map) looks like

Example

wrangler_info = wrangler:rulesetsInfo("io.picolabs.wrangler")
/*
[
  {
    "rid": "io.picolabs.wrangler",
    "src": "omitted for brevity, full source would show up here",
    "hash": "7d68b3232f8d820631ab73871530648b94ab610f598cab1986d7cd666232a0a0",
    "url": "The URL that the ruleset might be installed from, if downloaded from a remote server",
    "timestamp_stored": "2019-01-12T02:17:04.044Z",
    "timestamp_enable": "2019-01-12T02:17:04.045Z",
    "meta": {
      "name": "Wrangler Core",
      "description": "\r\n      Wrangler Core Module,\r\n      use example, use module v1_wrangler alias wrangler .\r\n      This Ruleset/Module provides a developer interface to the PICO (persistent computer object).\r\n      When a PICO is created or authenticated this ruleset will be installed to provide essential\r\n      services.\r\n    ",
      "author": "BYU Pico Lab"
    }
  }
]
*/

Received Events

install_rulesets_requested

wrangler:install_rulesets_requested

Installs the given rulesets in the pico that receives this event.

Attributes

Attribute

Datatype

Description

rids OR rid

Array

String

The RIDs of the rulesets to be installed on this pico. Each RID can be an entry in an array, or in a semicolon denoted list (e.g. "io.picolabs.ruleset_one;io.picolabs.ruleset_two").

urls OR url

Array

String

The URLs of the rulesets to be installed on this pico. Each RID can be an entry in an array, or in a semicolon denoted list (e.g. "https://github.com/Picolab/pico-engine/raw/master/test-rulesets/hello-world.krl;https://github.com/Picolab/pico-engine/raw/master/test-rulesets/http.krl").

Directives Returned

send_directive("rulesets installed", { "rids": /* An array of rids that were installed*/ });

Corresponding Raised Events:

Wrangler Full API#ruleset_added

uninstall_rulesets_requested

wrangler:uninstall_rulesets_requested

Uninstalls the given rulesets in the pico that receives this event. The directives returned will always be the same, meaning if the ruleset did not exist in the first place, the directive would still map "rids" to the RIDs given as the event attribute. Use the Wrangler Full API#installedRulesets function to programmatically check if a ruleset is installed.

Attributes

Attribute

Datatype

Description

rids OR rid

Array

String

The RIDs of the rulesets to be uninstalled on this pico. Each RID can be an entry in an array, or in a semicolon denoted list (e.g. "io.picolabs.ruleset_one;io.picolabs.ruleset_two").

Directives Returned

send_directive("rulesets uninstalled", { "rids": /* An array of rids that were uninstalled*/ });

ruleset_needs_cleanup_period

wrangler:ruleset_needs_cleanup_period

This event is used to signal to Wrangler to register a ruleset domain to wait for before fully deleting a pico, to allow the ruleset(s) time to cleanup.

Attributes

Attribute	Datatype	Description
domain	String	The ruleset domain to reigster to wait to cleanup.

cleanup_finished

wrangler:cleanup_finished

This event is used to signal to Wrangler that a ruleset domain previously registered for cleanup is finished.

Attributes

Attribute	Datatype	Description
domain	String	The ruleset domain that is done cleaning up.

set_timeout_before_pico_deleted

wrangler:set_timeout_before_pico_deleted

This event is used to change the time allotted for rulesets to cleanup before it times out and the pico deletes itself anyway. By default it is set to 5 minutes.

Attributes

Attribute	Datatype	Description
new_timeout	String	Has the same format as the second parameter of the time:add() function. (e.g. {"minutes":5} or {"seconds":5})

Raised Events

ruleset_added

wrangler:ruleset_added

Is raised within the pico when new ruleset(s) have just been installed. This can be especially useful as an entry point for code execution on any ruleset. By selecting on this event and checking if your ruleset is one of the installed ones, your ruleset can begin execution upon installation.

Attributes Added

Attribute	Datatype	Description
rids	Array	An array of rids that were installed

Example

rule on_installation{
  select when wrangler ruleset_added where rids >< meta:rid.klog("meta rid") // if this ruleset has just been installed
  pre {
  }
  noop()
  fired{
    ent:ownerPolicy := owner_policy;
    ent:owners := {"root": {"eci": new_channel{"id"}}};
    raise game event "start_game"
      attributes event:attrs;
  }
}

install_rulesets_error

wrangler:install_rulesets_error

This event is raised when there was an error installing a ruleset into a pico. This may (but not only) include giving a RID that does not exist on the engine to install.

Attributes Added

Attribute	Datatype	Description
rids	Array	An array of rids that failed to install

rulesets_need_to_cleanup

wrangler:rulesets_need_to_cleanup

This event is raised when a pico is now getting ready to delete. Rulesets that have registered for a cleanup period should do any necessary cleanup on this event and then raise wrangler:cleanup_finished with their domain to signal their completion. Will have passed through attributes given to wrangler:child_deletion.