Expressions

This is Tinderbox Cookbook version 2.0.1, created in conjunction with Tinderbox 7.0.1.

The locale settings used to export this document: en-GB. Most date tests were written/tested on a UK day/month order system and thus tests may fail if exported using different locale settings.

This page explores Tinderbox expressions, used in actions, rules, and with the export templates ^action()^ and ^value()^.

Deprecation. Some codes are now marked 'deprecated'. This means that while they may still work, such syntax should be avoided. New documents should not use such syntax and existing documents in regular use should be have their code reviewed to avoid retaining deprecated usage.

[Attribute]() - find value

Tests whether a regular expression can be found in an attribute of a note.

Deprecated - use .contains/.icontains.

See the original tests on the deprecated code page.

abs

computes the absolute value of a number.

Wiki: Math

description try expect result ok
abs(5) 5 5 not yet
abs(-5) 5 5 not yet
abs(1-6) 5 5 not yet

untitled

This function allows execution of code without the need for a return value.

any()

scans each item of a group to see whether any of those items meets a criterion. Data are taken from the following example:

Name UserFlag UserNum
apple true 12
pear false 3
lemon false 3
lime true 2

Wiki: Groups

description try expect result ok
any(children,$UserNum<100) true true not yet
any("children",$UserNum<100) true true not yet

logical

any(children,$UserNum>10) true true not yet
any(children(/data/fruit),$UserFlag) true true not yet
any(children(/data/fruit),$UserNum<0) false not yet

Using a literal list of paths

any("/data/fruit/apple;/data/fruit/pear;/data/fruit/lime",$UserFlag) true true not yet

String comparison

