List-Type Attributes

List

A semi-colon delimited list of string values. In terms of stored data Sets and Lists are the same: a string containing one or more semi-colon delimited items. The difference is in the way Tinderbox handles the two data types, as lists may contain duplicate items. Although the Set-type pre-dates List-type in Tinderbox, Lists should be thought of as the underlying form and Sets as a type of List with special features (de-duplicated, always sorted, etc.).

List items can be read/set via their list order number (see below) but note that this is zero-based, i.e. list item #1 has address value zero (0).

A List, even a list of numbers or boolean values, is stored as a semi-colon delimited string, i.e. list items are not stored with an explicit data type, though multi-value value can be list or dictionaries.

Declaring a new List

If setting a List's literal values via action code use the square bracket [ ] List definition:

$MyList=[Frogs;Dogs;Logs];

Above, the brackets replace the older now-deprecated method of enclosing quotes:

$MyList="Frogs;Dogs;Logs"; NOTE: do not use this for new code!

Whilst both methods work and the latter, older, method will be found in many demos and tutorials, the bracketed notation is now the preferred method.

Importantly, when typing/pasting a List's values into a UI input box such as the Inspector, Get Info, or Displayed Attributes, the enclosing brackets or quotes (as used above) should be omitted, i.e. using planes;trains;automobiles not [planes;trains;automobiles]. If brackets are used by mistake, the Tinderbox parser should ignore an outmost pair (as it would quotes) abut still honour brackets within the overall list value as implying a nested list. If Tinderbox reads from a List via code and reports (logs) a value with enclosing brackets, Tinderbox knows—in code—to ignore those as simply being list delimiters.

Adding new list items

With a List you can add/remove individual or multiple values and test its contents. In actions, + adds an item to a set if it is not already present. Values should be enclosed in square brackets (previous, and still supported is to use enclosing double quotes). If $PetTypes' value is "cats;dogs", then:

$PetTypes=$PetTypes+[rabbits]; adds the new value

$PetTypes=$PetTypes+[rabbits]; unlike a Set, this adds a second instance of "dogs" to the end of the List.

The += increment operator can also be used. If the List is 'cats;dogs;frogs':

$PetTypes=$PetTypes+[cats;frogs]; this gives a value of 'cats;dogs;frogs;cats;frogs'; the new values appended to the list in the order supplied.

To add new—not replacement—item(s) to the beginning of a list, use the [] list declaration method:

$PetTypes= [rabbits;hamsters]+$PetTypes;

N.B. the last fails if using to old quote-enclosed format instead of square brackets.

To add a new item that is itself a list, note the extra set of brackets needed. The following adds a new list item whose value is a two-item list.

$PetTypes=$PetTypes+[[rabbits;bunnies]];

To insert a new list at a specified location, i.e. adding a list item as opposed to replacing an existing value, iterate the list using List.each() with a custom counter. Store existing items in a new list and add the term when the loop reaches the desired place in the list. At the end of the loop write the new list back over the original List.

Deleting items

In actions using a - (minus) removes the supplied value(s) if present. Importantly, this removes all occurrences if the deleted item;

$PetTypes=$PetTypes-[dogs]; leaves only "cats" as a value.

To delete only specific instances would require using List.each() with a custom counter.

The += increment operator can also be used. If the List is 'cats;dogs;frogs':

$PetTypes=$PetTypes+[cats;frogs]; this gives a value of 'cats;dogs;frogs;cats;frogs'; the new values appended to the list in the order supplied.

The -= decrement operator can also be used. If the Set is 'cats;dogs;frogs':

$PetTypes=$PetTypes-[cats;frogs]; this leaves only 'dogs' as a value.

Replacing a list item's value

The List[N] notation addresses any single List item using a zero-based address. Thus List[1] addresses item #2, whilst List[0] addresses the first. To replace item #3 in a list (assuming a big enough list):

$MyList=[Frogs;Dogs;Logs];

$MyList[2]=[Pogs]; results in a list of "Frogs;Dogs;Pogs"

Additional list definition mark-up

Lists and Sets may be written by enclosing them in square brackets, rather than inside quotes, as in the past. The newer form is more declarative of intent to the user and the app, so is recommended. Lists may be nested; for example, the list

[ 1; [2;3]; 4]

contains a 3 elements — 1, the nested list 2;3, and 4.

Long Tinderbox precedent holds that list addition adds each element of the two lists. For example

$MyList = [1] + [2;3]

$MyList += [2;3]

both result in the list 1;2;3 and not 1;[2;3]. To add a sublist to a list, use the operator list.extend(). Thus:

$MyList = [1].extend( [2;3])

results in the list [1;[2;3]].

Offset assignment to a list of notes recognises bracket-enclosed lists correctly, for example:

$Status([this;parent])="urgent";

Implicit evaluation is no longer performed in bracketed lists. Thus,

$DisplayedAttributes=[MyList;MyString];

is now equivalent to

$DisplayedAttributes="MyList;MyString";

If new List terms need evaluation, use list() instead.

Accessing nested lists

Consider the following:

$MyTestList = [1;[a;b];3];

To retrieve the nested list:

$MyString = $MyTestList[1]; results in '[a;b]'

Note the square brackets are retrieved too, so for further use of the list this might be better:

$MyString = $MyTestList[1].substr(1,-1); results in '[a;b]'

To retrieve a value from that list:

$MyString = $MyTestList[1][1]; results in 'b'

De-duplicating a List: List vs. Sets

Lists, unlike Sets, allow duplicate values. To de-dupe a List, use the .unique dot-operator:

$MyList=$MyList.unique;

An older alternate method, which may be found in old demos is simply put its contents into a Set-type attribute:

$MySet=$MyList; (deprecated in favour of the method above)

If $MySet and $MyList both have the value [cats;dogs]: the following have different outcomes:

$MySet=$MySet + [dogs]; gives 'cats;dogs'

$MyList=$MyList + [dogs]; gives 'cats;dogs;dogs'

The Set attribute does not add the duplicate value but the List attribute does. List data values are stored in the order added.

Testing (querying) Sets & Lists

To test a set or list, use the .contains() operator, syntax AttributeName.contains("tested_value"), returns true if any Set/List discrete value exactly matches the designated tested_value; if case sensitivity is irrelevant for the query use .icontains(). If a user attribute $PetTypes has a value of 'dogs;cats' then

$PetTypes.contains("dogs") is true,

but

$PetTypes.contains("dog") is false

This is because Let/List matching does not allow partial matches, as via regex, unlike with String-type data.

Other variants:

$PetTypes.contains("Dogs").lowercase is true

$PetTypes.icontains("DOGS") is true

It can be useful to use a stored value as the search term, for instance using the name of an agent as the search term:

$PetTypes.contains($MyString) is true

Escaping literal semi-colons

If a list item must contain a semi-colon, it must be escaped, using a backslash, '\;'. Once the backslash is entered, it disappears and the list item containing the semi-colon is enclosed in double-quotes. Do not try to escape a value by adding the quotes directly, use the backslash method. Action code methods to make lists will treat a '\;' in an input string as an escape and act accordingly. Consider using String.replace() as a method for escaping backslashes (though only where intended!).

Listing and Exporting sets

The format() action operator and more recent .format() dot operator offer ways to turn sets into HTML lists for export. See Exporting Set-type data for more.

System Attributes: Sets vs. Lists

Most group-scope operators can work with lists or sets, as well as the find() operator (whose own output is a list) and literal list-based group designators; exceptions include $DisplayedAttributes where duplicates would not be helpful. It is the declared data type of the attribute being collected that informs the operator to return a list or set.

Default/Empty value

An empty string.

Sorting order

Lists are not sorted, so retain the order in which items were passed into the list, most recent being at the end. Lists can be sorted using action code sort operators or by setting the sort attributes of containers.

List-type System Attributes

Built-in attributes of the List data type are listed below:

See also—notes linking to here: