Property List Operators

add properties, replace properties, remove properties, and retain properties commands

What they do

The add properties command adds the properties of one property list or object to an existing property list or object if those properties are not already present. The replace properties command is similar, and overrides existing properties with new values. The remove properties command removes the indicated properties from an existing property list or object. The retain properties command removes any properties that are not explicitly requested to be retained.

When to use them

Use the add properties, replace properties, remove properties and retain properties commands to change the properties of an existing property list or object. To combine or remove properties without affecting an existing object, use the adding properties, replacing properties, removing properties or retaining properties operators instead (see Expressions for more information).

Syntax:

add {the} properties {of} additionalPropList to sourcePropList
replace {the} properties {of} replacementPropList [of | in] sourcePropList
remove {the} properties {of} propertiesToRemove from sourcePropList
retain {the} properties {of} propertiesToRetain [of | in] sourcePropList
  • If a property in additionalPropList is already present in sourcePropList that property is ignored. If additionalPropList is empty, the command does nothing.
  • 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, the command does nothing.
  • The propertiesToRemove may 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.
  • The propertiesToRetain may 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, 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:.

replace properties (B:"bunny", D"dog") of myObj//Results in property list '(A:"1", B:"bunny", C:"3", D:"dog")'.

remove property (B:765) from myObj //Results in property list '(A:1, C:3, D:dog)'. 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 ("C") from myObj//Results in property list '(A:1, D:dog)'

retain properties ("D") of myObj //Results in property list '(D:dog)'

Example:

#Overrides Script

on Click ImagePL

add property (scale:(.5)) to ImagePL //Adds the scale property to the original message (the image property list) so that all overridden click commands search for the image at half size.

pass message //Passes the message along to the next object (the Click command). See Passing Messages for more information.

Click ImagePL

end Click

# Main script

start using Overrides //Prioritizes the library of override commands written in the Overrides script over the in-built commands in SenseTalk.

Click (name:"ChromeIcon")

adding, replacing, removing, retaining properties

Behavior: Each of these four operators works with a property list and produces a new property list containing a modified set of properties. The new property list is derived by adding or replacing properties coming from a second property list, by removing specified properties, or by removing all but a selected set of properties.

Use the adding properties operator to combine the properties of two different property lists or objects to create a new property list. The replacing properties operator combines 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. The removing properties operator removes some properties from one property list or object to create a new property list. The retaining properties operator creates a new property list from another, containing only the indicated properties from the original property list.

If a property appears in both property lists when adding, the properties in sourcePropList always take precedence over those in additionalPropList. The reverse is true when replacing, with properties from propsToReplace taking precedence over those in sourcePropList.

When removing properties, the propsToRemove may be the name of a single property, a list of property names, or a property list (whose values will be ignored but whose keys will be used as the properties to remove). Trying to remove properties that don't exist has no effect. The retaining operator is similar, but instead of specifying the properties to be removed, propsToRetain identifies the properties from the original property list that should be retained, with all others being discarded. The word "property" or "properties" is optional in all of these operators.

Syntax:

sourcePropList adding {property | {the} properties {of}} additionalPropList

sourcePropList removing {property | {the} properties {of}} propsToRemove

sourcePropList replacing {property | {the} properties {of}} propsToReplace

sourcePropList retaining {property | {the} properties {of}} propsToRetain

Example:

put (A:1,C:3) into firstProps -- start with a simple property list

Example:

put firstProps adding properties (B:2, C:99, D:4) into newProps

Example:

put firstProps -- unchanged: (A:1, C:3)

Example:

put newProps -- (A:1, B:2, C:3, D:4)

Example:

put newProps removing properties ("B","C") -- (A:1, D:4)

Example:

put newProps replacing (B:22, D:44) -- (A:1, B:22, C:3, D:44)

Example:

put newProps retaining ("B","D","E") -- (B:2, D:4)

See Also: the add properties, replace properties, remove properties, and retain properties commands in Lists and Property Lists.

 

This topic was last updated on October 30, 2019, at 02:28:10 PM.

Eggplant icon Eggplantsoftware.com | Documentation Home | User Forums | Support | Copyright © 2019 Eggplant