Mutating Persistents in the Postlude

To be useful, persistent variables must be mutated. Persistents can only be mutated in the postlude.

Engine Compatibility

The syntax for use with the node pico engine differs. There is no clear (but you can assign a null), and setting is done with a := infix operator.

The following statements mutate persistent variables:

clear <pvar>. This deletes the persistent variable <pvar>.
set <pvar> <expr>. This sets the value of <pvar> to the value of the expression (literal).

If the persistent variable is bound to a complex data structure (i.e. maps and arrays), <pvar> can contain a hash path referencing part of the structure.

For historical reasons, if the persistent variable does not exist before it is used, the default value is 0.

This means that the isnull() operator, for example, is never true for an entity variable.

Numbers don't behave well as persistent variable indexes for maps. This is due to the underlying Mongo implementation treating them as array references rather than as map (hash) keys. In general, prepending or appending a string to the number will fix the problem.

Examples

For classic KRE:

fired {
  set ent:a 1
  set app:b{"foo"} 1 + my_var
  set app:b{["flip", "flop"]} "this is a string"
  clear c
}

This blog post has a detailed example of using persistent variables to create a personal data manager.

For the node pico engine:

fired {
  ent:a := 1;
  app:b{"foo"} := 1 + my_var;
  app:b{["flip", "flop"]} := "this is a string";
  ent:c := null
}

Deprecated

The following are deprecated and should not be used.

There are several persistent statements that are deprecated.

<pvar> (+=|-=) <expr> from <expr>. This increments (or decrements) the persistent variable <pvar> by the value given by the first expression. If the value is null when the statement executes, the value of the second expression is used to initialize the persistent.
mark <pvar> with <expr>. This marks the trail <pvar> using the value of the expression as the place.
forget <regexp> in <pvar>. This forgets any places in the trail matched by the regular expression.