Property List Operators
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.
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:
add {the} properties {of} additionalPropList to sourcePropListOperator Syntax:
sourcePropList adding {property | {the} properties {of}} additionalPropList
If a property in additionalPropList is already present in sourcePropList, that property is ignored. If additionalPropList is empty, the command does nothing.
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] sourcePropListOperator Syntax:
sourcePropList replacing {property | {the} properties {of}} replacementPropList
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.
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:
remove {the} properties {of} propertiesToRemove from sourcePropListOperator Syntax:
sourcePropList removing {property | {the} properties {of}} propertiesToRemove
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.
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}