The commands and operators described here modify a property list to change the set of properties that it contains.
Use the add properties or replace properties commands to add properties or possibly replace some properties. Use the remove properties and retain properties commands to remove some properties. Use the rename properties command to change the names of some of an object's properties.
To perform these operations without affecting an existing object, use the corresponding operator instead of the command.
On this page:
Add Properties Command, Adding Properties Operator
Behavior: The add properties command and adding properties operator add the properties of one property list or object to those of an existing property list or object if those properties are not already present. Compare this to the replace properties command, which overrides existing values.
Use the add properties command to add new properties to an existing property list or object.
Use the adding properties operator to combine the properties of two different property lists or objects to create a new property list. If a property appears in both property lists when adding, the properties in the original sourcePropList always take precedence over those in additionalPropList.
Command Syntax:
Operator Syntax:
If a property in additionalPropList is already present in sourcePropList, that property is ignored. If additionalPropList is empty, the command does nothing.
Reading Syntax Definitions
Syntax definitions for language elements follow these formatting guidelines:
- boldface: Indicates words and characters that must be typed exactly
- italic: Indicates expressions or other variable elements
- {} (curly braces): Indicate optional elements.
- [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.
Example syntax:
In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".
Example:
put {A:1, C:3} into myObj
add properties {B:2, C:99, D:4} to myObj -- Results in property list '{A:1, B:2, C:3, D:4}'. The add properties command does not replace the preexisting value of key C:.
Example:
put {A:1,C:3} into firstProps -- start with a simple property list
put firstProps adding properties {B:2, C:99, D:4} into newProps
put newProps -- {A:1, B:2, C:3, D:4}
Replace Properties command, Replacing Properties operator
Behavior: The replace properties command and replacing properties operator add the properties of one property list or object to an existing property list or object or replaces the existing values if those properties are already present. Compare this to the add properties command, which will not override existing values.
Use the replace properties command to add new properties and replace existing properties within an existing property list or object.
Use the replacing properties operator to combine the properties of two different property lists or objects to create a new property list, overriding properties in the first property list with any corresponding properties from the second property list.
Command Syntax:
replace {the} properties {of} replacementPropList [of | in] sourcePropList
Operator Syntax:
If a property in replacementPropList is already present in sourcePropList, that property is replaced with the new value. Other values from replacementPropList are added to those in sourcePropList. If replacementPropList is empty, sourcePropList is unchanged.
Reading Syntax Definitions
Syntax definitions for language elements follow these formatting guidelines:
- boldface: Indicates words and characters that must be typed exactly
- italic: Indicates expressions or other variable elements
- {} (curly braces): Indicate optional elements.
- [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.
Example syntax:
In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".
Example:
put {A:1, B:2, C:3} into myObj
replace properties {B:"bunny", D:"dog"} of myObj -- Results in property list '{A:"1", B:"bunny", C:"3", D:"dog"}'
Example:
put {A:1,C:3} into firstProps -- start with a simple property list
put firstProps adding properties {B:2, C:99, D:4} into newProps
put newProps replacing {B:22, D:44} -- {A:1, B:22, C:3, D:44}
Remove Properties command, Removing Properties operator
Behavior: The remove properties command and removing properties operator remove the indicated properties from an existing property list or object. Compare this behavior to the retain properties command, which removes all properties that aren't explicitly being retained.
Use the remove properties command to remove some properties from an existing property list or object.
Use the removing properties operator to create a new property list that is a copy of one property list with some properties removed.
Command Syntax:
Operator Syntax:
The propertiesToRemove can be the name of a single property, a list of property names, or a property list. If a property list is given, its values will be ignored but its keys will be used as the list of properties to remove. Trying to remove properties that are not present in sourcePropList has no effect.
Reading Syntax Definitions
Syntax definitions for language elements follow these formatting guidelines:
- boldface: Indicates words and characters that must be typed exactly
- italic: Indicates expressions or other variable elements
- {} (curly braces): Indicate optional elements.
- [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.
Example syntax:
In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".
Example:
put {A:1, B:2, C:3} into myObj
remove property {B:765} from myObj -- Results in property list '{A:1, C:3}'. The remove property command will remove the property even if the value provided with the property does not match the actual property list.
remove properties ["B","C","D"] from myObj -- Results in property list '{A:1}'
Example:
put {A:1,C:3} into firstProps -- start with a simple property list
put firstProps adding properties {B:2, C:99, D:4} into newProps
put newProps removing properties ("B","C") -- {A:1, D:4}
Retain Properties command, Retaining Properties operator
Behavior: The retain properties command and retaining properties operator remove any properties that are not explicitly requested to be retained. Compare this to the remove properties command, which removes just the explicitly named properties.
Use the retain properties command to remove all properties from an existing property list or object other than those that are requested to be retained.
Use the retaining properties operator to create a new property list from another, containing only the indicated properties from the original property list.
Command Syntax:
Operator Syntax:
The propertiesToRetain can be the name of a single property, a list of property names, or a property list. If a property list is given its values will be ignored but its keys will be used as the list of properties to retain. Trying to retain properties that are not present in sourcePropList has no effect.
Reading Syntax Definitions
Syntax definitions for language elements follow these formatting guidelines:
- boldface: Indicates words and characters that must be typed exactly
- italic: Indicates expressions or other variable elements
- {} (curly braces): Indicate optional elements.
- [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.
Example syntax:
In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".
Example:
put {A:1, B:2, C:3} into myObj
retain properties ["B","C","D"] of myObj -- Results in property list '{B:2, C:3}'
Example:
put {A:1,C:3} into firstProps -- start with a simple property list
put firstProps adding properties {B:2, C:99, D:4} into newProps
put newProps retaining ["B","D","E"] -- {B:2, D:4}
Rename Properties command, Renaming Properties operator
Behavior: The rename properties command and the renaming properties operator change the name of one or more properties in a property list.
The properties that are to be renamed are specified using a property list "map". The keys in the map are names of properties in the existing property list, and the values in the map are the new names for those properties.
It is possible that not all of the keys in the map will match property names in the existing property list. Any that don't match are ignored. It is also possible that there might be existing properties for which there is no matching entry in the map. If so, those properties are left unchanged.
Use the rename properties command to rename properties within an existing property list or object.
Use the renaming properties operator to create a modified property list on the fly, with properties renamed.
Command Syntax:
rename [property | {the} properties] {with | using} mapPropertyList [of | in] sourcePropertyList
Operator Syntax:
Reading Syntax Definitions
Syntax definitions for language elements follow these formatting guidelines:
- boldface: Indicates words and characters that must be typed exactly
- italic: Indicates expressions or other variable elements
- {} (curly braces): Indicate optional elements.
- [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.
Example syntax:
In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".
Example:
put {A:1, B:2, C:3} into myObj
rename property {b:"bread", D:"donuts"} from myObj -- Results in property list '{A:1, bread:2, C:3}'.
Example:
set cat to {name:"Whiskers", type:"shorthair", color:"gray-striped"}
rename property {type:"breed"} of cat
put cat —> {breed:"shorthair", color:"gray-striped", name:"Whiskers"}
Example:
put {x:17, y:42} renaming {x:"time", y:"score"} —> {score:42, time:17}
Eggplantsoftware.com | Documentation Home | User Forums | Support | Copyright © 2022 Eggplant