Operator Type:
Operator Scope of Action:
Operator Purpose:
Operator First Added:
Operator Altered:
Function [other Function type actions]
Item [operators of similar scope]
Data manipulation [other Data manipulation operators]
Baseline
action(code)
This function allows execution of the code without the need for a return value. This allows an action be set within an attribute, and perform that action as part of a rule or agent action.
For example, the Rule
action('$Color= "bright red"');
will set the note's primary colour ($Color).
Note that that in its simplest form, an action() call is a quote-enclosed string. As action codes tend to use double-quoted strings, it may often be necessary to use single quotes for the outer enclosure, as in the example above.
The action() function returns the evaluated result of the code within it. In the above case if $MyString were set to store the result, the value would be "true"—because the action completed successfully. So, in most cases, there is no requirement for a left-side attribute to accept any output. By comparison, the related eval(expression) function evaluates an expression and returns a value. Whereas eval() is designed to intentionally return an output, action() performs an action such as an assignment.
An action() call can be used with a do(macro) call to create a form of function as macros allow input parameters (its arguments): see do().
The action() call is particularly useful during export where it is desirable to run some action code in the context of the template during template rendering (evaluation)—see more below.
Calling stamp code via action()
If a stamp's code is long/complex it can be convenient to store it in a code note. Thus if a code note 'Test-stamp' held the action code $Colour="red";, then a stamp with the code:
action($Text("Test-stamp"));
when run would result in the stamped note(s) turning red. The example is trivial but shows the technique. Note the offset reference in the stamp to the code note is case sensitive and should use a unique $Name (or else cite the full $Path to the code note). Local attribute references, i.e. $Color or $ChildCount, are bound to the note being stamped: it is not possible to reference values in the code note using a designator.
On-the-fly Attribute references using action()
Occasionally it is necessary to make at attribute value reference string from a variable, i.e. if the variable holds 'Path' the rersult being '$Path' as opposed to the value of $Path. Whilst $MyString refers to the value of attribute MyString, what if the attribute name is itself the value of a variable in the current code? Here action() solves the problem. For instance, if vAnAttr holds as its value the name of an attribute, e.g. "SomeAttribute" then the following does not work:
$MyString = "$" + vAnAttr; WRONG ($MyString is the value of $SomeAtttribute)
as $MyString is not set to the value of $SomeAttr. Instead use action():
action('$MyString = "$" + vAnAttr'); CORRECT ($MyString is the string '$SomeAtttribute')
To build a series of $-prefixed attribute references in a loop, use action() instead of eval(), as described in more detail here.