any(children(/data/fruit),$Name=="pear" false not yet

String comparison

any(children(/data/fruit),$Name=="mango" false not yet

atan()

compute the arctangent of a number; the result is reported in radians.

Wiki: Math

description try expect result ok
atan(1).format(6) 0.785398 0.785398 not yet
format(atan(0),2) 0.00 0.00 not yet
atan(-1).format(6) -0.785398 -0.785398 not yet

attributeEncode

XML/OPML-safe encoding of attribute values:> The following characters are converted to numeric HTML entities (e.g. like '&#10;'): left angle bracket, right angle bracket, ampersand, (straight) double quote, (straight) apostrophe, and line feed character (ASCII #10).

description try expect result ok

This is paragraph 1.

This is paragraph 2.

attributeEncode($Text) This is paragraph 1. This is paragraph 2. This is paragraph 1. This is paragraph 2. not yet

This 'is"

This & is >paragraph 2.

attributeEncode($Text) This 'is" <paragraph 1. This & is >paragraph 2. This 'is" <paragraph 1. This & is >paragraph 2. not yet

avg

Computers the mean of a numeric attribute for a group of notes. The data are the following:

Name UserFlag UserNum
apple true 12
pear false 3
lime true 2

Wiki: Groups

description try expect result ok

Computes the mean of all children

avg(children,$UserNum).format(5) 5.66667 5.66667 not yet

Computes the mean of all children

avg("children",$UserNum).format(5) 5.66667 5.66667 not yet

Computes the mean of the squares: 144+9+4

avg(children,$UserNum*$UserNum).format(5) 52.3333 52.33333 not yet

Using a literal list of paths

avg("/data/fruit/apple;/data/fruit/pear;/data/fruit/lime",$UserNum).format(5) 5.66667 5.66667 not yet

avg_if()

Computers the mean of a numeric attribute for a group of notes. The data are the following:

Name UserFlag UserNum
apple true 12
pear false 3
lime true 2

Wiki: Groups

description try expect result ok

Compute the means for only those children where $UserFlag is true

avg_if(children,$UserFlag,$UserNum) 7 7 not yet

Compute the means for only those children where $UserFlag is true

avg_if("children",$UserFlag,$UserNum) 7 7 not yet

Compute the means of only the children where $UserNum is less than 12

avg_if(children,$UserNum<12,$UserNum) 2.5 2.5 not yet

Using a literal list of paths

avg_if("/data/fruit/apple;/data/fruit/pear;/data/fruit/lime",$UserFlag,$UserNum) 7 7 not yet

between(value,min,max)

A value lies between a specified minimum and maximum. The value may be equal to min but must be less than max. Thus between 1 and 10, means 1.0 to 9.999...etc. and not 1.0 to 10.0.

description try expect result ok

True - 5 us between 1 and 10

between(5,1,10) true true not yet

True: 1 is within value range 1-10.

between(1,1,10) true true not yet

True: 10 is not within range 1-10.

between(10,1,10) false not yet

Expected fail

between(1,5,10) not yet

$TestNumber = 5, $UserNum = 1, $UserNum2 = 10

between($TestNumber,$UserNum,$UserNum2) true true not yet
between(dogs,cats,lions) true true not yet
between(cats,dogs,lions) not yet
between("4/15/2009","4/1/2009","5/1/2009") true true not yet

Test value matches min

between("4/15/2009","4/15/2009","5/1/2009") true true not yet

Test value matches max.

between("4/15/2009","4/1/2009","4/15/2009") false not yet

$TestDate = 15/04/2009, $Date = 01/04/2009, $Date2 = 01/05/2009

between($TestDate,$Date,$Date2) true true not yet

$TestDate = 15/02/2009, $Date = 01/04/2009, $Date2 = 01/05/2009

between($TestDate,$Date,$Date2) false not yet

brightness(color)

return the relative brightness, on a scale of 0-100, of a color.

Deprecated - use Color.brightness.

See the original tests on the deprecated code page.

capitalize()

Transforms a string or attribute to use initial capitals.

description try expect result ok

Doing so causes the argument not to be processed

capitalize("frosty friday") Frosty Friday Frosty Friday not yet

DEPRECATED - quote string literals.

capitalize(frosty friday) Frosty Friday Frosty Friday not yet

Use a literal string. Only the initial letters are capitalised.

capitalize("fROSTY fRIDAY") FROSTY FRIDAY FROSTY FRIDAY not yet

Use a literal string. Only the initial letters are capitalised.

capitalize("frOSTy friDaY") FrOSTy FriDaY FrOSTy FriDaY not yet

Refer to value of $UserString from previous test.

capitalize($UserString(prevSibling)) Frosty Friday Frosty Friday not yet

ceil()

Rounds the input number upwards to the nearest integer: i.e. ceil(5.1) is 6.

description try expect result ok
ceil(5.1) 6 6 not yet

$TestNumber = 5.1

ceil($TestNumber) 6 6 not yet
ceil(5.1+1) 7 7 not yet

collect()

Construct a set of the unique values of an attribute of a collection of notes. Sample data are taken from the following:

Name UserFlag UserNum
apple true 12
pear false 3
lemon false 3
lime true 2

Wiki: Groups

description try expect result ok

Collect names

collect(children(/data/fruit),$Name) apple;pear;lemon;lime apple;pear;lemon;lime not yet

Collect names - quoted offset designator

collect("children(/data/fruit)",$Name) apple;pear;lemon;lime not yet

Collect names - quoted designator

collect("children",$Name) apple;lime;pear apple;lime;pear not yet

collect() doesn't support explicit literal lists.

collect("/data/fruit/apple;/data/fruit/pear;/data/fruit/lime",$Name) apple;pear;lemon;lime apple;pear;lime not yet

Since v5.6 all 4 values are reported as collect() now returns a list not a (de-duped) set Note that pears and lemons have the same $UserNum.

collect(children(/data/fruit),$UserNum) 12;3;3;2 12;3;3;2 not yet

set should collect positive and negative numbers

collect(children(/data/negatives),$UserNum) 25;2;-0.5;-4 25;2;-0.5;-4 not yet

collect_if()

Construct a set of the unique values of an attribute of a collection of notes, filtered by an expression (the second parameter).

Wiki: Groups

description try expect result ok

Collect only those items of the group that match the criterion

collect_if(children(/data/fruit),$UserNum=3,$Name) pear;lemon pear;lemon not yet

Collect only those items of the group that match the criterion

collect_if("children(/data/fruit)",$UserNum==3,$Name) pear;lemon not yet

Collect only those items of the group that match the criterion

collect_if("children",$UserNum==3,$Name) pear pear not yet

collect only negative values

collect_if(children(/data/negatives),$UserNum<0,$UserNum) -0.5;-4 -0.5;-4 not yet

collect_if() doesn't support explicit literal lists.

collect_if(all,($Container=="/data/fruit/"),$Name) apple;pear;lemon;lime apple;pear;lemon;lime not yet

contains

tests whether a note is among this note's immediate children.

Sample data are taken from the following:

description try expect result ok
eval(/data/fruit,contains("apple")) true true not yet

$UserString(/data/fruit) = lemon

About the test… ⇕
eval(/data/fruit,contains($UserString)) true true not yet
eval(/data/fruit,contains("lion")) false not yet

cos()

Compute the cosine of an angle, in radians

Wiki: Math

description try expect result ok
format(cos(3.1415927/2),2) -0.00 -0.00 not yet
format(cos(3.1415927/4),3) 0.707 0.707 not yet
format(cos(0),2) 1.00 1.00 not yet
format(cos(0.5),2) 0.88 0.88 not yet

count()

counts the number of items in a set

description try expect result ok
count("lions;tigers;bears") 3 3 not yet

date()

convert a string to a date, or construct a date from numeric values for year, month, and day. For the purposes of this test, $Date is 20/01/2009, 00:00.

description try expect result ok

Date is '28 November 2005 03:10'.

date("28 November 2005 03:10") 28/11/2005, 03:10 28/11/2005, 03:10 not yet

$Date is 20/01/2009, 00:00

date($Date+1 day) 21/01/2009, 00:00 21/01/2009, 00:00 not yet

$Date is 20/01/2009, 00:00

date($Date+1 week) 27/01/2009, 00:00 27/01/2009, 00:00 not yet
date(2001,2,3,4,5) 03/02/2001, 04:05 03/02/2001, 04:05 not yet

day()

extract the day of the month from a date. Also, construct a date from an existing date, specifying the day of the month. For the purposes of this test, $Date is 20 Jan 2009 09:00

description try expect result ok
day($Date) 20 20 not yet

$Date is 20 January 2009

day($Date,17) 17/01/2009, 09:00 17/01/2009, 09:00 not yet

$UserNum is 24

day($Date,$UserNum) 24/01/2009, 09:00 24/01/2009, 09:00 not yet

days(start,end)

compute the number of days between two dates.

description try expect result ok

$Date=20 Jan 2009 00:00. $Date2=20 Jan 2008 00:00. Note that this span includes a leap-year day in 2008.

days($Date2,$Date) 366 366 not yet

$Date=20 Jan 2009 00:00. $Date2=20 Jan 2008 00:00

days($Date,$Date2) -366 -366 not yet
days("20/1/2008","20/1/2009") 366 366 not yet

degrees()

Takes an angle specified in radians and returns the angle in degrees.

description try expect result ok
degrees(2).format(3) 114.592 114.592 not yet
degrees(-2).format(3) -114.592 -114.592 not yet
degrees($TestNumber).format(3) 171.887 171.887 not yet

descendedFrom

tests whether the current note is a descendant of a named note.

Sample data are taken from the following:

description try expect result ok

'apple' is descended from 'fruit'.

Uses name as query argument.

eval(/data/fruit/apple,descendedFrom("fruit")) true true not yet

'apple' is descended from 'fruit'.

Uses path as query argument.

eval(/data/fruit/apple,descendedFrom("/data/fruit")) true true not yet

'apple' is descended from 'data'.

eval(/data/fruit/apple,descendedFrom("/data")) true true not yet

'fruit' is not descended from 'apple'.

Uses path as query argument.

eval(/data/fruit,descendedFrom("/data/fruit/apple")) false not yet

'apple' is not descended from a non-existent note.

eval(/data/fruit/apple,descendedFrom("/NoSuchNote")) false not yet

distance()

Returns the distance in map distance between the centres of two notes.

description try expect result ok

Test notes are in /data/map/

distance("Start Note","End Note").toNumber.format(5) 4.94975 4.94975 not yet

$MyString value is "Start Note"

$MyString2 value is "End Note"

distance($MyString,$MyString2).toNumber.format(5) 4.94975 4.94975 not yet

do( theMacro [,argument, anotherArgument, etc.] )

Execute the named macro (macro must already be defined in the current TBX).

escapeHTML()

encode a string in a form suitable for HTML, replacing characters such as '<' and '&' with HTML entities.

description try expect result ok
escapeHTML("<") < < not yet
escapeHTML("Gilbert & Sullivan") Gilbert & Sullivan Gilbert & Sullivan not yet

The expression may be constructed from attribute references or strings.

escapeHTML("Third "+"& "+ (1+2)) Third & 3 Third & 3 not yet

eval()

evaluates an expression

description try expect result ok
eval("1+2") 3 3 not yet
eval("$Name(grandparent)") Expressions Expressions not yet
eval(/data/fruit/apple,"$Name(parent)") fruit fruit not yet

every()

scan each item of a group to see whether all items meets a criterion. Compare any() and collect_if(). Data are taken from the following example:

Name UserFlag UserNum
apple true 12
pear false 3
lemon false 3
lime true 2

Wiki: Groups

description try expect result ok

every note has a positive $UserNum

every(children(/data/fruit),$UserNum>0) true true not yet

every note has a positive $UserNum . Using quoted designator.

every("children(/data/fruit)",$UserNum>0) true true not yet

every note has a positive $UserNum . Using quoted designator and local children.

every("children",$UserNum>0) true true not yet

but some notes have $UserNum less than ten

every(children(/data/fruit),$UserNum>10) not yet

string comparison

every(children(/data/fruit),$Name>"aardvark") true true not yet

exp(N)

Returns the exponential to the power N

description try expect result ok

N.B result is rounded to 6 digits due to key attribute display.

exp(3).format(4) 20.0855 20.0855 not yet
exp(-4).format(7) 0.0183156 0.0183156 not yet

N.B result is rounded to 6 digits due to key attribute display.

exp(4).format(4) 54.5982 54.5982 not yet

exportedString()

applies an export template to a note and returns the result as a string. exportedString() is occasionally useful as a bridge between the export template syntax and Tinderbox's action syntax.

PRETTY CERTAIN THIS BROKEN FOR THE MOMENT

description try expect result ok

This test has the title "example 1".

eval(exportedString(^title^)) example 1 eval(exportedString(^title^)) not yet
exportedString(this,"^title^ ^title(parent)^") placeholder exportedString() not yet

find(query)

Returns a list of one or more path strings to matching items - so can match item or group scope with appropriate query argument.

description try expect result ok

Match a single item

$TestList = find($Path=="/data/fruit/lime")

$TestList /data/fruit/lime /data/fruit/lime not yet

Match all children of a container. Don't use inside() in this context as aliases of notes in the container are also found.

$TestList = find($Container=="/data/fruit/")

$TestList /data/fruit/apple;/data/fruit/pear;/data/fruit/lemon;/data/fruit/lime /data/fruit/apple;/data/fruit/pear;/data/fruit/lemon;/data/fruit/lime not yet

first

tests whether a note is among the first n notes in its container.

Sample data are taken from the following:

description try expect result ok

"apple" is the first child of "fruit"

eval(/data/fruit/apple,first("/data/fruit",2)) true true not yet

"pear" is the second child of "fruit"

eval(/data/fruit/pear,first("/data/fruit",2)) true true not yet

There is no spoon

eval(/data/fruit/spoon,first("/data/fruit",2)) false not yet

firstWord()

Returns as a String the first lexical word of the input parameter - a quoted string literal or a String attribute/expression.

description try expect result ok
firstWord("Now is the winter of our disconent") Now Now not yet

$MyString: Winter is coming

firstWord($MyString) Winter Winter not yet

$MyString(prevSibling): Winter is coming

firstWord($MyString(prevSibling)) Winter Winter not yet

floor()

Rounds the input number downwards to the nearest integer; i.e. floor(5.9) is 5.

description try expect result ok
floor(5.9) 5 5 not yet

$TestNumber = 5.9

floor($TestNumber) 5 5 not yet
floor("5.9") 5 5 not yet
floor(5.1-1) 4 4 not yet

format()

converts dates, strings, numbers, and sets to strings, with various options to determine the presentation of the formatted string.

description try expect result ok

set the number of digits after the decimal point

format(3.1415927,2) 3.14 3.14 not yet

the second argument is optional, and sets the total width of the field. Here, two spaces are added before the '3' to pad the field.

"*"+format(3.1415927,2,6)+"*" * 3.14* * 3.14* not yet

format a set, using the delimiter you prefer. The value of $UserSet is dogs;cats;rabbits.

format($UserSet,"•") dogs•cats•rabbits dogs•cats•rabbits not yet

format a date, using the date format string described in Appendix 5 of the Tinderbox User’s Manual. Here, $Date is 20 Jan 2009 00:00.

format($Date,"W") Tuesday Tuesday not yet

format a date, using the date format string described in Appendix 5 of the Tinderbox User’s Manual. Here, $Date is 20 Jan 2009 00:00.

format($Date,"L") 20 January 2009 20 January 2009 not yet

format a date, using the date format string described in Appendix 5 of the Tinderbox User’s Manual. Here, $Date is 20 Jan 2009 00:00.

format($Date,"l") 20/01/2009 20/01/2009 not yet

format a date, using the date format string described in Appendix 5 of the Tinderbox User’s Manual. Here, $Date is 20 Jan 1709 00:00.

format($Date,"l") 20/01/1709 20/01/1709 not yet

format a date, using the RFC 822 date format string described in Appendix 5 of the Tinderbox User’s Manual. Here, $Date is 1 Dec 2015 12:06. Note the offset is that for 'today' and not the offset on the actual date. To get this sort of format for future or past dates without the offset consider using format($Date,"w, D M y h:mm:s").

An error may occur because the time offset at time of conversion/export is being used rather than the offset for actual date (IOW it has a summer savings time offset for a winter date).

Warning: the time offset is always applied for the current time in the current locale.

format($Date,"*") Tue, 1 Dec 2015 12:06:17 +0000 Tue, 1 Dec 2015 12:06:17 +0000 not yet

format a date, using the ISO 8601 date format string described in Appendix 5 of the Tinderbox User’s Manual. Here, $Date is 1 Dec 2015 12:07.

An error may occur because the time offset at time of conversion/export is being used rather than the offset for actual date (IOW it has a summer savings time offset for a winter date).

Warning: the time offset is always applied for the current time in the current locale.

format($Date,"=") 2015-12-01T12:07:01+00:00 2015-12-01T12:07:01+00:00 not yet

format a date, using the time format string described in Appendix 5 of the Tinderbox User’s Manual. Here, $Date is 2 Apr 2009 09:23.

format($Date,"d D m y Y w W M M0 MM") 2 02 4 2009 09 Thu Thursday Apr 04 April 2 02 4 2009 09 Thu Thursday Apr 04 April not yet

format a date, using the time format string described in Appendix 5 of the Tinderbox User’s Manual. Here, $Date is 11 May 2009 09:23.

format($Date,"t") 09:23 09:23 not yet

format a date, using the time format string described in Appendix 5 of the Tinderbox User’s Manual. Here, $Date is 11 May 2009 09:23.

format($Date,"h:mm") 09:23 09:23 not yet

format a date, using the time format string described in Appendix 5 of the Tinderbox User’s Manual. Here, $Date is 11 May 2009 09:23.

format($Date,"h:mm:s") 09:23:00 09:23:00 not yet

format a date, using the time format string described in Appendix 5 of the Tinderbox User’s Manual. Here, $Date is 11 May 2009 09:23.

format($Date,"H:mm") 9:23 9:23 not yet

format a date, using the time format string described in Appendix 5 of the Tinderbox User’s Manual. Here, $Date is 11 May 2009 09:23.

format($Date,"H:mm p") 9:23 AM 9:23 AM not yet

hasLocalValue()

Tests if an attribute of the current note has a locally set value - true, as opposed to the default/inherited value - false.

Note the argument is a quote-enclosed string name. If a $-prefix is used the value of the referenced attribute is evaluated and that value is expected to be an attribute name.

description try expect result ok

Here $MyString is the default - an empty string.

hasLocalValue("MyString") false not yet

Here $MyString has a value set of "test".

hasLocalValue("MyString") true true not yet

Here $MyString is the edge case where the rather than resetting the attribute has been locally set to an empty string. Previously this could be hard to find via action code.

This does work in Tinderbox itself, error is a problem with the Cookbook's JavaScript logic!

hasLocalValue("MyString") true not yet

Here $MyString holds the name of $UserString and it is the latter that is evaluated. Test #1 - default.

hasLocalValue($MyString) false not yet

Here $MyString holds the name of $UserString and it is the latter that is evaluated. Test #2 - local value. $UserString value is "test".

hasLocalValue($MyString) true true not yet

Here $MyString holds the name of $UserString and it is the latter that is evaluated. Test #2 - local value. $UserString value is "".

This does work in Tinderbox itself, error is a problem with the Cookbook's JavaScript logic!

hasLocalValue($MyString) true not yet

hour()

extract the hour of the time from a date. Also, construct a date from an existing date, specifying the hour of the day. For the purposes of this test, $Date is never

description try expect result ok
hour($Date) 12 12 not yet

$Date is 20 January 2001

hour($Date,12) 20/01/2001, 12:00 20/01/2001, 12:00 not yet

$Date is 20 January 2001 : $UserNum is 12

hour($Date,$UserNum) 20/01/2001, 12:00 20/01/2001, 12:00 not yet

hours(start,end)

Returns the whole number of hours between the start and end times

description try expect result ok

Dates:

$Date 08/01/2010, 15:24

$Date2 08/01/2010, 17:24

hours($Date,$Date2) 2 2 not yet

Dates:

$Date 08/01/2010, 15:24

$Date2 08/01/2010, 17:14

hours($Date,$Date2) 1 1 not yet

Dates:

$Date 08/01/2010, 15:24

$Date2 08/01/2010, 17:24

hours($Date2,$Date) -2 -2 not yet
hours(date("20/1/2009 15:20"),date("20/1/2009 17:25")) 2 2 not yet

hue(color)

computers the hue of a color, expressed as a color-wheel angle from 0 to 360°. Also, transforms a color by changing its hue while leaving its brightness and saturation unchanged.

Deprecated - use Color.hue.

See the original tests on the deprecated code page.

idEncode()

HTML and XML ID's must begin with a number or an underscore. Tinderbox's idEncode() makes it easy to use a $Name or other convenient text attribute as an ID.

description try expect result ok
idEncode("33") _33 _33 not yet
idEncode("try this!") try_this_ try_this_ not yet

indented

returns true if the note is n generations removed from the top of the outline, or from specified ancestor. Useful, for example, for assigning different styles to top-level, secondary, and tertiary outline items.

Sample data are taken from the following:

description try expect result ok

OutlineDepth of fruit is 2

eval(/data/fruit,indented(1)) true true not yet

apple is a child of fruit

eval(/data/fruit/apple,indented(1,"/data/fruit") ) true true not yet

apple is a child of fruit

eval(/data/fruit/apple,indented(2,"/data") ) true true not yet

inside

tests whether a note is one of the immediate children of a container.

Sample data are taken from the following:

description try expect result ok

"apple" is an immediate child of "fruit".

Uses name for 'fruit'.

eval(/data/fruit/apple,inside("fruit")) true true not yet

"apple" is an immediate child of "fruit".

Uses full path for 'fruit'.

eval(/data/fruit/apple,inside("/data/fruit")) true true not yet

"apple" is not an immediate child of "/data"

eval(/data/fruit/apple,inside("/data")) false not yet

fruit is not descended from apple.

eval(/data/fruit,inside("/data/fruit/apple")) false not yet
eval(/data/fruit/apple,inside("/NoSuchNote")) false not yet

interval

Return the days/hours/minutes/seconds, positive or negative between two data times. Outputs Interval-type data which is rendered in the forms:

[neg][days] hh:mm:ss

-2 days 14:12:00

1 day 12:03:00

or, if no days:

[neg]hh:mm:ss

-06:04:00

02:30:00

description try expect result ok

$TestDate: 01/12/2015, 12:35

$MyDate: 04/12/2015, 14:56

interval($TestDate,$MyDate) 3 days 02:21:00 3 days 02:21:00 not yet

$TestDate: 01/12/2015, 12:35

$MyDate: 29/11/2015, 09:04

interval($TestDate,$MyDate) -2 days 03:31:00 -2 days 03:31:00 not yet

$TestDate: 01/12/2015, 12:35

$MyDate: 01/12/2015, 14:56

interval($TestDate,$MyDate) 02:21:00 02:21:00 not yet

$TestDate: 01/12/2015, 12:35

$MyDate: 01/12/2015, 09:04

interval($TestDate,$MyDate) -03:31:00 -03:31:00 not yet

isbn10()

Converts an ISBN-13 code string to an ISBN-10 format number-only string. Dashes or other punctuation will be ignored. If the argument is not a valid ISBN code, the functions return the empty string.

description try expect result ok
isbn10(9781449339739) 1449339735 1449339735 not yet
isbn10("978-1-449-33973-9") 1449339735 1449339735 not yet
isbn10("978 1 449 33973 9") 1449339735 1449339735 not yet

isbn13()

Converts an ISBN-10 code string to an ISBN-13 format format number-only string. Dashes or other punctuation will be ignored. If the argument is not a valid ISBN code, the functions return the empty string.

description try expect result ok
isbn13(1449339735) 9781449339739 9781449339739 not yet
isbn13("1-449-33973-5") 9781449339739 9781449339739 not yet
isbn13("1 449 33973 5") 9781449339739 9781449339739 not yet

jsonEncode()

This operator (added in v5.7.0) returns a JSON-encoded UTF-8 version of a string attribute's value. The straight double quote, solidus (forward slash) and backslash characters are all escaped by a preceding backslash character.

Prior to v5.11.2 the apostrophe (straight single quote) was escaped but this was dropped as it interferes with some AJAX functions in browsers (and is not required by the JSON spec).

description try expect result ok
$MyString.json() Should escape \/solidus, \"double-quote and \\backslash Should escape \/solidus, \"double-quote and \\backslash not yet

last

tests whether a note is among the last n notes in its container.

Sample data are taken from the following:

description try expect result ok

"lime" is the last child of "fruit"

eval(/data/fruit/lime,last("/data/fruit",2)) true true not yet

"lemon" is the second to the last child of "fruit"

eval(/data/fruit/lemon,last("/data/fruit",2)) true true not yet

"apple" is not among the last two children of "fruit"

eval(/data/fruit/apple,last("/data/fruit",2)) false not yet

There is no spoon

eval(/data/fruit/spoon,last("/data/fruit",2)) false not yet

lastWord()

Returns as a String the last lexical word of the input parameter - a quoted string literal or a String attribute/expression.

description try expect result ok

$MyString: Winter is coming

lastWord($MyString)) coming coming not yet

$MyString(prevSibling): Winter is coming

lastWord($MyString(prevSibling)) coming coming not yet

linkedFrom

tests linkage values among a collection of linked notes. The data are taken from the following example:

description try expect result ok

is Louisa linked from Amy by a link of type 'special'?

eval(/data/people/Louisa,linkedFrom("Amy","special")) true true not yet

linkedTo

tests linkage values among a collection of linked notes. The data are taken from the following example:

description try expect result ok

is Amy linked to David?

eval(/data/people/Amy,linkedTo("David")) true true not yet

is Amy linked to Beth by a link of type 'special'?

eval(/data/people/Amy,linkedTo("Beth","special")) true true not yet

linkFrom()

This function creates a link and returns nothing. It can't easily be tested in a cookbook context.

linkFromOriginal()

This function creates a link, always between originals (if/either both linked item s are aliases), and returns nothing. It can't easily be tested in a cookbook context.

links

creates a set of values among a collection of linked notes. The data are taken from the following example:

description try expect result ok

Collect the names of notes linked to Amy by links of type "special"

links(/data/people/Amy).outbound.special.$Name Beth;Louisa Beth;Louisa not yet

Collect the names of notes from Amy regardless of type

links(/data/people/Amy).outbound..$Name Ralph;Jo;David;Beth;Louisa Ralph;Jo;David;Beth;Louisa not yet

Collect the names of notes that link to David

links(/data/people/David).inbound..$Name Amy;Louisa Amy;Louisa not yet

linkTo()

This function creates a link and returns nothing. It can't easily be tested in a cookbook context.

linkToOriginal()

This function creates a link, always between originals (if/either both linked item s are aliases), and returns nothing. It can't easily be tested in a cookbook context.

list()

Creates a list from evaluated arguments

description try expect result ok
list("ant"+"eater",5+2); anteater;7 anteater;7 not yet

$MyString = 'Klaatu ', $MyString2 = 'barada nikto', $TestNumber = '8', $UserNum = '2'

list($MyString+$MyString2,sqrt(2).format(5),$TestNumber / $UserNum) Klaatu barada nikto;1.41421;4 Klaatu barada nikto;1.41421;4 not yet

locale()

Return or set the locale used by TB for date and other formatting.

The second test’s rule is disabled as it otherwise puts unnecessary load Tinderbox’s rule/agent process.

description try expect result ok
locale().tr("_","-") en-GB en-GB not yet

Rule captures current locale value in $MyString2, resets locale to ‘en_US’, tests that has been set, then resets locale to the original value.

Enable the rule if you want to experiment with this test.

$MyString.tr("_","-") en-US en-US not yet

log(argument)

returns the natural logarithm of a number.

Wiki: Math

description try expect result ok
log(2).format(6) 0.693147 0.693147 not yet
round(log(2.7182818284)) 1 1 not yet
log(10).format(5) 2.30259 2.30259 not yet

lowercase()

Transforms a string or attribute to use all lower case.

description try expect result ok
lowercase("FROSTY FRIDAY") frosty friday frosty friday not yet

$MyString = "FROSTY FRIDAY"

lowercase($MyString) frosty friday frosty friday not yet

$MyString = "FROSTY FRIDAY"

lowercase($MyString(prevSibling)) frosty friday frosty friday not yet

max()

returns the largest element of a list (List or Set types). N.B., lists are always a string of semi-colon delimited values, even if the values are numbers. If no context is provided, max() compares elements lexically unless every element is a number.

Wiki: Math

description try expect result ok

If no context is provided, max() compares elements lexically unless every element is a number

max("1;10;3") 10 10 not yet

If no context is provided, max() compares elements lexically unless every element is a number

max("1;10;zebra") zebra zebra not yet

Action: $UserNum=max("1;10;3") . Since max() has a numeric context, it sorts numerically

$UserNum 10 10 not yet

Lexical max works regardless of list position.

max("Winken;Blinken;Nod") Winken Winken not yet

Lexical max works regardless of list position.

max("Blinken;Nod;Winken") Winken Winken not yet

min()

returns the smallest element of a list (List or Set types). N.B., lists are always a string of semi-colon delimited values, even if the values are numbers. If no context is provided, min() compares elements lexically unless every element is a number

Wiki: Math

description try expect result ok
min(apple;pear;grape) apple apple not yet

Action: $UserNum=min("10;2;3"). Since our context is numeric, min() compares items numerically.

$UserNum 2 2 not yet
min("Winken;Blinken;Nod") Blinken Blinken not yet

Action: $UserNum=min("20;2;-0.5;-4")

$UserNum -4 -4 not yet

Test that collect() is correctly passing through positive and negative values.

min(collect(children(/data/negatives),$UserNum)) -4 -4 not yet

minute()

extract the minute of the time from a date. Also, construct a date from an existing date, specifying the minute of the day. For the purposes of this test, $Date is never

description try expect result ok
minute($Date) 44 44 not yet

$Date is 20 January 2001

minute($Date,21) 20/01/2001, 09:21 20/01/2001, 09:21 not yet

$Date is 20 January 2001 : $UserNum is 21

minute($Date,$UserNum) 20/01/2001, 09:21 20/01/2001, 09:21 not yet

minutes(start,end)

Offset in whole minutes between two date/times.

description try expect result ok

Dates:

$Date 08/01/2010, 15:24

$Date2 08/01/2010, 15:14

minutes($Date2,$Date) 10 10 not yet

Dates:

$Date 08/01/2010, 15:24

$Date2 08/01/2010, 15:14

minutes($Date,$Date2) -10 -10 not yet
minutes(date("20/1/2009 15:20"),date("20/1/2009 15:25")) 5 5 not yet

mod

Modulo arithmetic: divides the first argument by the second argument and returns the remainder.

Wiki: Math

description try expect result ok
mod(5,2) 1 1 not yet
mod(4,2) 0 0 not yet
mod(3,100) 3 3 not yet

month()

extracts the month (as a number from 1-12) from a date. With two arguments, converts a date to a new date, replacing the original date’s month by a new month.

description try expect result ok
month("20 January 2009") 1 1 not yet

$Date is 04/07/1985 16:40.

month($Date) 7 7 not yet

$Date is 04/07/1976 16:40.

month($Date,9) 04/09/1976, 16:40 04/09/1976, 16:40 not yet

$Date is 04/07/1976 16:40.

month($Date,month($Date)+1) 04/08/1976, 16:40 04/08/1976, 16:40 not yet

$Date is 04/07/1976 00:00.

month($Date,12+9) 04/09/1977, 00:00 04/09/1977, 00:00 not yet

$Date is 14/07/1789 15:00.

month($Date,month($Date)+12) 14/07/1790, 15:00 14/07/1790, 15:00 not yet

$Date is 14/07/1999 15:00.

month($Date,month($Date)+12) 14/07/2000, 15:00 14/07/2000, 15:00 not yet

$Date is 14/07/1985 16:44. In earlier versions, Tinderbox failed to treat the second argument as a number

month($Date,month($Date)+12) 14/07/1986, 16:44 14/07/1986, 16:44 not yet

months(start,end)

Offset in whole months between two date/times.

description try expect result ok

Positive difference test #1

Dates:

$Date 08/01/2010, 15:24

$Date2 08/03/2010, 17:24

months($Date,$Date2) 2 2 not yet

Positive difference test #2

Dates:

$Date 08/01/2010, 15:24

$Date2 07/02/2010, 17:14

months($Date,$Date2) 0 0 not yet

Positive difference test #3

Dates:

$Date 08/01/2010, 15:24

$Date2 08/02/2010, 15:24

months($Date,$Date2) 1 1 not yet

Negative difference test #1

Dates:

$Date 08/01/2010, 17:24

$Date2 08/03/2010, 15:24

months($Date2,$Date) -1 -1 not yet

Negative difference test #2

Dates:

$Date 08/01/2010, 14:24

$Date2 08/03/2010, 15:24

months($Date2,$Date) -2 -2 not yet

Test using dates in string literal form.

months(date("20/1/2009 15:20"),date("20/3/2009 17:25")) 2 2 not yet

notify()

Send a notification to the OS.

pow(N,K)

Raises N to the power K

description try expect result ok
pow(4,3) 64 64 not yet

N = $MyNumber = 3, K = $TestNumber = 4

pow(3,4) 81 81 not yet

radians()

converts degrees to radians.

Wiki: Math

description try expect result ok
radians(180).format(5) 3.14159 3.14159 not yet
radians(-90).format(4) -1.5708 -1.5708 not yet

rand()

computes a pseudo random number between 0-1

Wiki: Math

description try expect result ok
rand() 0.1391949989549792 not yet
rand() 0.4503474363360309 not yet

a random integer from 0-99

round(100*rand()) 99 not yet

rgb()

constructs a color from separate intensities of red, green, and blue, on a scale of 0-255.

description try expect result ok

50% gray

rgb(128,128,128) #808080 #808080 not yet

dark red

rgb(64,0,0) #400000 #400000 not yet

light green

rgb(200,255,200) #c8ffc8 #c8ffc8 not yet

round(argument)

rounds an number to the nearest integer

Wiki: Math

description try expect result ok
round(4.3) 4 4 not yet
round(-4.3) -4 -4 not yet

runCommand()

provides a link between Tinderbox actions and external programs. Executes a command-line process. The second argument, if supplied, is passed to the new process’ standard input, and the process' standard output is the result of the command.

description try expect result ok

The default working directory for TB’s runCommand is ~, i.e. the user’s home folder.

The actual contents of the user’s home folder may vary from the default (as listed in the expected result).

runCommand("ls") Desktop Documents Downloads Dropbox Library Movies Music Pictures Public Applications Desktop Documents Downloads Dropbox Library Movies Music Pictures Public Sites Untitled.pdf.svg bower_components data.csv data.txt new.txt node_modules single-colum.txt not yet

$URL is http://www.eastgate.com/Tinderbox/config/version

This may need the 'Expected' value to be updated for the current released version. If the 'result' column shows a valid (past) version number this test is, in effect, passed.

In v6, compared to v5, use of curl it is necessary to use the ‘-s’ flag to stop console output being passed back with the actual data retrieved from the URL.

runCommand("curl -f -s "+$URL) 7.0.1 7.0.1 not yet

saturation(color)

computes the saturation of a color — the intensity of its hue, on a scale of 0 (completely neutral) to 100 (intensely saturated). Alternatively, creates a new color whose hue and brightness are unchanged, but with a new saturation.

Deprecated - use Color.saturation.

See the original tests on the deprecated code page.

seconds()

Returns the whole number of seconds between the start and end times

description try expect result ok

$Date has time: 19:05:00 in hh:mm:ss

$Date2 has time: 19:06:35 in hh:mm:ss

seconds($Date, $Date2) 95 95 not yet

similarTo

returns true if this note is similar to the named note.

description try expect result ok

It is for us the living, rather, to be dedicated here to the unfinished work which they who fought here have thus far so nobly advanced.

similarTo("/data/Gettysburg",10) true not yet

sin(argument)

computes the sine of an angle, in radians.

Wiki: Math

description try expect result ok
sin(0) 0 0 not yet
sin(radians(90)) 1 1 not yet
format(sin(radians(45)),3) 0.707 0.707 not yet

sqrt()

calculates the square root of a number

Wiki: Math

description try expect result ok
sqrt(4) 2 2 not yet
sqrt(7*7) 7 7 not yet
(sqrt(2)*sqrt(2)).format(2) 2.00 2.00 not yet
sqrt(-2) -nan nan not yet
sqrt("Hecuba") -nan 0 not yet

substr(data,startN,lengthN)

Return a substring from data, being of lengthN characters from startN position. startN is zero-based. If lengthN is omitted everything from startN to end of string is returned.

substr() does negative indices are not supported - though String.substr() does.

description try expect result ok

$MyString = "Brave New World"

substr($MyString,6) New World New World not yet

$MyString = "Brave New World"

substr($MyString,6,3) New New not yet

$MyString = "Brave New World"

substr($MyString,-5) World World not yet

$MyString = "Brave New World"

substr($MyString,-9,3) New New not yet

$MyString = "Brave New World"

lengthN must be positive.

substr($MyString,-6,-3) New not yet

sum_if()

Adds a numeric attribute for a group of notes. The data are the following:

Name UserFlag UserNum
apple true 12
pear false 3
lime true 2

Wiki: Groups

description try expect result ok

Add the numeric attributes of selected children

sum_if(children,$UserFlag,$UserNum) 14 14 not yet

sum_if may also use an expression; here, we have the sum of those fruits of which we have less than a dozen

sum_if(children,$UserNum<12,$UserNum) 5 5 not yet

sum_if can count notes that meet a criterion; here, we count fruits of which we have less than a dozen.

sum_if(children,$UserNum<12,1) 2 2 not yet

Using a literal list of paths

sum_if("/data/fruit/apple;/data/fruit/pear;/data/fruit/lime",$UserFlag,$UserNum) 14 14 not yet

sum()

Adds a numeric attribute for a group of notes. The data are the following:

Name UserFlag UserNum
apple true 12
pear false 3
lime true 2

Wiki: Groups

description try expect result ok

Add the numeric attribute of each child

sum(children,$UserNum) 17 17 not yet

Using a literal list of paths

sum("/data/fruit/apple;/data/fruit/pear;/data/fruit/lime",$UserNum) 17 17 not yet

We may sum an expression; here, we sum the squares of UserNum

sum(children,$UserNum*$UserNum) 157 157 not yet

tan()

computes the tangent of an angle, in radians

Wiki: Math

description try expect result ok
tan(0) 0 0 not yet
round(tan(radians(45))) 1 1 not yet

time()

extract the time of day, as a string, from a date or date expression. Also, modify a date to set a specific time of day. In these examples, $Date is 20/01/2009.

description try expect result ok

Time is: 11:00

time($Date(parent)) 11:00 11:00 not yet

Time is: 11:00

time($Date(parent)+"3 hours") 14:00 14:00 not yet

Time is: 11:00

time($Date(parent),10,15) 20/01/2009, 10:15 20/01/2009, 10:15 not yet

Time is: 11:00. $UserNum = 8.

time($Date(parent),$UserNum,5+10) 20/01/2009, 08:15 20/01/2009, 08:15 not yet

Time is: 11:00. $UserNum = 8. $UserNum2 = 10.

time($Date(parent),$UserNum,5+$UserNum2) 20/01/2009, 08:15 20/01/2009, 08:15 not yet

twitter()

Pass username and status text and (if authorised - Tinderbox will ask) a tweet to sent from that account.

unlinkFrom()

This function deletes a link and returns nothing. It can't easily be tested in a cookbook context.

unlinkFromOriginal()

This function deletes a link, always between originals (if/either both linked item s are aliases), and returns nothing. It can't easily be tested in a cookbook context.

unlinkTo

This function deletes a link and returns nothing. It can't easily be tested in a cookbook context.

unlinkToOriginal()

This function deletes a link, always between originals (if/either both linked item s are aliases), and returns nothing. It can't easily be tested in a cookbook context.

uppercase()

Transforms a string or attribute to use all upper case.

description try expect result ok
uppercase("frosty friday") FROSTY FRIDAY FROSTY FRIDAY not yet

$MyString = "frosty friday"

uppercase($MyString) FROSTY FRIDAY FROSTY FRIDAY not yet

$MyString = "frosty friday"

uppercase($MyString(prevSibling)) FROSTY FRIDAY FROSTY FRIDAY not yet

urlEncode

URLs may only contain a restricted character set. urlEncode() converts any illegal characters in a string to the appropriate representation; for example, a space is converted to the string %20.

description try expect result ok
urlEncode("my test") my%20test my%20test not yet

$MyString's value is:

Para 1. Para 2.

N.B.: includes a Tab and line break.

urlEncode($MyString) %09Para%201.%0APara%202. %09Para%201.%0APara%202. not yet

$MyString's value is:

"This 'is' a test."
urlEncode($MyString) %22This%20'is'%20a%20test.%22 %22This%20'is'%20a%20test.%22 not yet

$MyString's value is:

This is <para> 1.
urlEncode($MyString) This%20is%20%3Cpara%3E%201. This%20is%20%3Cpara%3E%201. not yet

the argument to urlEncode() should be evaluated before the string is encoded.

urlEncode($Name(child)) foo%20bar foo%20bar not yet

utf8("theString")

utf8("theString")

Deprecated - not needed as Tinderbox now outputs UTF-8 as the default encoding.

See the original tests on the deprecated code page.

values(attr)

Returns a unique (set (list) of all the discrete strings (or individual list items) for a given attribute across the whole document. The attribute input is evaluated so is either a quoted attribute name (no $ prefix) or an attribute reference holding an attribute name, or an expression yielding the same.

description try expect result ok
values("ValueString") cogs;dogs;frogs;logs; cogs;dogs;frogs;logs; not yet

$MyString value: ValueString

values($MyString) cogs;dogs;frogs;logs; cogs;dogs;frogs;logs; not yet

var(x) {}

Declare a temporary/local variable. A local variable acts in most ways like a user attribute. The variable name, i.e. whatever string (no spaces or special characters) is given in var(), is available for local use for either the duration of the action or, when they appear inside curly brackets { ... } their scope is the rest of the clause - i.e the individual statements within the {}.

description try expect result ok
not yet

word()

tests whether a word occurs in the text or title of a note. This is faster than regular expression search, but less flexible.

description try expect result ok

The word "score" is found in the Gettsburg address.

eval(/data/Gettysburg,word("score")) true true not yet

The the phrase "Four score" appears, but it is not a word

eval(/data/Gettysburg,word("Four score")) false not yet

The word "Gettysburg" is found in the title of the note containing the Gettsyburg address.

eval(/data/Gettysburg,word("Gettysburg")) true true not yet

The phrase "Four score" can be found by regular expression search

eval(/data/Gettysburg,"Text(Four score)") true true not yet

year()

extract the year from a date. Also, construct a date from an existing date, specifying the year. For the purposes of this test, $Date is never

description try expect result ok
year($Date) 2009 2009 not yet

$Date is 20 January 2001

year($Date,2011) 20/01/2011, 09:00 20/01/2011, 09:00 not yet

$Date is 20 January 2001 : $UserNum is 2011

year($Date,$UserNum) 20/01/2011, 09:00 20/01/2011, 09:00 not yet

years(start,end)

Returns the whole number of years between the start and end times

description try expect result ok

Dates:

$Date 08/01/2010, 15:24

$Date2 08/01/2012, 15:24

years($Date,$Date2) 2 2 not yet

Dates:

$Date 08/01/2010, 15:24

$Date2 07/01/2012, 15:24

years($Date,$Date2) 1 1 not yet

Dates:

$Date 08/03/2010, 15:24

$Date2 08/01/2008, 15:24

years($Date,$Date2) -2 -2 not yet
years(date("20/1/2009 15:20"),date("20/1/2011 15:20")) 2 2 not yet