13.4.2 Property List Functions for Objects

Once upon a time, only symbols had property lists. Now, several other object types, including strings, extents, faces and glyphs also have property lists.

Function: symbol-plist symbol

This function returns the property list of symbol.

Function: object-plist object

This function returns the property list of object. If object is a symbol, this is identical to symbol-plist.

Function: setplist symbol plist

This function sets symbol’s property list to plist. Normally, plist should be a well-formed property list, but this is not enforced.

(setplist 'foo '(a 1 b (2 3) c nil))
     ⇒ (a 1 b (2 3) c nil)
(symbol-plist 'foo)
     ⇒ (a 1 b (2 3) c nil)

For symbols in special obarrays, which are not used for ordinary purposes, it may make sense to use the property list cell in a nonstandard fashion; in fact, the abbrev mechanism does so (see Abbrevs). But generally, its use is discouraged. Use put instead. setplist can only be used with symbols, not other object types.

Function: get object property &optional default

This function finds the value of the property named property in object’s property list. If there is no such property, default (which itself defaults to nil) is returned.

property is compared with the existing properties using eq, so any object is a legitimate property.

See put for an example.

Function: put object property value

This function puts value onto object’s property list under the property name property, replacing any previous property value. The put function returns value.

(put 'fly 'verb 'transitive)
     ⇒'transitive
(put 'fly 'noun '(a buzzing little bug))
     ⇒ (a buzzing little bug)
(get 'fly 'verb)
     ⇒ transitive
(object-plist 'fly)
     ⇒ (verb transitive noun (a buzzing little bug))

Function: remprop object property

This function removes the entry for property from the property list of object. It returns t if the property was indeed found and removed, or nil if there was no such property. (This function was probably omitted from Emacs originally because, since get did not allow a default, it was very difficult to distinguish between a missing property and a property whose value was nil; thus, setting a property to nil was close enough to remprop for most purposes.)