In documenting action code, examples are given where pertinent. In order to help learners, where a left side attribute is appropriate, an attribute is used whose name indicates the type of data returned by the right side of the example.
In the majority of cases the returned value is is an explicit or implied string:
$MyNumber = $MyDate.hour;
$MyString = $MyString.words(-1);
But other types do occur:
$MyInterval = interval($Created,$Modified);
Processes returning a list are shown as returning a List:
$MyList = $MyList.unique;
But you can chose a different approach, if you have a different result in mind
$MyList = collect(children,$FavFruit); $MyList is "Apples;Oranges;Pears;Apples"
$MySet = collect(children,$FavFruit); $MySet is "Apples;Oranges;Pears;"
$MyString = collect(children,$FavFruit); $MyString is "Apples;Oranges;Pears;Apples"
Above the first case is the best generalised example. But if the source has duplicates , you can de-dupe it if desired simply by passing a list (i.e. multi-value ) to a Set-type attribute as shown in the second example. Possible, but of less use is passing the kist ti String where you receive a single string of all the list value, separated by semi-colons (essential a list in its raw form).
This same choice of left-side attribute can word in other context:
$MyNumber = $MyColor.blue; (gives 255)
$MyString = $MyColor.blue; (gives "255")
In a few cases an action operator requires no left-site attribute as the process returns nothing, but instead carries our the specified action:
action($Text("Test-stamp"));
stamp("Do Stuff");
$Text.speak("Tessa");
Two more conventions worthy of note. Designators are by convention not quoted, in this case the 'children' forming the first input parameter.
$MyList = collect(children,$Name);
Also when using note titles as offset addresses for an attribute reference, a $Name value is quoted
$MyInterval = drivingTimeTo("Swarthmore");
but a $Path values is not:
$MyInterval = drivingTimeTo(/places/faves/Swarthmore);
Those designator and title vs. path quoting 'rules' are not hard-and-fast, but unless experienced enough with code to understand possible edge cases, most users would do well to treat them as actual rules, in order to avoid unexpected outcomes.
I've also been deliberately pedantic over end-of semi-colon expression markers. These all work:
$MyString = "Hello world.";
$MyString = "Hello world."
$MyString = "Hello world"; $MyNumber = 2;
$MyString = "Hello world"; $MyNumber = 2
as do expressions if split onto different lines:
$MyString = "Hello world";$MyNumber = 2;
But, if the attribute or stamp holding the code has more than one expression, you must place a semi-colon between expressions. So, this is wrong:
$MyString = "Hello world" $MyNumber = 2
Tinderbox might correctly guess you are using two discrete actions, or not. Better to close your expressions with a semi-colon, even if only to remind yourself
In, turn this leads to another confusion. Semi-colon expression delimiters are not used in queries. This is not so confusing as at first sight as queries are used in very few contents:
- agent queries.
- the condition in a if(condition)
- find(query)
Semi-colons turn up in one more place, in literal lists:
$MyList = "ant;bee;cow"
Results in adding three discrete value to $MyList.
Tinderbox ignores white space within/between expressions. These all work the same:
$MyString = "Hello world"; $MyNumber = 2;
$MyString = "Hello world";$MyNumber = 2;
$MyString="Hello world";$MyNumber=2;
The same is true of white space in input parameters:
$MyList = collect(children,$FavFruit);
$MyList = collect(children, $FavFruit);
However, within a string, the same does not hold true, these set different values:
$MyString = "Hello" + " " + "world."; → "Hello world."
$MyString = "Hello " + " " + " world." → "Hello world."
Of course, the latter is in Tinderbox. To simulate that here in HTML , non-breaking spaces have to be used in the TBX as web browsers collapse strings of space to a single one. Thus string "Hello world." in Tinderbox exports as "Hello world." but renders online as "Hello world."