Set Attributes

A Set is useful for lists of topics, categories, and tags. Sets are typically displayed as strings, separated by semicolons:

astronomy;marine biology;chemistry

dogs;cats

To add set values directly to an attribute via the KeyAttributes or via Info view, simply type the values as seen above noting that no semi-colon is required after the last value; Tinderbox happily ignores it if you supply one.

With a set you can add/remove individual or multiple values and test its contents.

Adding and deleting values

In actions, + adds an item to a set if it is not already present, and - removes it if it is present. Although double quotes aren't necessary, their omission is deprecated and users should migrate to always using double quotes with string literals in action code.

PetTypes+"dogs" leaves PetTypes unchanged, since 'dogs' is already in PetTypes

PetTypes-"dogs" leaves only cats.

Besides specifying elements to be added or removed, they can also be toggled via the '~' operator:

PetTypes="+dog;-cat;~hamster"

adds 'dog' to PetTypes, removes 'cat'. If 'hamster' is present, it will be removed; if 'hamster' is absent, it will be added. In the above example the quotation marks are mandatory, since + and - would be interpreted differently in without them).

The shorter, deprecated syntax

PetTypes="+dog"

is equivalent to either of these:

PetTypes=$PetTypes+dog [Deprecated - no quotes]

PetTypes=$PetTypes+"dog"

The second longer usage forms are much clearer, if somewhat more verbose; the first, short, form can be more flexible for use with stamps. Tinderbox is quite forgiving; for instance both the following add a value 'gun dog' even though it a multi-word string containing a space but in the first example it has no enclosing quotes:

PetTypes=$PetTypes+ gun dog

PetTypes=$PetTypes+"gun dog"

Less experienced users should use the latter, quoted, syntax to save inadvertently testing just how flexible or not the action parsing is.

Be careful not to inadvertanly using the following syntax for adding values:

PetTypes=+"dog"

note the plus sign coming before the opening double quote but not preceded by the target attribute. This syntax adds the value "dog" instead of dog, i.e. actually including enclosing double quotes as part of the value. Luckily, it doesn't matter for deletions as quoted and non-quoted values would both be deleted if present. However, if doing tests (see further below) a test for PetType(dog) would not match a value "dog" but would match dog.

As further above, if the last example has the target attribute's name added at the start of the action and the quotes are placed only around the value string, the desired value without quotes is added correctly.

PetTypes=$PetTypes+"dog"

Should you get an incorrect (quote-enclosed) value, a set delete action will match both quoted and non-quoted values. You can then re-insert the correct value.

The '~' operator can only be used inside a quoted string like above. To use it on its own, add a quoted string with the ~ inside the quotes and with a space either before, after or both sides of the preceding '+' (otherwise the added value isn't properly detected):

PetTypes=$PetTypes+ "~dog" Good

PetTypes=$PetTypes +"~dog" Good

PetTypes=$PetTypes + "~dog" Good

PetTypes="~dog" Good but deprecated

PetTypes=$PetTypes~"dog" Won't work - incorrect use of '~' syntax

PetTypes=$PetTypes+"~dog" Won't work (parsing error, no space around the '+')

Testing sets

Testing sets, the contains operator, syntax AttributeName(tested_value), returns true if a set contains an exact match for the the designated value; the test is case sensitive regardless of agent query case sensitivity settings. If user attribute PetTypes has a value of "dogs;cats" then either

PetTypes(dogs) is true,

but

PetTypes(dog) is false

as 'dog' is an incomplete value match. As such test are a query (even if used in action syntax like an if{}else{} test), the tested value must not be quoted as the tested_value string is a regular expression.

See the format() action operator for ways to turn sets into HTML lists for export.

Attributes of the set data type are listed below.

• KeyAttributes

Licensed under Creative Commons Attribution-Noncommercial-Share Alike 3.0 License
[See aTbRef CC licence Attribution/Waiver info info]