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.

ClosedSetting 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}

Note: 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 not set for lists, so the setting of the defaultQuoteFormat global 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 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 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 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: Standard
  • 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 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

Tip: 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]'

Tip: 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 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:

 

This topic was last updated on August 19, 2021, at 03:30:51 PM.

Eggplant icon Eggplantsoftware.com | Documentation Home | User Forums | Support | Copyright © 2022 Eggplant