do(macroStr[,argumentsList])

---

do(macroStr[, argumentsList])

The do() operator do lets rules and actions use macros. Action code macros cannot, generally, evaluate action (or export) code within the macro itself and so might best be thought of sections of boilerplate text with configurable text inputs.

do() always returns an output (string) and so will expect a left side attribute. To do something useful with the output consider wrapping the it in an eval() call. Assume macro "Hello world" has the code: "Hello $1!". Then:

$ReturnString = eval(do("Hello world","Nibbler")); 

would set a $ReturnString value of "Hello Nibbler!".

Alternatively, if the macro is written so the left side is included, action() can be used. Macro "Hello world2" has the code: $ReturnString = "Hello $1!". Using the macro thus:

action(do("Hello world2","Cubert")); 

which would set a $ReturnString value of the current note to "Hello Cubert!". Notice how action() requires no left-side receiving attribute as there is no direct output. The assignment to $ReturnString occurs within the macro; the assigned attribute being whatever system/user attribute the user decides, it is not a fixed output assignment.

An offset within an action call is also possible. Macro "Hello world3":

$ReturnString('$2') = "Here's $1!"; 

Use the macro thus:

action(do("Hello world3","Calculon", "All My Circuits")); 

which would set a $ReturnString("All My Circuits") to "Here's Calculon!".

Note that if an input is itself an expression, it may prove beneficial to evaluate it before insertion into the macro. Why? It may affect outcome if the context of the input evaluation and the output evaluation differ, e.g. where the reference 'this' might refer to a different note in each context.

do(macro[,arg1,arg2,arg3] )

The first argument is the name of the macro. Subsequent argumentsList (comma delimited) arguments are optional and are passed to the macro, which can refer to them as $1, $2, $3, and so forth.

After the macro is evaluated, its result string is returned and is parsed again as a rule, action, or expression. For example:

$Name|=do(computeName,$Name,$Name(parent)); 

sets name to the result of a macro called computeName. This if the macro code were:

$2: $1 

Then, if $Name were "mammal" and $Name(parent) were "horse", the result on the above call would be a new $Name of "mammal: horse"

do(Instructions); 

simply returns whatever text is stored in a macro called Instructions.

Macros cannot be used in agent queries (this was supported in early versions).

Macros called in action code via do() do not evaluate any embedded export codes. This is because such behaviour is reserved for export use.