These functions augment the standard Emacs Lisp functions
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.
This function is like
get, except that if the property is not found, the default argument provides the return value. (The Emacs Lisp
getfunction always uses
nilas the default; this package's
cl-getis equivalent to Common Lisp's
setf-able; when used in this fashion, the default argument is allowed but ignored.
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
nilif there was no such property. (This function was probably omitted from Emacs originally because, since
getdid 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
nilwas close enough to
cl-rempropfor most purposes.)
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
eqto property, the following odd-numbered element is returned. Otherwise, default is returned (or
nilif no default is given).
In particular,(get sym prop) == (cl-getf (symbol-plist sym) prop)
It is valid to use
setfplace, in which case its place argument must itself be a valid
setfplace. 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 (cl-getf (symbol-plist sym) prop) val)
cl-getfunctions are also
setf-able. The fact that
defaultis ignored can sometimes be useful:(cl-incf (cl-get 'foo 'usage-count 0))
usage-countproperty is incremented if it exists, or set to 1 (an incremented 0) otherwise.
When not used as a
cl-getfis just a regular function and its place argument can actually be any Lisp expression.
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
)), whereas if it occurs later, this simply uses
setcdrto splice out the property and value cells.