Operator Scope of Action:
Operator First Added:
To make it easier to write rules succinctly, you may use the assignment:
$TheAttribute |= the_expression;
…which sets $TheAttribute to the value of the_expression if it is already
true OR if the_expression is
true. An attribute that has no locally set (or inherited) value is evaluated as
false. Thus there are two possible outcomes:
- if $TheAttribute is set to a value that evaluates (the left side of the code) as
true. Therefore, regardless of the state of the_expression, the_expression (the right side of the code) is not evaluated and $TheAttribute retains its current value.
- if $TheAttribute is set to a value evaluates (the left side of the code) as
false. Therefore the_expression (the right side of the code) is evaluated. If the_expression evaluates as
true$TheAttribute takes the value of the_expression. On subsequent iteration of the code $TheAttribute thus evaluates as
true. But, if the_expression evaluated to
false, both it and the overall action evaluate as
false, i.e. $TheAttribute's value remains unchanged.
In practical terms this means the left side, usually an attribute, is set to the right side value only if it is not already set locally at note level. This is because for most attributes, especially new user attributes, the default value will evaluate as
false. But, $TheAttribute's data type does not have to be Boolean.
For new String-type attributes (and string-based Action/Color/File/Font/Interval/List/Set/URL types) the default is an empty string "". For Number-type, is it 0 (zero). For Date-type, it is the string "never". For Boolean-type, is it 'false' (with no quotes, and shown as un-ticked if displayed via a tick-box). The "", 0 and "never" values—for the appropriate data types—evaluate as
false. But, be aware that not all system attributes follow this assumption. For instance, the $Color default is preset to use a named Tinderbox colour, so its default value (even if inherited) would evaluate as
Prototypes have no direct effect as the outcome, as it initially depends on the evaluation of the left-side attribute value regardless of whether document default, prototype inherited or locally set.
This operator's behaviour makes the |= usage very useful for doing tasks like making code run only once; on the second pass the left side already has a value so no change occurs. This avoids scenarios like successive applications of a rule causing multiple concatenation of strings (one extra each iteration).
For example, for the Boolean-type attribute $Urgent:
$Urgent |= any(children,$Urgent)
A project is urgent if it has been declared to be urgent itself, or if any child is urgent.
If using |= assignments, it can be useful to have a means to reset an attribute to default to re-enable |= value assignment.
See also the logical AND assignment.