action([scope,]codeStr)

---

action([scope, ]codeStr)

action(codeStr)

This function allows execution of the codeStr 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. From v9.5.0, an additional optional scope argument was added allowing the action to be run on a note other than the current note

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 codeStr 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 arguments (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 address 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 result 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.

action(scope, code)

From v9.5.0, if an optional first scope argument is provided, the code is not run on the current note but on that defined by scope (defining scope). Thus:

action("Some note","$Color = 'blue';"); 

will set the colour of note "Some note" to blue.

This option can avoid needing to use offset references in code, especially if the offset address is being defined by a variable.