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 text
• quotes (optional): This property defines the manner in which values in the list are quoted. By default, the quotes value is set to "Auto". See the defaultQuoteFormat global property for other options.
• indent (optional): This property can be set to a text value that will be used for indenting items in the list. If you set an indent value, 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 and quotes are set initially:

• prefix: "["
• separator: ","
• suffix: "]"
• quotes: "Auto"

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 DefaultQuoteFormat Global Property

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, or one of "None", "Standard" or "Auto" (the default). See the defaultQuoteFormat global property for a full description.
• 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 an indent value, 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: Auto
• emptyRepresentation: {:}
• 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 DefaultQuoteFormat Global Property

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
• insert Command

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 listInsertionMode Local Property
• insert Command

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 first or last, 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:

• Checking Object Contents