Note: both 'keyword' and 'designator' have long been used interchangeably for the terms described below. Other types of designator are described here.
When defining Date-type data Tinderbox's code parser accepts the following expressions as placeholders for calculated dates:
- yesterday
- today
- now
- tomorrow
Duration keywords
All provide a date/time, to seconds-level granularity. today and now return exactly the same value, with yesterday being 24 hours previous to now and tomorrow 24 hrs later. These alternate keywords can make for more intuitive contextual use in code.
The following designators can be used to modify the above. However, if simply used on their own, rather than as a modifier they do not return a valid date/time:
- day(s)
- week(s)
- month(s)
- year(s)
- hour(s)
- minute(s)
- second(s)
No value keyword
There is a further special case:
- never. No date, and regarded as earlier or later than any real date. This is also the default/empty value for Date-type attributes.
Case-sensitivity of keywords
Treat usage for the above placeholders as case sensitive.
Day-of-the-week keywords
Day placeholders, such as Sunday, Monday, etc., may also be used. Tinderbox recognises the day of the week and interprets it as the day after today with that week day. Thus on Sunday June 1, the date "Sunday" refers to Sunday, June 8. These keywords are locale-observant.
- The date parser recognises the day of the week in the current (macOS) locale. Recognised forms include the full day (Sunday), the short day (Sun), and the very short day (S). Note though, that the very short day is ambiguous in many languages, including English.
In other respects, days of the week act like the core keywords, e.g. today, in that they can be modified similarly, e.g. "Monday - 1" week is the previous Monday.
Dates may be modified by adding and subtracting "minutes", 'hours", "days", "weeks" and "years":
date("today+65 minutes")
Explicit (24-hour clock) time can be used, in which case it comes at the end of the string:
date("today+7 days 00:00")
The latter is useful to ensure that a base like 'today' or 'now' that take system clock time are set to to an exact known time, as may be needed for accurate date comparison.
Normally time is input is the form consistent with the users short date(/time) form such as "09:30" or "9:30 AM"but more flexibility is offered for import making it easier to set times as part of date/time designators, such as:
- "
today 0930" - "
today 930pm" - "
today 11"
The first two before half-past nine in the morning, The latter will be interpreted as 11 AM (11:00): the lack of minutes implies to set them as 00.
Note that the date(string) operator arguments are written as quoted strings which may include addition/subtraction signs. This format is deprecated:
date("today" +" 65 minutes") INCORRECT!
for this form, noting all string inputs are in one string:
date("today + 65 minutes")
If using Attribute values in a date expression simple use the $-prefixed attribute name outside the quoted string:
date($Modified+"5 minutes")
If modifying a date and the expression part of code can not be parsed as a date modified, the unmodified date is returned; this avoids unintentional creation of undefined ('never') dates.
Date parsing: the date "tomorrow 8" is treated as 8 o'clock tomorrow. Note in that older versions it was interpreted as 8 days from tomorrow. "Tomorrow+8" continues to denote 8 days from tomorrow.
Beware that any Date-type attributes initialised using using year, month & day without a time element will use current system time as opposed to a 00:00:00 which might otherwise be assumed.