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 sourcePropList

Operator 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] sourcePropList

Operator 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 sourcePropList

Operator 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] sourcePropList

Operator 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] sourcePropList

Operator 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]} propertyList2

matchingProperties( 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

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] propertyList2

excludeProperties( 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:

• MatchingProperties Function