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] sourcePropertyList [with | using] mapPropertyList

rename [property | {the} properties] {with | using} mapPropertyList [of | in] sourcePropertyList

Operator Syntax:

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

 

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