Next: Creating Symbols, Up: Symbols
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.
This function is like
get
, except that if the property is not found, the default argument provides the return value. (The Emacs Lispget
function always usesnil
as the default; this package'scl-get
is equivalent to Common Lisp'sget
.)The
cl-get
function issetf
-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
nil
if there was no such property. (This function was probably omitted from Emacs originally because, sinceget
did not allow a default, it was very difficult to distinguish between a missing property and a property whose value wasnil
; thus, setting a property tonil
was close enough tocl-remprop
for 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
eq
to property, the following odd-numbered element is returned. Otherwise, default is returned (ornil
if no default is given).In particular,
(get sym prop) == (cl-getf (symbol-plist sym) prop)It is valid to use
cl-getf
as asetf
place, in which case its place argument must itself be a validsetf
place. The default argument, if any, is ignored in this context. The effect is to change (viasetcar
) 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)The
get
andcl-get
functions are alsosetf
-able. The fact thatdefault
is ignored can sometimes be useful:(cl-incf (cl-get 'foo 'usage-count 0))Here, symbol
foo
'susage-count
property is incremented if it exists, or set to 1 (an incremented 0) otherwise.When not used as a
setf
form,cl-getf
is 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(setf
place(cddr
place))
, whereas if it occurs later, this simply usessetcdr
to splice out the property and value cells.