11.9.1 Working With Normal Plists

Function: plist-get plist property &optional default

This function extracts a value from a property list. The function returns the value corresponding to the given property, or default if property is not one of the properties on the list.

Function: plist-put plist property value

This function changes the value in plist of property to value. If property is already a property on the list, its value is set to value, otherwise the new property value pair is added. The new plist is returned; use (setq x (plist-put x property value)) to be sure to use the new value. The plist is modified by side effects.

Function: plist-remprop plist property

This function removes from plist the property property and its value. The new plist is returned; use (setq x (plist-remprop x property)) to be sure to use the new value. The plist is modified by side effects.

Function: plist-member plist property

This function returns t if property has a value specified in plist.

In the following functions, if optional arg nil-means-not-present is non-nil, then a property with a nil value is ignored or removed. This feature is a virus that has infected old Lisp implementations (and thus E-Lisp, due to RMS’s enamorment with old Lisps), but should not be used except for backward compatibility.

Function: plists-eq a b &optional nil-means-not-present

This function returns non-nil if property lists A and B are eq (i.e. their values are eq).

Function: plists-equal a b &optional nil-means-not-present

This function returns non-nil if property lists A and B are equal (i.e. their values are equal; their keys are still compared using eq).

Function: canonicalize-plist plist &optional nil-means-not-present

This function destructively removes any duplicate entries from a plist. In such cases, the first entry applies.

The new plist is returned. If nil-means-not-present is given, the return value may not be eq to the passed-in value, so make sure to setq the value back into where it came from.