$Attribute == $OtherAttribute
The double-equals (==) usage for tests of equality replace older use of a single equals sign.
Previously, a single equals sign acted as either an assignment of the right side to the left or as an equality operator, Tinderbox deciding which form to use depending on context. A single equals sign is used for assigning values only and not for testing equality.
$BooleanAttribute == true
Matches notes whose $BooleanAttribute value is true.
For other data types, testing for the presence of a value can be considered a boolean test. This is useful as queries and if() clauses use a 'condition' which must resolve as true or false.
$ColorAttribute == color("data")
The data needs to be a string that matches $ColorAttribute case-sensitively.
Named colours matching hex values will be match and the case of hex values is ignored. Thus color("#0000ff") matches color("#0000FF") and color("bright blue"). But none of those would match color("Bright Blue"), unless of course it too had been defined with the same hex equivalent of #0000ff.
Note that Tinderbox's pre-defined named colours are all-lowercase, and that hexadecimal colour codes created via the colour picker use lower case for any letter characters.
$DateAttribute == date("aDate")
$DateAttribute == "aDate" <— Deprecated, do not use
In tests of date equality, the time element of a date/time is ignored. In other words the granularity of test is for the dates being on the same calendar day.
$DateAttribute == date("aDate")
$DateAttributeA == $DateAttributeB
true where $DateAttribute date matches the given aDate's calendar day
$DateAttribute == date("today"). true where $DateAttribute date is today's date (same calendar day).
$DateAttribute == date("yesterday"). true where $DateAttribute date is yesterday's calendar day.
$DateAttribute == date("tomorrow"). true where $DateAttribute date is tomorrow's calendar day.
$DateAttribute == date("never"). true if there is no date. Note, 'never' is not < any date, nor is it > than any date, but it is equal to 'never'. Atypically, this null value is both older than the oldest set date and newer than the most recent set date; thus 'never' is earlier or later than any real date. When agents search for a specified time range, the comparison operators < and > treat the value 'never' specially.
To search for a note with a valid date/time, it might seem logical to use $DateAttributeA > "never". No! The correct test is $DateAttributeA != "never".
The operators '<=' and '>=':
$DateAttributeA >= $DateAttributeB
$DateAttributeA <= $DateAttributeB
also return true if the dates are on the same calendar day (because the '=' part of these operators are a '==' equality test).
$NumberAttribute == number
True where $NumberAttribute value equals the given number. Note the number value is not quoted.
$ListAttribute == "data"
Note: Tinderbox does not perform meaningful equality comparisons on List-type attributes.
A match only occurs if data matches all values in the list. Thus if the list value is "dog;cat" and the data string is "dog", the result is false. If the string is "dog:cat" the result is true; a successful match also occurs for "cat;dog".
It can be seen that data is parsed for all values but that a true result is only achieved if all values match, whereas the likely intention of the user is to see if data matches one, or more, list values.
Lists are best compared for a pattern—either a literal string or regular expression—using:
- for matching only complete individual list values: the List.contains("regex") action operator.
- for regex partial matches: coerce the Set values to a String, and use String.contains("regex").
$SetAttribute == "data"
Note: Tinderbox does not perform meaningful equality comparisons on Set-type attributes.
A match only occurs if data matches all values in the set. Thus if the set value is "dog;cat" and the data string is "dog", the result is false. If the string is "dog:cat" the result is true; a successful match also occurs for "cat;dog".
It can be seen that data is parsed for all values but that a true result is only achieved if all values match, whereas the likely intention of the user is to see if data matches one, or more, set values.
Sets are best compared for a pattern—either a literal string or regular expression—using:
- for matching only complete individual list values: the Set.contains("regex") action operator.
- for regex partial matches: coerce the Set values to a String, and use String.contains("regex").
$StringAttribute == "data"
True where $StringAttribute value is identical to the data string. For instance:
$Text == "Hello"
…would be true if the note's text consisted only of the word "Hello".
Note the data string is must be quoted (it may work without quotes but do not rely on that!).