A Rule is an action, much like an agent action, but while agents act on other notes a Rule acts on it own note (and only that note). If a rule is desired that only runs occasionally, consider using an edict instead
Rules are actions attached to notes and containers. Agents may have rules.
A note or agent's rule is stored in $Rule.
Rules are run periodically, and change the note's attributes. For example, suppose we have a Boolean attribute called $Urgent. A note might have a rule
$Urgent=any(children,$Urgent)
…meaning, "this note is urgent if any of its immediate children are urgent."
Another rule might be
$Urgent=$Urgent(parent)
…meaning, "this note is urgent if its parent is urgent."
Given that rules run periodically, Tinderbox will eventually enforce each rule, although there may be a delay between a change made to one note and its impact throughout the document depending on the agent update (cycle) time, i.e. in complex TBXs the update time may be a little slower.
Notice, too, that contradictory rules can be written; this may lead to constant changes in the document and should be avoided.
Agents can have rules and this is especially useful for highlighting agents under specified circumstances (e.g. if $UrgentTasks is not empty, or if $ThingsToDo find more than seven tasks in your inbox).
Like actions, rules may use simple arithmetic and logical expressions as well as action code functions.
If there are a lot of rules running, especially if complex ones, it is a good idea to use a logical OR (|=) rather than a normal assignment (=). The |= method ensures the rule is only run if the left side equates as empty. An alternate solution is to use a Boolean 'guard' attribute and an if() test to ensure the running of the rule is controlled. This is a specimen such Rule:
if($ShouldRun){$SomeAttribute=eval([some expression]);$ShouldRun=false}
Note how the rule only runs if $ShouldRun is true and that once the run is run, $ShouldRun is set to false. This allows for some other action or rule to reset $ShouldRun and allow the rule to run one more time.
Rules can be disabled locally in a note using $RuleDisabled. The most common application of this is with prototypes where it is desired to run a rule in inheriting notes but not in the prototype itself.
Editing $Text or Displayed Attribute values will cause the note's rule to be run.
See also—notes linking to here: