Appendix 3: Actions and Rules
| Tinderbox User's Manual : Appendix 3: Actions and Rules |
Appendix 3: Actions and Rules |
|
Tinderbox agents, containers, and adornments can have actions which modify notes when they are found by the agent, added to a container, or move onto an adornment. Tinderbox notes may also have rules, which are continually applied to that note.
Actions and rules are case sensitive; “Red” and “red” are distinct.
Strings in actions and rules may be enclosed in either single or double quotes.
Comparison operators include:
= < ≤ > ≥ ≠ !=
The left-hand side of a comparison is always an attribute name; it may be preceded by a '$' character. If the left-hand side contains an argument, is must be preceded by a '$'.
Color=red;
$Color=red;
$Color(this)=red; Identical to above
$Color(parent)=red;
Color(parent)=red; Wrong!
The right-hand side of a comparison may be a numerical constant, a string constant (which may be enclosed in optional quotation marks), or an attribute reference.
An attribute reference is an attribute name, optionally followed by an argument that designates a specific note. If the argument is absent, this is assumed.
$Color="red"
$Color=$BorderColor
$Color=$Color(parent)
If the attribute reference refers to a specific note, it may refer to the note:
by the note's name, which should be unique
by the note’s path (/container/note name) or (../name)
an expression ($path+"/details")
by keyword: this, agent, next, previous, nextSibling,
prevSibling, firstSibling, lastSibling, parent, grandparent, child, lastChild, randomChild, cover
The keywords used in queries are identical to those used in actions (Appendix 4), with the addition of the keyword agent, which refers to the agent which is currently querying the note.
Parenthesis may be used to group multiple queries together, using logical operators &(and), | (or), and ! (not).
Regular expressions can be used to search for text patterns in any attribute, but are most frequently used to search for strings or patterns in Text and Name. A regular expression query begins with the name of an attribute, followed by a parenthesis containing the pattern:
Text(pattern)
Note that the '$' prefix is not used in regular expressions. $Text(parent) is the text of the nhote's parent, whilst Text(parent) is a regular expression.
Any expression can be a query, common queries include the following:
contains( name of note )
descendedFrom( name of note )
inside( name of note )
first( name of note[,count] )
last( name of note[,count] )
between( attribName,minimum,maximum )
linkedFrom( name of note )
linkedTo( name of note )
indented( count )
similarTo( name of note ) — finds notes whose text is most similar to the text of the named notes. Similarity is based on the number of words that appear in both texts, weighted to give more weight to words that are less common in the rest of the document.
word( pattern ) — finds notes that contain the pattern string. No regular expressions are allowed, but word() is much faster than searching for a regular expression.
An attribute reference may stand alone as a query. For example, if Urgent is a boolean user attribute, the query
$Urgent
finds all urgent notes.
If the attribute is Boolean, the query is true if the value is true. If the attribute is a string, the query is true if the string is not empty and not the string "false". If the attribute is a number, the query is true if the value is not zero. If the attribute is a date, the query is true if the value is not "never".
ACTIONS
An action changes the value of an attribute. For example,
$Color="red"
sets the color of this note to "red". Several actions may be combined, setting them apart with semicolons.
$Color="red";$BorderColor="bright red"
The final semicolon is optional. Note that values with spaces should be enclosed in quotes.
If the right-hand side of the action is empty, the attribute will be restored to the value it inherits from its prototype, or to the default value.
$Color=;
The assignment operator |= assigns a new value to an attribute only if the attribute does not currently have a value. For example, the action
$Project |= $Project(parent)
will set a note's project to be the same as its parent's project, provided the note doesn't already have a project.
For boolean attributes, |= performs the assignment if the current value is false. For string attributes and set attributes, |= performs the assignment if the current value is empty. For numbers, |= performs the assignment if the current value is zero. For dates, |= performs the assignment if the current value is "never".
The assignment operator &= assigns a new value to an attribute only if the attribute already has a value;
Conditional actions can perform any query before proceeding, and make their action contingent upon that query.
if(query){ action }
if(query) { action } else { action }
The right side of an action always refers to an attribute name preceded by a '$', and followed by an optional argument to designate which note is to be referred to.
Color=$Color(parent)
The '$'symbol is optional on the left-hand side, which always refers to an attribute name, unless the left-hand side designates a target node.
$Color="red"; (preferred)
Color="red"; (deprecated)
$Color(parent)="red"
Attribute references normally refer to this note, but may refer to another note by name or keyword:
this the current note
current the note Tinderbox is currently exporting. Where a note is exported to its own page, current is the same as this. If a note includes children or other notes, however, current differs from this in the included notes. (When it appears outside of an export template, like in an agent or container action, current is always synonymous with this.)
source the link source (used only in link expressions)
destination the link destination (used only in link expressions)
next the note after the current note, in outline order
previous the note preceding the current note, in outline order
prevSibling the next older sibling of the current note
nextSibling the next younger sibling of the current note
firstSibling the first sibling of the current note, in outline order
lastSibling the final sibling of the current note, in outline order
parent the parent of this note
grandparent the parent of the parent of this note
child the first child of this note
lastChild the last child of this note
original in aliases, refers to the original note associated with the alias and useful for addressing properties of the original such as Xpos and Ypos that are not inherent to the alias. Otherwise synonymous with this.
randomChild a randomly selected child of this note
cover the first note in the document. This is the first note listed in an outline window that shows the whole document.
agent available only in agent actions; refers to the agent that is currently examining the note
Attribute references can also refer to another note through its unique name
$Price(WonderfulRedWidget)
or a path to the note
$Text(/catalog/widgets/red/wonderful/price)
When agents search for regular expressions, the agent saves substrings that matched portions of the search expression. These substrings or back references can be used in actions, and are especially useful for automatically extracting information from notes.
For example, an agent might search for notes that contain fields like this:
From: Henry Higgins
by searching for the pattern
From: (.+)$
An action can then refer to the name extracted following "From: " as $1
$Author=$1;
The author will now be set to Henry Higgins. Subsequent subexpressions may be referred to as $2, $3, and so on.
If the right hand side of an action begins with the character ^, the rest of the action is interpreted as a template expression. For example,
Msg=^ See ^getFor(parent,Name)’s son ^get(Name);
The use of template expressions in actions was formerly common but is now seldom if every necessary. Template expressions in actions are now deprecated.
If you wish to use a template expression to construct a complex string, see exportedString() under string functions.
If the right-hand side of an action begins with the character `, the rest of the action is treated as a command that is passed to the Mac OS X command line. The command is executed by the C shell, and the standard output is returned. For example,
$Text=`perl -v
would replace the note's text with the a string describing the version of perl installed on this computer. More usefully,
$Text=`curl http://example.com
would set the text to whatever information is available at the stated URL. Attribute references are interpolated in shell expressions, so
$Text=`curl $URL
would fetch the data for whatever location is stored in the note's URL attribute.
For more complex actions, the runCommand function is often more convenient.
$Text = runCommand(command_line, input)
runCommand() executes the specified command line in csh, passing it the result of evaluating input. The standard output of the command, if any, is the value of the completed action.
Each attribute has a single type, which determines what kind of information that attribute contains.
boolean
color
date
file
number
set
string
When Tinderbox actions assign a value to an attribute, that value is coerced to the appropriate type. If you assign a string to a color attribute, for example, Tinderbox will try to interpret the string as a color.
$BorderColor="rgb(200,150,120)"
Occasionally, the same operator has different meanings when acting on different types of data. For example, "+" adds numbers but concatenates strings:
$Total=$BasePrice+$Tax; (result: 17.95)
$Name=$Topic(parent)+":"+$Topic; (result: Waterfowl:Loons)
In an assignment, the governing type is the type of the left-hand side.
In an expression or a query, the governing type is the type of the left-hand operand (for binary operators like +) or the sole operand (for unary operators).
Three functions encode strings for use in different contexts.
urlEncode("the string")
utf8("the string")
escapeHTML("the string")
idEncode("the string")
urlEncode converts a string to urlEncoded form, for use in HTML links. Characters that are illegal in URLs are encoded as '%' followed by the corresponding hexadecimal character code.
utf8 converts a string to unicode.
escapeHTML converts HTML and XML special characters to XML entities. For example, '<' is replaced by '<' and '&' is replaced by '&'.
idEncode converts a string to form suitable for use as an HTML identifier. Punctuation and other charactersthat arte neither letters or digits are replaced by underscores.
These functions will be useful in preparing data for use with other programs and Web services via runCommand.
format(value,format_string)
The argument what is usually an attribute reference or expression. For example:
format($Created,"L")
gets the note's creation date and formats it as a "long local date" such as "Sunday, March 23, 2007 1:26pm".
The meaning of format_string depends on the type of object represented by value.
If value is a date, the format string is the same as the format used by Tinderbox's date export codes.
If value is a set, the format string is the delimiter used to separate set elements
format($KeyAttributes,",")
converts key attributes to a comma-separated list. Optionally, you may supply five arguments to format the set as an HTML list:
format(what,list-prefix,item-prefix,item-suffix,list-suffix)
For example
format(what,"<ul>","<li>","</li>","</ul>")
If what is a number, then the arguments are numeric and interpreted as follows:
format(value,precision, width)
For example, if $myNum is 3.1415927, then
format($myNum,2,7) is " 3.14"
format($myNum,2) is 3.14
format($myNum,0) is 3
In quoted string arguments here (as elsewhere), \" is converted to a quotation mark, \n to a carriage return, and \t to a tab.
exportedString(note,templateFile)
exportedString(note,templateString)
The first form of exportedString takes a reference to a note and the name of a file in the HTML Export Template folder, and returns the result of applying the template to the note. The second form requires no external file; instead, its second argument is the template string itself.
exportedString(this,"^getFor(parent,Name)")
or
exportedString(this,$MyTemplate)
For more information about HTML Export and markup Tinderbox uses for this process, see the HTML Templates chapter of this manual and Appendix 4.
Rules and actions may use macros through the do() function:
do(macro[,arg1,arg2,arg3] )
The first argument is the name of the macro. Subsequent 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 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.
do(Instructions);
simply executes whatever actions are returned by Instructions.
The eval() function evaluates an expression and returns the result. For example,
eval($Price*1.05)
returns the value of price augmented by 5%.
The familiar binary operators + - * /operate on numeric expressions in the expected way. Note that +and -have different meanings when applied to sets, and that +has yet another
meaning (concatenation) when applied to strings.
log() computes the natural logarithm of its argument, which should be a number, a numeric attribute, or an expression that can be interpreted as a number.
sqrt() computes the square root of its argument.
abs() computes the absolute value.
round() rounds the value to the nearest integer.
sin(), cos(), and tan() are the familiar trigonometric functions, taking arguments in radians.
atan() computes arctangent, and returns its result in radians
mod(a,b) computes the remainder of a divided by b.
radians() converts its argument, in degrees, to radians.
rand() returns a pseudo-random number between 0 and 1
Two operators add sums for lists of notes.
sum(what,expression)
computes the sum of a series of expressions. For example,
sum(child,$WordCount)
computes the total word count of all the children of a note. where may be any of {child,descendant,sibling,ancestor,all}. In addition, what may take a single argument that designates a particular note other than this; for example
sum(child(/agents/books),$TextLength)
sum_if(what,condition,expression)
avg_if(what,condition,expression)
computes the sum or the mean of a value computed in each note for a group that meets the designated condition. For example:
sum_if(child,$Qty>0,$Qty*$Price)
avg_if(child,$Qty>0,$Qty*$Price)
A set is a list of strings or tags, separated by semicolons. A given tag can appear in a set at most once; duplicates are automatically removed. The order of elements in a set is not significant.
Two sets are equal if they contain the same tags.
The +and -operators have special significance for sets. +adds one or more tags to the set, if they are not already contained in the set.
"dogs;cats" + "cats;mice" is "dogs; cats; mice"
- removes items from a set, if those items are currently contained in the set.
"dogs;cats" - "cats;mice" is "dogs;"
Several functions are useful for extracting notable elements from sets.
count() returns the number of tags in a set
max() returns the largest tag in a set. (If max() is evaluated in a numerical context, numerical comparison is used. Otherwise, Tinderbox uses lexical comparison)
min() returns the smallest tag in a set.
Several functions construct sets from a group of notes.
collect(what,expression)
builds a set by visiting each note described by what and adding the value of the designated attribute to the set. For example,
collect(child,$Name)
constructs a set with the name of each child of the note.
what may be any of {child,descendant,sibling,ancestor,all}. In addition, what may take a single argument that designates a particular note other than this; for example
collect(child(/agents/books),$Name)
expression can be any expression, but is typically an attribute. For example,
collect(child,$Name)
collect(child,$Width*$Height)
collect_if(where,condition,expression)
constructs a set by collecting all the notes corresponding to where, testing each note to see if it meets condition, and adding the expression to the set for each such note. For example
collect_if(child,$Status="Important",$Name)
will construct a set of the names of all of this note's important children.
Note that collect_if is related to agents; many tasks you might perform with collect_if could be done as well, or better, with an agent.
The links operator builds a set from a collection of links. For example
$MySet=links(/config).outbound.supports.$Name
constructs a set of all the Names of notes that are linked to the top-level note named config via links of type "supports".
$MySet=links.inbound..$Name
collects a set of all the names of notes that are linked to this note.
links[(note)].kind.linkType.attribute
note selects which note's links should be collected. If omitted, "this" is implied. note may be a keyword (e.g. "parent") or a note path (/config/details)
kind is one of the keywords "inbound", "outbound", or "web"
linkType collects only links of a specified link type. linkType is a regular expression: wild-card characters are permitted and have special meanings. If the linkType contains white space or periods, enclose it in quotes:
links.outbound."responds to".$Name
If linkType is left empty, links of all types are collected with the exception of prototype links. Prototype links are always omitted.
attribute is the name of the attribute whose values are to be collected in the result.
Keep in mind that a set contains unique values. If several notes have identical names, then
$MySet=links.inbound..$Name
will list the distinct names, and so will have fewer elements than the number of links.
Converting strings to colors
Tinderbox provides several flexible notations for interpreting colors.
Named colors are always the preferred way to set and change colors in Tinderbox. Named colors may be redefined, and new named colors added or deleted, in the Colors pane of the Attributes window (Cmd-2)
Hex colors, customarily used on the Web, begin with a # sign followed by six hexadecimal digits: #rrggbb, corresponding to the proportion of red, green, and blue in the color. #FFFFFF is white, #800000 is dark red, and #000000 is black.
RGB colors of the form RGB(red,green,blue) use decimal colors from 0 to 255 to describe the proportion of red, green, and blue in the color.
HSV colors of the form HSV(hue,saturation,value) describe the hue, saturation, and value of the color. Hue is a color wheel angle, in degrees, running from 0 to 360. 0 corresponds to red, 120 to blue, and 240 to green. Saturation and value run from 0 to 100.
Manipulating colors
RGB(red,green,blue)
RGB() creates a color. Its arguments are integers ranging from 0 to 255. Arguments may also be expressions or attribute references.
$Color=RGB($MyRed,255,255)
brightness(color,value) returns a modified color that has the same hue and saturation as the original color, but that has reduced brightness. The range of value is 0 to 100.
brightness(color) returns the brightness of a color, as a numeric value from 0 to 100.
saturation(color,saturation) returns a modified color that has the same high and brightness as the original color, but has a reduced saturation. The range of saturation is 0 to 100.
saturation(color) returns the saturation of a color, as a numeric value from 0 to 100.
hue(color,value) returns a modified color that has the same brightness and saturation as the original color, but has a different hue. The range of hue is 0 to 360.
hue(color) returns the hue of a color, as a numeric value from 0 to 360.
date(year,month,day,hour,min) constructs a date from individual numeric elements -- useful, for example, if you need to assemble a date from separate attributes. year is the 4-digit year, month is a number from 1-12. The time arguments are optional, and are specified in a 24-hour clock.
date(2004,7,23,16,45) is 23 July 2004 4:45pm
date("string") constructs a date from a string or string expression. Usually, this is not necessary; Tinderbox will coerce the string to a date type automatically. In some contexts, though, it may be more convenient or more clear to make the conversion explicit. (See format() to convert dates into strings)
day(theDate) returns the day of the month from the date expression. If $Date is July 4, 2009 then day($Date) is 4.
day(theDate,val) creates a new date based on theDate, but in which the day of the month is val. theDate is not changed. If $Date is July 4,2009, then $NewDate=day($Date,5) will set NewDate to July 5, 2009.
month(theDate) returns the month from the date expression. If $Date is July 4, 2009 then month($Date) is 7.
month(theDate,val) creates a new date based on theDate, but in which the month is val. theDate is not changed. If $Date is July 4,2009, then $NewDate=month($Date,5) will set NewDate to May 4, 2009.
time(theDate) returns the time from the date expression.
time(theDate,hours,minutes) creates a new date based on theDate, but in which the time is set by hours and minutes. theDate is not changed.
days(date1,date2) returns the number of days that elapsed between date1 and date2.
Boolean operators & | ! operate as expected. Boolean assignment (and queries) coerce non-boolean attributes to either to or false.
number: zero is false and any non-zero is true.
string: "" and "false" are false, other values are true
set: empty sets are false, all others are true
date: "never" is false, all others are true
color: black (RGB(0,0,0)) is false, others are true
Logical group operators examine a group of notes and determine whether every note in the group meets a criterion, or if any note does.
every(group,expression)
any(group,expression)
group describes the notes to be examined. group may be any of {child,descendant,sibling,ancestor,all}. In addition, group may take a single argument that designates a particular note other than this; for example
collect(child(/agents/books),$Name)
expression may be any valid expression, but is most often a reference to an attribute.
every(child,$status=important)
any(child,$overdue)
| Up: Tinderbox User's Manual | |
| Previous: Appendix 2: Regular Expressions | Next: Appendix 4: HTML Export Codes |
