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}
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:
retain {the} properties {of} propertiesToRetain [of | in] sourcePropListOperator Syntax:
sourcePropList retaining {property | {the} properties {of}} propertiesToRetain
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.
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] [of | in] sourcePropList [with | using] mapPropertyList
rename [property | {the} properties] {with | using} mapPropertyList [of | in] sourcePropListOperator Syntax:
sourcePropList renaming {property | {the} properties} {with | using} mapPropertyList
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}
MatchingProperties
Function
Behavior: The matchingProperties
function compares two property lists and returns a new property list containing just those properties which are present in both and which have equal values in both.
Syntax:
{the} properties [of | in] propertyList1 {that are} {also} [equal to | the same as | identical to | {found} in | {{shared} in} common [with | to] | shared by] {[{the | those} [properties | ones] | those] [of | in]} propertyList2matchingProperties( propertyList1 , propertyList2 {, caseSensitive} )
Example:
set product1 to {
color:red,
size:18,
style:"EMPIRE",
code:"6F-236",
vendor:"Gilford",
status:"discontinued"
}
set product2 to {
color:blue,
size:18,
style:"empire",
finish:"matte",
code:"6G-118",
vendor:"Gilford"
}
put the properties of product1 that are identical to product2
--> {size:18, style:"EMPIRE", vendor:"Gilford"}
put properties of product2 shared in common with those of product1
--> {size:18, style:"empire", vendor:"Gilford"}
put matchingProperties(product1, product2, Yes)
--> {size:18, vendor:"Gilford"}
put properties of product2 shared in common with those of product1 case-sensitive
--> {size:18, vendor:"Gilford"}
Related:
ExcludeProperties
Function
Behavior: The excludeProperties
function compares two property lists and returns a new property list containing the properties of the first property list which are different from those in the second property list (either the property isn't present in the second property list, or it has a different value). If all properties of the first property list are present in the second and have the same values, the result will be an empty property list.
Syntax:
{the} properties [of | in] propertyList1 [excluding | without | {that are} different from | [{that are} not | that aren't] [equal to | the same as]] [{the} [properties | ones] | those] {that are} {also} [{found} in | {{shared} in} common [with | to] | shared by | from | of] propertyList2excludeProperties( propertyList1 , propertyList2 {, caseSensitive} )
Example:
set product1 to {
color:red,
size:18,
style:"EMPIRE",
code:"6F-236",
vendor:"Gilford",
status:"discontinued"
}
set product2 to {
color:blue,
size:18,
style:"empire",
finish:"matte",
code:"6G-118",
vendor:"Gilford"
}
put the properties of product1 that are different from the properties of product2
--> {code:"6F-236", color:"red", status:"discontinued"}
put properties of product2 that aren't the same as those in product1
--> {code:"6G-118", color:"blue", finish:"matte"}
put excludeProperties(product1, product2, Yes)
--> {code:"6F-236", color:"red", status:"discontinued", style:"EMPIRE"}
put the properties of product2 excluding those in product1 case sensitive
--> {code:"6G-118", color:"blue", finish:"matte", style:"empire"}
Related: