Dictionary<\/b><\/p>\n
A Dictionary attribute replaces like the older Tinderbox feature of lookup tables<\/a>, as a list of paired key<\/b>s with value<\/b>s: The key<\/b> part comes first with a terminating colon. The value<\/b> part follows, terminated by a semi-colon. White space handling in key:value pairs is described below.<\/p>\n Dictionaries are faster to construct, and large dictionaries are far faster to check, than lookup tables. Dictionaries are not generally intended for handing large\/complex values or for values including punctuation and symbols. A Dictionary may be considered better for tasks previously configured using look-up lists.<\/p>\n Like other attribute types, a Dictionary follows normal rules of scope and inheritance. A note using a prototype with a Dictionary holding data, will inherit that data dictionary. Similar to a Set type, a Dictionary does not allow duplicate keys, but multiple keys may use the same value.<\/p>\n A key may have multiple<\/i> values; this can be either []-enclosed List-type or {}-enclosed Dictionary-type data. For example, the dictionary:<\/p>\n\t contains two elements. The first has a key of \\\" Dictionary key:value syntax<\/b><\/p>\n A dictionary collects pairs of strings separated by a colon, noting that whitespace before\/after the colon in the key:value: pair is ignored when the data is added. The first string is the key,<\/i> and the second string is the value.<\/i> In these examples there are 3 such key:value pairs. These first two forms are better practice than the third just below:<\/p>\n\t The dictionary()<\/b> operator creates a dictionary (in the current note),<\/p>\n\t The key<\/b> \\\"cat\\\" has the value<\/b> \\\"animal\\\", while the key<\/b> \\\"rock\\\" has the value<\/b> \\\"mineral\\\".<\/p>\n Although it is still possible, via legacy support, to populate a directory by passing a dictionary-formatted list as a quoted string to a Dictionary-type attribute, this is deprecated<\/i> in favour of the Case-sensitivity<\/b><\/p>\n A key<\/b> is case-sensitive<\/i> and must be unique to the dictionary; the value<\/b> may be the same as values for different keys within the current dictionary. Rather like the Set data type, duplicates are weeded. If a new key:pair is added to a dictionary and the key (case-sensitively) already exists, the existing value (only) for that key is updated to use the value from the new pair.<\/p>\n\t Now, the value of key \\\"cat\\\" becomes \\\"mammal\\\" and the older value is lost.<\/p>\n Quoting of keys and values<\/p>\n From v11.5.0, the key is always<\/i> treated as a string, and does not require to be quoted: quoted keys, e.g. in older code, will still work correctly. If the value of that key is a string, it should<\/i> be quoted. In addiction, the value must<\/i> be quoted if<\/i> the string value contains any of the following: {}():\/\/ or quotation marks.<\/p>\n Use of whitespace, symbols, quotes, etc., with keys & values<\/b><\/p>\n Any whitespace either side of a colon (:), or semi-colon (;), or at beginning or end of dictionary data is ignored. As the colon (:) and semi-colon (;) characters are used as delimiters in the stored Dictionary data, they should also not be used within key names or values.<\/p>\n The expectation is that keys and values will be simple strings or numbers, so avoid use of characters like punctuation as you may experience unexpected results; additionally avoid using parentheses (), square [] or curly {} brackets, backward \\ and forward \/ slashes, single\/double quotes or commas.<\/p>\n A good rule of thumb is to think hard if using other than Adding key:value pairs<\/b><\/p>\n To add to a new key:value pair, use addition, as with Lists and Sets…<\/p>\n\t adds they key \\\"apple\\\" and associates it with the value \\\"plant\\\". If the key was already found in the dictionary, its value is replaced by the new value. If the key was not found in the dictionary, both the new key and the new value are added.<\/p>\n As well as using a literal value, the key (and value) to be added can be give as an attribute value or variable:<\/p>\n\t There also a Dictionary.add()<\/a> operator. This does the same as the above:<\/p>\n\t Deleting keys (implicitly key:value pairs)<\/b><\/p>\n Entries can be deleted from a dictionary by subtracting the key:<\/p>\n\t or in newer form:<\/p>\n\t Be aware that setting an empty value for a key doesn\\'t delete the key:<\/p>\n\t leaves the key \\'somekey\\' with no value, which is not encouraged (q.v. below).<\/p>\n As well as using a literal value, the key to be removed can be give as an attribute value or variable:<\/p>\n\t It is not possible to subtract a list of keys. Instead, such a list must be iterated as a succession of individual key deletions. The only exception to this is if all keys<\/i> are to be deleted, in which case set the dictionary object (attribute or variable) to the default value to delete existing data:<\/p>\n\t Changing the value of a key<\/b><\/p>\n New values may be assigned to specific dictionary keys.<\/p>\n\t Adds the key \\\"apple\\\" to $MyDictionary with the value \\\"pie\\\". If the dictionary previously contained a value for \\\"apple\\\", it is replaced by \\\"pie\\\"; if not, a new key and a new value are added to the dictionary. Or, use .add()<\/b> can be used:<\/p>\n \t Note that the += and -= operators are not currently available for changes to dictionary (numerical) values of the form<\/p>\n\t Instead, use the conventional form:<\/p>\n\t Adding to a key\\'s value(s)<\/b><\/p>\n The Dictionary.extend()<\/a> operator offers such a feature.<\/p>\n Deleting the (single) value of a key<\/b><\/p>\n Ideally in such a case remove the key. However is possible to delete a key\\'s value, by setting it to an empty string \\\"\\\" (or reading from a stored value that is such). To set the value of key \\'apple\\' to \\\"\\\":<\/p>\n\t Generally, the expectation is that a key has an actual value<\/i>.<\/p>\n Keys with multi-item values are supported using [] or {} notation<\/b><\/p>\n Dictionary key values can be multi-valued using either the new From v11.6.0, lists now allow blank (empty) list items when using the Merging Dictionaries<\/b><\/p>\n Dictionaries may be merged by adding them.<\/p>\n\t adds they key \\\"apple\\\" and associates it with the value \\\"plant\\\". If the key was already found in the dictionary, its value is replaced by the new value. If the key was not found in the dictionary, both the new key and the new value are added.<\/p>\n It is possible to add two dictionaries.<\/p>\n\t Note that if the dictionaries share (case-sensitive) keys that have differing values, the values from the last-added, therefore those in $MyDictionary, will replace those in $MyDictionary. Thus:<\/p>\n\t MyDictionary now contains \\\"granite: rock; pear: fruit; apple: fruit\\\"<\/code> <\/p>\n Note the order of dictionary items is re-ordered, reinforcing the point that additions\/subtraction of dictionary data may alter item order, and which the user does not control. It is not possible to:<\/p>\n <\/p>\n Dictionaries lack the \\'default\\' key used by look-up lists <\/b><\/p>\n User of look-up lists<\/a> with list-type data might assume the same notion holds for Dictionary-type: it does not! It is still possible to define a \\'default\\' key but using it requires a little extra code. Whilst it is possible to check if a key exists with Dictionary.contains()<\/a>, it may be more useful to check for a default empty (\\\"\\\") value being returned. For instance, instead of, in a consider (and assuming a \\'default\\' key\/value exists):<\/p>\n\t or:<\/p>\n\t But, the key point is that is a default response is needed, the user must (a) define the \\'default\\' key:vale pair and (b) add the code to invoke it. More code-savvy users may choose to encapsulate this in a user function<\/a>.<\/p>\n Dictionary and values()<\/b><\/p>\n You can get the values of a Dictionary, but you cannot look up a key that corresponds to a given value. Remember, multiple keys may same value. Therefore, using values() with dictionaries is not recommended as this returns all the unique key:pair values as opposed to only keys or only values.<\/p>\n Iterating Dictionaries<\/b><\/p>\n Use Dictionary.keys to get a list of the keys and then iterate that list using list.each()<\/a>.<\/p>\n Default\/Empty value<\/b><\/p>\n If a requested key is not defined, or the key has no value, an empty string is returned.<\/p>\n Dictionary sorting<\/b><\/p>\n Not applicable, as Dictionaries cannot be sorted. As a Dictionary is addressed via a key value rather than a list offset, the stored order for keys is moot. By observation, a Dictionary is generally stored in key lexical sort order but this should not be assumed to always be the case.<\/p>\n Whilst a Dictionary itself cannot be sorted, it is possible to make a list of the keys then sort and iterate that<\/i> list. for example:<\/p>\n\t Note that the initial sort could be lexical ( Additional Dictionary definition mark-up<\/b><\/p>\n Dictionaries may be written by enclosing them in braces, for example a dictionary with two key:value pair elements:<\/p>\n\t The use of the braces removes the need to use quotes around string values.<\/p>\n This new form of Dictionary-type data allows for nesting; for example, the dictionary<\/p>\n\t contains two elements. The first has a key of \\\" The dictionary .add() and .extend() operators now take a single argument — a dictionary of elements which will replace or extend the current elements.<\/p>\n Legacy behaviour<\/b>: Prior to v9.6.0, a value could not contain more than one value The value for a key \\'pie\\' might reasonably be apple, lemon and quince. Whilst it was possible to define a dictionary like this:<\/p>\n\t … the fact a semi-colon is used as both a list delimiter (within the value<\/b>) and as a key<\/b>:value<\/b> pair delimiter, means Tinderbox currently<\/i> does not know how to parse this; work is in hand to support multi-item value, i.e. lists.<\/p>\n Temporary note<\/i>. Presently generating a dictionary with nested multi-values (list\/dictionary) may be possible only if using literal string values but not if using variables\/attribute values. This is likely a by-product of the newer [ ] and { } data type notations and subject to later changes\/fixes.<\/i><\/p>\n Dictionary-type System Attributes<\/b><\/p>\n Built-in attributes of the date data type are listed below:<\/p>\n List<\/b><\/p>\n A semi-colon delimited list of string values. In terms of stored data Sets<\/a> 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.).<\/p>\n List items can be read\/set via their list order number (see below) but note that this is zero-based<\/i>, i.e. list item #1 has address value zero ( 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.<\/p>\n Declaring a new List<\/b><\/p>\n If setting a List\\'s literal values via action code use the square bracket Above, the brackets replace<\/i> the older now-deprecated<\/i> method of enclosing quotes:<\/p>\n\t 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.<\/p>\n 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 Adding new list items<\/b><\/p>\n With a List you can add\/remove individual or multiple values and test its contents. In actions, The To add new—not replacement—item(s) to the beginning of a list, use the N.B. the last fails if using to old quote-enclosed format<\/i> instead of square brackets.<\/p>\n 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.<\/p>\n\t 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()<\/a> 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.<\/p>\n Deleting items<\/b><\/p>\n In actions using a To delete only specific instances would require using List.each()<\/a> with a custom counter.<\/p>\n The The Replacing a list item\\'s value<\/b><\/p>\n The List[N] notation addresses any single List item using a zero-based<\/i> address. Thus Additional list definition mark-up<\/b><\/p>\n 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<\/p>\n\t contains a 3 elements — 1, the nested list 2;3, and 4.<\/p>\n Long Tinderbox precedent holds that list addition adds each element of the two lists. For example<\/p>\n\t or<\/p>\n\t both result in the list results in the list Offset assignment to a list of notes recognises bracket-enclosed lists correctly, for example:<\/p>\n\t Implicit evaluation is no longer performed in bracketed lists. Thus,<\/p>\n\t is now equivalent to<\/p>\n\t If new List terms need evaluation, use list()<\/a> instead.<\/p>\n Accessing nested lists<\/b><\/p>\n Consider the following:<\/p>\n\t To retrieve the nested list:<\/p>\n\t Note the square brackets are retrieved too, so for further use of the list this might be better:<\/p>\n\t To retrieve a value from that list:<\/p>\n\t De-duplicating a List: List vs. Sets<\/b><\/p>\n Lists, unlike Sets, allow duplicate values. To de-dupe a List, use the .unique<\/a> dot-operator:<\/p>\n\t An older alternate method, which may be found in old demos is simply put its contents into a Set-type attribute:<\/p>\n\t If $MySet and $MyList both have the value [cats;dogs]: the following have different outcomes:<\/p>\n\tkey:value;<\/code> <\/p>\n{Tinderbox: 1;Storyspace: {Editor: 2; Reader:3}}<\/code> <\/blockquote>\nTinderbox<\/code>\\\" and a value of 1<\/code>. The second has a key of \\\"Storyspace<\/code>\\\" and the value that is itself a dictionary, {Editor: 2; Reader:3}<\/code>.<\/p>\n$MyDictionary={cat:animal; dog:animal; rock: mineral};<\/code> <\/blockquote>\n\t$MyDictionary=$MyDictionary.add(\\\"cat:animal\\\").add(\\\"dog:animal\\').add(\\\"rock: mineral\\\");<\/code> <\/blockquote>\n$MyDictionary=dictionary(\\\"cat:animal; dog:animal; rock: mineral\\\");<\/code> <\/blockquote>\n{}<\/code> method, or using the dictionary()<\/b> operator is explicit and indicates intent unambiguously when parsed by Tinderbox. See dictionary()<\/a> for usage.<\/p>\n$MyDictionary = dictionary(\\\"cat:animal; dog:animal; rock: mineral\\\");<\/code> <\/blockquote>\n\t$MyDictionary = $MyDictionary + \\\"cat:mammal\\\";<\/code> <\/blockquote>\nA-za-z0-9<\/code> or underscore\/hyphen\/period (the period might be needed for a decimal number value).<\/p>\n$MyDictionary = $MyDictionary + {apple:plant};<\/code> <\/blockquote>\n\t$MyDictionary += {apple:plant}\\\";<\/code> <\/blockquote>\n$MyString = \\\"apple:plant\\\"; $MyDictionary += $MyString;<\/code> <\/blockquote>\n\tvar:string vKey = \\\"apple:plant\\\"; $MyDictionary += vKey;<\/code> <\/blockquote>\n$MyDictionary = $MyDictionary.add(\\\"apple:plant\\\");<\/code> <\/blockquote>\n$MyDictionary = dictionary(\\\"dog:animal; cat:animal; rock:mineral\\\");<\/code> <\/blockquote>\n\t$MyDictionary = $MyDictionary - \\\"dog\\\"; \/\/ gives \\\"cat:animal; rock:mineral\\\"<\/code> <\/blockquote>\n$MyDictionary -= \\\"dog\\\"; \/\/ gives \\\"cat:animal; rock:mineral\\\"<\/code> <\/blockquote>\n$MyDictionary[somekey] = \\\"\\\";<\/code> <\/blockquote>\n$MyString = \\\"dog\\\"; $MyDictionary -= $MyString;<\/code> <\/blockquote>\n\tvar:string vKey = \\\"dog\\\"; $MyDictionary -= vKey;<\/code> <\/blockquote>\nvDict=; $MyDictionary=;<\/code> <\/blockquote>\n$MyDictionary[apple] = \\\"pie\\\"<\/code> <\/blockquote>\n$MyDictionary.add(\\\"apple\\\",\\\"pie\\\");<\/code> <\/blockquote>\n$MyDictionary[key] += 1;<\/code> WRONG!<\/blockquote>\n$MyDictionary[key] = $MyDictionary[\\\"key\\\"] + 1;<\/code> <\/blockquote>\n$MyDictionary[apple] = \\\"\\\"<\/code> <\/blockquote>\n[]<\/code> (list or set) or {}<\/code> (dictionary) notation. This holds for creating dictionaries or setting key values. When retrieving a multi-value result pass the data to an appropriately type attribute or variable. The data can then be accessed using appropriate key or list address syntax. Examples of nested multi-value values:<\/p>\n\t$MyDictionary={cat:animal; dog:animal; rock:{granite:mineral;basalt:mineral}};<\/code> <\/blockquote>\n\t$MyDictionary={cat:animal; dog:{terrier:dog;labrador:dog}; rock:mineral};<\/code> <\/blockquote>\n[ ] <\/code>list notation. As a result, a trailing semi-colon will imply the intent of a last list item that is empty.<\/p>\n$MyDictionary = $MyDictionary+\\\"apple:plant\\\"<\/code> <\/blockquote>\n$MyNewDictionary = $MyDictionary+$MyOtherDictionary<\/code> <\/blockquote>\n$MyFirstDictionary = dictionary(\\\"apple:fruit; granite:mineral\\\");<\/code> <\/blockquote>\n\t$MyOtherDictionary = dictionary(\\\"pear:fruit; granite:rock\\\");<\/code> <\/blockquote>\n\t$MyDictionary = $MyFirstDictionary + $MyOtherDictionary;<\/code> <\/blockquote>\n.each(aKey){}<\/code> loop, where you might code:<\/p>\n\t$MyString = $MyDictionary[aKey];<\/code> <\/blockquote>\nif($MyDictionary[aKey]){$MyString = $MyDictionary[aKey];}else{$MyString = $MyDictionary[default];};<\/code> <\/blockquote>\nif($MyDictionary.contains(aKey)){$MyString = $MyDictionary[aKey];}else{$MyString = $MyDictionary[default];};<\/code> <\/blockquote>\n\tvar:list vKeyList = $MyDictionary.keys;\n\tvKeyList = vKeyList.sort; \/\/ Use .nsort if keys are numbers\n\tvar:list vSortResults; \/\/ Use List so it stays sorted\n\tvKeyList.each(aKey){\n\t\tvSortResults+=(aKey+\\\" | \\\"+$MyDictionary[aKey]);\n\t};\n\t\/\/Test\n\t\/\/$Text = vSortResults.format(\\\"\\n\\\"); <\/code><\/pre>\n.sort<\/code>), lexical case insensitive (.isort<\/code>) or numerical (.nsort<\/code>)<\/p>\n$MyDictionary = dictionary({Dog: animal; Crocus: plant});<\/code> <\/blockquote>\n{Tinderbox: 1;Storyspace: {Editor: 2; Reader:3}}<\/code> <\/blockquote>\nTinderbox<\/code>\\\" and a value of 1<\/code>. The second has a key of \\\"Storyspace<\/code>\\\" and the value that is itself a dictionary, {Editor: 2; Reader:3}<\/code> .<\/p>\n
\n$MyDictionary[\\\"pie\\\"] = \\\"apple;lemon;quince\\\"<\/code> <\/blockquote>\n
\n\n
0<\/code>).<\/p>\n[ ]<\/code> List definition:<\/p>\n\t$MyList=[Frogs;Dogs;Logs];<\/code> <\/blockquote>\n$MyList=\\\"Frogs;Dogs;Logs\\\";<\/code> NOTE: do not use this for new code!<\/blockquote>\nplanes;trains;automobiles<\/code> not [planes;trains;automobiles]<\/code>. 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. <\/p>\n+<\/code> 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:<\/p>\n\t$PetTypes=$PetTypes+[rabbits];<\/code> adds the new value<\/blockquote>\n\t$PetTypes=$PetTypes+[rabbits];<\/code> unlike a Set, this adds a second instance of \\\"dogs\\\" to the end<\/i> of the List.<\/blockquote>\n+=<\/code> increment<\/a> operator can also be used. If the List is \\'cats;dogs;frogs\\':<\/p>\n\t$PetTypes=$PetTypes+[cats;frogs];<\/code> this gives a value of \\'cats;dogs;frogs;cats;frogs\\'; the new values appended to the list in the order supplied.<\/blockquote>\n[]<\/code> list declaration method:<\/p>\n\t$PetTypes= [rabbits;hamsters]+$PetTypes;<\/code> <\/blockquote>\n$PetTypes=$PetTypes+[[rabbits;bunnies]];<\/code> \n-<\/code> (minus) removes the supplied value(s) if present. Importantly, this removes all<\/i> occurrences if the deleted item;<\/p>\n\t$PetTypes=$PetTypes-[dogs];<\/code> leaves only \\\"cats\\\" as a value.<\/blockquote>\n+=<\/code> increment operator can also be used. If the List is \\'cats;dogs;frogs\\':<\/p>\n\t$PetTypes=$PetTypes+[cats;frogs];<\/code> this gives a value of \\'cats;dogs;frogs;cats;frogs\\'; the new values appended to the list in the order supplied.<\/blockquote>\n-=<\/code> decrement<\/a> operator can also be used. If the Set is \\'cats;dogs;frogs\\':<\/p>\n\t$PetTypes=$PetTypes-[cats;frogs];<\/code> this leaves only \\'dogs\\' as a value.<\/blockquote>\nList[1]<\/code> addresses item #2, whilst List[0]<\/code> addresses the first. To replace item #3 in a list (assuming a big enough list):<\/p>\n\t$MyList=[Frogs;Dogs;Logs];<\/code> <\/blockquote>\n\t$MyList[2]=[Pogs];<\/code> results in a list of \\\"Frogs;Dogs;Pogs\\\"<\/blockquote>\n[ 1; [2;3]; 4]<\/code> <\/blockquote>\n$MyList = [1] + [2;3]<\/code> <\/blockquote>\n$MyList += [2;3]<\/code> <\/blockquote>\n1;2;3<\/code> and not<\/b> 1;[2;3]<\/code>. To add a sublist to a list, use the operator list.extend()<\/a>. Thus:<\/p>\n\t$MyList = [1].extend( [2;3])<\/code> <\/blockquote>\n[1;[2;3]]<\/code>.<\/p>\n$Status([this;parent])=\\\"urgent\\\";<\/code> <\/blockquote>\n$DisplayedAttributes=[MyList;MyString];<\/code> <\/blockquote>\n$DisplayedAttributes=\\\"MyList;MyString\\\";<\/code> <\/blockquote>\n$MyTestList = [1;[a;b];3];<\/code> <\/blockquote>\n$MyString = $MyTestList[1];<\/code> results in \\'[a;b]\\'<\/blockquote>\n$MyString = $MyTestList[1].substr(1,-1);<\/code> results in \\'[a;b]\\'<\/blockquote>\n$MyString = $MyTestList[1][1];<\/code> results in \\'b\\'<\/blockquote>\n$MyList=$MyList.unique;<\/code> <\/blockquote>\n$MySet=$MyList;<\/code> (deprecated in favour of the method above)<\/blockquote>\n$MySet=$MySet + [dogs];<\/code> gives \\'cats;dogs\\'<\/blockquote>\n\t$MyList=$MyList + [dogs];<\/code> gives \\'cats;dogs;dogs\\'<\/blockquote>\n