This version is out of date, covering development from v8.0.0 to v8.x.x. It is maintained here only for inbound reference links from elsewhere. It is no longer actively updated.

Jump to the current version of aTbRef

Tinderbox v8 Icon

Rules

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.