Local and Global Properties for Lists and Property Lists
The SenseTalk global and local properties described here control behaviors of lists and property lists in your scripts. You can set or change these options to affect formatting, insertion methods, and other actions to customize your environment.
For complete information about lists and property lists in SenseTalk, see Lists and Property Lists.
Setting or Changing Local and Global Property Values
You can set a global property value with the SenseTalk commands Set or Put. Note that when you reference one of these properties, you must use the word the before the property name to distinguish it from an ordinary variable.
Examples:
set the searchrectangle to [1,2,2,3]
put 2 into the remoteworkinterval
You can add or change specific named properties within a global property like this:
set the namedColors.pink to color("RGB,1.0,0.5,0.5") -- Adds pink to the namedColors global property and defines its RGB color value
set the listFormat's separator to " & " -- Sets the separator property of the listFormat global property
Properties can also be set or updated by using the setoption or setoptions commands. The setoption command lets you update a single property, and setoptions lets you update multiple properties.
Examples:
setoption searchrectangle, [1,2,2,3]
setoptions {searchrectangle: [1,2,2,3], scriptlogging: yes}
Because setoption and setoptions are specific for use with global and local properties, you omit the word the from the property name in the command syntax for these commands.
For additional information about working with local and global properties, see Local and Global Properties in SenseTalk.
the listFormat Global Property
Values: A property list including three required values, and optionally two additional values:
prefix: The character that precedes the list when converted to text.separator: The character that appears between each item of the list when converted to text.suffix: The character that ends the list when converted to textquotes(optional): This property defines the manner in which values in the list are quoted. By default, thequotesvalue is not set for lists, so the setting ofthe defaultQuoteFormatglobal property controls quoting of list values.indent(optional): This property can be set to a text value that will be used for indenting items in the list. If you set anindentvalue, individual list items are displayed on separate lines with values indented by multiples of the indent value, according to the nesting of the structure.
Default: Only the three required values are set initially:
prefix: [separator: ,suffix: ]
Behavior: This global property defines the format used to convert a list into a text format. When displaying a list as text, the list is surrounded by the prefix and suffix values, with the separator value used between each item of the list.
Predefined values for the listFormat include boxListFormat, jsonListFormat, and standardListFormat.
Example:
set the ListFormat's separator to period // Uses the 'period' keyword to set the ListFormat's separator to "."
Example:
set the listFormat's quotes to "^"
put ["cheese","meat","fruit"] // Displays '[^cheese^,^meat^,^fruit^]'
Example:
set the listformat to {separator:";"}
put ["cheese","meat","fruit"] // Displays 'cheese;meat;fruit'
Example:
set the ListFormat.prefix to "-->"
put ["cheese","meat","fruit"] // Displays '-->cheese,meat,fruit]'
Example:
set the ListFormat to {separator:";",quotes:"^"}
put ["cheese","meat","fruit"] //Displays '^cheese^;^meat^;^fruit^'
Example:
set the listformat to boxListFormat
put (1,2,3,5,7) // Displays 【1】 【2】 【3】 【5】 【7】
Example:
set the listformat to jsonListFormat
put (1,2,3,5,7)
The output from the above example would display in the Run window as follows:
[
1,
2,
3,
5,
7
]
Example:
set the listFormat.prefix to "[["
set the listFormat's suffix to "]]"
put [1,2,3,4] // Displays '[[1,2,3,4]]'
set the listFormat's separator to " & "
set the listFormat's quotes to ["<",">"]
put [5,6,7,8] // Displays '[[<5> & <6> & <7> & <8>]]'
set the listFormat's indent to " "
put [1,[10,20,30],2]
The final put command from this example would display in the Run window as follows:
[[
<1> &
[[
<10> &
<20> &
<30>
]] &
<2>
]]
Example:
set the listformat to standardListFormat
put [1,2,3,5,7] //Displays '[1,2,3,5,7]'
Related:
The split by and joined by operators, described in Miscellaneous Operators, provide ways to explicitly convert text to lists and vice versa. For more information about working with lists, see Lists and Property Lists.
the propertyListFormat Global Property
Values: A property list that can contain these property values:
prefix: The character that precedes the list when converted to text.entrySeparator: The character that appears between each key/value pair of the list when converted to text.keySeparator: The character that appears between a key and its value when converted to text.suffix: The character that ends the list when converted to text.quotes: The character or characters used to quote property values when converted to text.emptyRepresentation: The character or characters used if the object has no properties when it is converted to text.indent(optional): This property can be set to a text value that will be used for indenting items in the list. If you set anindentvalue, individual list items are displayed on separate lines with values indented by multiples of the indent value, according to the nesting of the structure.asTextEnabled:True,False
Default: See the Behavior section below.
prefix: {entrySeparator: ", " (comma and space)keySeparator: :suffix: }quotes:StandardemptyRepresentation: {:}asTextEnabled:True
Behavior: This global property defines the format used when converting a property list (object) into text.
If asTextEnabled is True (the default) when the text representation of an object is needed, the object is sent an asText function message to get its text representation. If the object does not respond to this message, its asText or asTextFormat property is used to obtain a text representation.
If asTextEnabled is False, or if none of the asText mechanisms yield a value, then the other values are used. In that case, the object's properties are listed (in alphabetical order of its keys) with each key (property name) preceding its value separated by the keySeparator (with a default value of ":") and the entries separated by the entrySeparator (which defaults to ", ").
Property values are quoted according to the quotes value (which defaults to Standard for property lists; see the defaultQuoteFormat global property). The entire text is surrounded by the prefix and suffix (default values " and " ). If the object has no properties, the value of the emptyRepresentation property (default "{:}" ) is used as its text representation.
If the keySeparator is set to empty, the object's keys are not listed, only its values.
The indent value can be set to a text value that will be used for indenting entries in the object. When set to anything other than empty, each entry is displayed on a separate line with each line indented by multiples of the indent value, according to the nesting of the structure.
Example:
set the propertyListFormat's entrySeparator to "*"
Example:
set the propertyListFormat's keySeparator to "%"
put {Capitol:"Lansing",Bird:"robin"} // Displays '[Bird%"robin", Capitol%"Lansing"]'
Example:
set the propertyListFormat to {entrySeparator:";"} // The keySeparator is empty, so only the values are displayed
put {Capitol:"Lansing",Bird:"robin"} // Displays 'robin;Lansing'
Example:
put {astext:"Michigan",Capitol:"Lansing",Bird:"robin"} // Displays 'Michigan'
set the propertyListFormat.asTextEnabled to false
put {astext:"Michigan",Capitol:"Lansing",Bird:"robin"} // Displays '{astext:"Michigan", Bird:"robin", Capitol:"Lansing"}'
Example:
set the propertyListFormat to {entrySeparator:"$",keySeparator:"*"}
put {Capitol:"Lansing",Bird:"robin"} // Displays 'Bird*robin$Capitol*Lansing'
Example:
replace properties {prefix:"[[", suffix:"]]", entrySeparator:"; ", \
keySeparator:" is "} in the propertyListFormat
put {A:1,C:3,B:2} -- Displays [[A is "1"; B is "2"; C is "3"]]
delete the propertyListFormat's keySeparator
set the propertyListFormat.quotes to "None"
put {A:1,C:3,B:2} -- Displays [[1; 2; 3]]
set the propertyListFormat.emptyRepresentation to "[[no properties]]"
put {:} -- Displays [[no properties]]
Related:
For more information about converting property lists to a text representation, see Lists and Property Lists.
the listInsertionMode Local Property
Values: item by item, nested
Default: the defaultListInsertionMode global property (originally set to item by item)
Behavior: This local property controls how items behave when you add a list of items to another list. With the property set to item by item, each item from the list being added is added individually. With the property set to nested, the list being added is added as a nested list.
The value of the listInsertionMode is local to each handler. When a handler begins running, the listInsertionMode in that handler is initially set to the value of the defaultListInsertionMode global property.
Example:
set the ListInsertionMode to nested // Changes the local property the ListInsertionMode from the default of "item by item"
Example:
set the listInsertionMode to nested
put ["maple","oak","pine"] into localtrees
insert ["willow","sassafras"] after localtrees
log localtrees // Displays '[maple,oak,pine,[willow,sassafras]]'
Example:
put [1,2,3,4] into list // [1,2,3,4]
put ["A","B"] into otherList // [A,B]
insert otherList after item 2 of list // [1,2,A,B,3,4]
set the listInsertionMode to "nested"
insert otherList after item 2 of list // [1,2,[A,B],A,B,3,4]
Example:
set Biggest to ["sun","earth"]
set Smallest to ["moon","you"]
log myNestedList(Biggest,Smallest,2) // Displays '[sun,[moon,you],earth]'
insert Smallest before item 2 of Biggest // The ListInsertionMode is still set to the default of "item by item"
log Biggest // Displays '[sun,moon,you,earth]'
to myNestedList InitialList,SecondaryList,position // Declares the custom function handler "myNestedList", with three parameters
set the ListInsertionMode to nested // Specifying the ListInsertionMode local property means the setting will be in effect only for the function handler and not the initial script handler
insert SecondaryList before item position of InitialList
return InitialList
end myNestedList
Use the listInsertionMode local property when you want to change the behavior only for the specific handler from which you call it. Use the defaultListInsertionMode global property (rather than the listInsertionMode local property) if you want the setting to persist and carry across scripts and handlers in the current runtime environment.
Related:
the defaultListInsertionMode Global Property
Values: item by item, nested
Default: item by item
Behavior: This global property controls how items behave when you add a list of items to another list. With the property set to item by item, each item from the list being added is added individually. With the property set to nested, the list being added is added as a nested list.
Example:
set the defaultListInsertionMode to nested
Example:
set Alignment to ["sun","earth"]
set the defaultListInsertionMode to "item by item"
insert ["moon","you"] after the first item of Alignment
put Alignment // Displays '[sun,moon,you,earth]'
Example:
set People to ["Susan","Joe","Ricky","Jennifer"]
set the defaultListInsertionMode to nested
insert ["Robert","Kelly"] into People
log People // Displays '[Susan,Joe,Ricky,Jennifer,[Robert,Kelly]]'
Example:
put ["A","B","C"] into Letters
set the defaultListInsertionMode to nested
insert [1,2] before item 2 of Letters
put Letters // Displays '[A,[1,2],B,C]'
Use the listInsertionMode local property when you want to change the behavior only for the specific handler from which you call it. Use the defaultListInsertionMode global property (rather than the listInsertionMode local property) if you want the setting to persist and carry across scripts and handlers in the current runtime environment.
Related:
the DuplicatePropertyKeyMode Global Property
Values: error, first, last, list
Default: error
Behavior: If the same key is repeated within a property list, this global property controls how it is handled.
- If this property is set to
error, an exception is thrown. - If this property is set to
firstorlast, only the first (or last) value given for that key is used; any duplicate keys are ignored. - If this property is set to
list, all of the values supplied for that key are accepted and combined into a list.
Example:
set the DuplicatePropertyKeyMode to error // Throws an error if there is a reference to a property list in the initial or any called handlers with duplicated keys, such as '{Capitol:"Lansing",Population:"9.928 million",Population:"26"}'
Example:
set the duplicatePropertyKeyMode to last
set meal to ({beverage:"Water",dessert:"Ice Cream",entree:"Hamburger",dessert:"Cake"})
log meal // Displays '{beverage:"Water", dessert:"Cake", entree:"Hamburger"}'
Example:
set the duplicatePropertyKeyMode to list
set meal to ({beverage:"Water",dessert:"Ice Cream",entree:"Hamburger",dessert:"Cake"})
log meal // Displays '{beverage:"Water", dessert:[Ice Cream,Cake], entree:"Hamburger"}'
Related:
For more information about working with property lists, see Property Lists.
the strictProperties Global Property
Values: True, False
Default: False
Behavior: This property controls what happens when you attempt to access a property that has not been set within a property list. When the strictProperties is set to false, SenseTalk returns empty as the value for undefined properties. If you set the strictProperties to true, accessing an undefined property throws an exception.
Example:
set the StrictProperties to true // Changes the default behavior so that an error occurs when referencing an undefined property
Example:
set the StrictProperties to true
put {Capitol:"Lansing",Bird:"robin",Population:"9.928 million"} into Michigan
Log Michigan's Song // Throws an error because 'Song' is not a defined property in the property list. If the StrictProperties is false, then the log command displays an empty message.
Example:
put a new object into emptyObj
put (property abc of emptyObj) is empty -- displays 'true'
set the strictProperties to true
put (property abc of emptyObj) is empty -- throws an exception
the objectContainsItemDefinition Global Property
Values: AsTextContains, NestedValueContains, KeyOrValueEquals
Default: AsTextContains
Behavior: This property controls how operators or functions access keys and values within a property list. If this property is set to AsTextContains (the default behavior) the containsItem function returns true if the object's text value contains the search value. When set to NestedValueContains, the operator is applied to each of the object's values and the expression yields true if any them contains the search value. Finally, a setting of KeyOrValueEquals returns true if the search value is equal to one of the object's keys or to one of its values.
Example:
set the objectContainsItemDefinition to KeyOrValueEquals // Checks both the object's keys and values to see if they match the search value
Example:
set State to {AsText:"Michigan",Capitol:"Lansing",Bird:"robin",Population:"9.928 million"}
log State contains "robin" // Diplays 'False'
set the objectContainsItemDefinition to NestedValueContains
log State contains "robin" // Displays 'True'
Example:
set PersonalInfo to {asText:"Robert",age:31,hair:"brown",height:"5 feet 11 inches",degrees:["BS","MS"]}
put "hair" is among the keys of PersonalInfo // Returns 'true'
put PersonalInfo contains "hair" // Returns 'false' because the text value of the property list is "Robert"
set the objectContainsItemDefinition to KeyorValueEquals
put "hair" is in PersonalInfo // Returns 'true' because hair is a key of the property list
put "BS" is in PersonalInfo // Returns 'false' because "BS" is neither a key nor value in the property list
set the objectContainsItemDefinition to NestedValueContains
put PersonalInfo contains "BS" // Returns 'true' because "BS" is a nested value in the property list
Related: