Next: Creating Symbols, Previous: Symbols, Up: Symbols

### 8.1 Property Lists

These functions augment the standard Emacs Lisp functions `get` and `put` for operating on properties attached to symbols. There are also functions for working with property lists as first-class data structures not attached to particular symbols.

— Function: get* symbol property &optional default

> This function is like `get`, except that if the property is not found, the default argument provides the return value. (The Emacs Lisp `get` function always uses `nil` as the default; this package's `get*` is equivalent to Common Lisp's `get`.)

> The `get*` function is `setf`-able; when used in this fashion, the default argument is allowed but ignored.

— Function: remprop symbol property

> This function removes the entry for property from the property list of symbol. It returns a true value 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.)

— Function: getf place property &optional default

> This function scans the list place as if it were a property list, i.e., a list of alternating property names and values. If an even-numbered element of place is found which is `eq` to property, the following odd-numbered element is returned. Otherwise, default is returned (or `nil` if no default is given).

> In particular,

>               (get sym prop)  ==  (getf (symbol-plist sym) prop)

> It is valid to use `getf` as a `setf` place, in which case its place argument must itself be a valid `setf` place. The default argument, if any, is ignored in this context. The effect is to change (via `setcar`) the value cell in the list that corresponds to property, or to cons a new property-value pair onto the list if the property is not yet present.

>               (put sym prop val)  ==  (setf (getf (symbol-plist sym) prop) val)

> The `get` and `get*` functions are also `setf`-able. The fact that `default` is ignored can sometimes be useful:

>               (incf (get* 'foo 'usage-count 0))

> Here, symbol `foo`'s `usage-count` property is incremented if it exists, or set to 1 (an incremented 0) otherwise.

> When not used as a `setf` form, `getf` is just a regular function and its place argument can actually be any Lisp expression.

— Special Form: remf place property

> This macro removes the property-value pair for property from the property list stored at place, which is any `setf`-able place expression. It returns true if the property was found. Note that if property happens to be first on the list, this will effectively do a `(setf` place `(cddr` place`))`, whereas if it occurs later, this simply uses `setcdr` to splice out the property and value cells.