Tinderbox User-to-User Forum (for formal tech support please email: info@eastgate.com)
Tinderbox Users >> Agent, Actions, Rules & Automation >> A rudimentary date-parsing question

Message started by J Fallows on Apr 11th, 2016, 10:38pm

Title: A rudimentary date-parsing question
Post by J Fallows on Apr 11th, 2016, 10:38pm

This is a topic I've visited before but don't feel I've mastered. I'm asking "in public" in case others have a related question.

I have an agent to find tasks whose $StartDate — the time when I need to pay attention to them — has already arrived. Thus the basic form of my query is:

  $Prototype="*Task" & $StartDate<today

My question involves the use of parentheses and quotes. In principle, is there any difference among these formulations:

  $Prototype="*Task" & $StartDate<today     [bare]
  $Prototype="*Task" & ($StartDate<today)  [parens]
  $Prototype="*Task" & ($StartDate<"today") [parens & quotes on today]
  $Prototype="*Task" & "$StartDate<today"   [quotes]

If they should all give the same results, is one form the "preferred" form? If they don't give the same results, is that because quotes mean something special when applied to a term like today? Right at this moment, I seem to get the same results from all four, but I first noticed the issue because I was puzzled earlier by some differing results. Grateful for guidance on (a) the overall similarity/difference of quotes vs parens, and (b) special meaning of quotes and parens with terms like "today."

Title: Re: A rudimentary date-parsing question
Post by Mark Anderson on Apr 12th, 2016, 5:23am

There are two discrete aspects to this so, if I may, I'll address them separately. I'll first give a TL;DR answer for later skim-reader and then given the explanation. 'Correct' being a weighted term, I'll suggest that as at v6.5.0, the optimal forms is as follows:

$Prototype="*Task" & $StartDate<date("today")

These do no harm, in the way used in your examples. As in a spreadsheet or coding, parentheses can be used to influence how an expression/equation is unpacked and processed. Consider this query:

A | B & C

This could be passed on one of two orders (ignore whether the outcome is the same):

- evaluate 'A or B' then the result with 'and C'
- evaluate 'B and C' then the result with 'or A'

As it happens, I think the first is the more usual left-to-right parsing and that which TB uses. But what if you wanted to be certain the second sequence was used? Then you'd write:

A | (B & C)

The parentheses tell the parser to do the things in the enclosed bit first. More complex use with nested parentheses work the same, the 'innermost' parentheses are evaluated first.

As well as influencing order of execution, parentheses have another useful effect in that they ensure that things happen in order. For instance we may want to test a value made from joining two bits of text, i.e. we have "abc" and  "def" but want to test "abcdef". Putting parentheses around these ensures the two string are joined before further evaluation takes place.

Defining date/times
This are gets confusing because Tinderbox is around 15 years old and is ever-evolving. Importantly, action code is much more simple and there are many more attribute. Indeed, early Tinderbox didn't have action code (sidenote: you used export code instead). So, you could write this:

StartDate < today

…and TB would understand you wanted to test whether the attribute 'StartDate' had a date/time earlier than today's date/time. (Aside: in fact the date time of current execution of the code, as 'today' is the equivalent of 'now'). Look around, e.g. the old wiki and you'll find examples like this. The probably still work today, but may not going forward.  So what's changed.

1. Explicit attribute references. If we refer to the (value of) an attribute in action code, current best practice is to put a $ sign in front. This tells Tinderbox explicitly of our intent. Thus:

$StartDate    - best practice. Use for new code
StartDate    - existing code should work. Update/don't use for new code
2. Quoting strings. Over time, it has become convention (not yet enforced internally, so as not to break existing code) to make sure strings (bits of literal text) in action code are put in quotes, most usually double quotes and never curly typographic quotes (the latter will cause the code to not work). Thus, best practice changed:

StartDate < today

… became …$StartDate < "today"

… before evolving further c. v5 when the date() function allowed explicit expression of date/time from a string.

Using the latter is not compulsory. But, if you don't (like to) understand action code you are advised to work as it it were a requirment. Using date() should provide fewer (no!) instances of unexpected outcomes. This gives us:

$StartDate < date("today")

To a degree, using date() also obviates some of the considerations twoards the need for parentheses (as described above).

3. Date designators. Read this article on designators like now' and 'week'. Most seem lowercase. From a quick check (v6.5.0) day-of-week can beith either case (i.e. 'Monday' or 'monday'). I'm unsure whether day-of-week desigators are English only or follow locale, now Tinderbox is increaingly lovale aware (perhaps eastgate can clarify?)

In an ideal world, we could go back and update all online examples to current use. But, including screen grabs, videos, demo files, that's a mammoth task. So, don't be afraid to update example you see if copying them into your current documents. The underlying principles haven't changed. It's just the mark-up is getting more explicit (clarity is no bad thing!).

Title: Re: A rudimentary date-parsing question
Post by J Fallows on Apr 12th, 2016, 9:46am

To Mark A: This is very clarifying and informative, and typically patient and generous of you to lay it out this way. Thank you!

Title: Re: A rudimentary date-parsing question
Post by Mark Anderson on Apr 12th, 2016, 10:30am

Most kind. THe writing down always throws up someething I thought I knew but don't. Today is was whether date deignators are case sensitive, it looks like they aren't. Pertinently, if you use them with date() TB has less guessing as to whether 'Today' means 'today' or is string with some other meaning purpose.

Title: Re: A rudimentary date-parsing question
Post by Mark Bernstein on Apr 12th, 2016, 11:44am

The keywords "today", "tomorrow", and "yesterday" are all case-sensitive.  It turns out the "Today" is a synonym for "today", but this is not something on which to rely.

Title: Re: A rudimentary date-parsing question
Post by Mark Anderson on Apr 12th, 2016, 12:02pm

Thanks. A trip-up here, for the occasional or code-averse user, is that designators are generally all-lowercase except possibly (based on examples) for day-of the-week. Thus: 'now', 'today', 'month', 'tomorrow' … but 'Monday', 'Wednesday'.

however, it does appear - testing in v6.5.0. - that date("Thursday +1 day") and date("thursday + 1 day") have the same outcome. As lower case day names seem to work, it seems a consistent rule ('use all-lowercase') to adopt and learn for designators, even if TB's actually coercing to capital case under the hood. Actually, using lowercase for day names as designator usage has the benison of otherwise being an egregious grammatical error if intended as a normal bit of text.

Tinderbox User-to-User Forum (for formal tech support please email: info@eastgate.com) » Powered by YaBB 2.2.1!
YaBB © 2000-2008. All Rights Reserved.