GNU Info

(cl)Property Lists

---

Next: Creating Symbols Prev: Symbols Up: Symbols

---

Enter node , (file) or (file)node

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 legal to use `getf' as a `setf' place, in which case its
     PLACE argument must itself be a legal `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.