Go to the previous, next chapter.
This package defines several symbol-related features that were missing from Emacs Lisp.
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.
@secno=2
These functions create unique symbols, typically for use as temporary variables.
{Function} gensym &optional x
This function creates a new, uninterned symbol (using make-symbol)
with a unique name. (The name of an uninterned symbol is relevant
only if the symbol is printed.) By default, the name is generated
from an increasing sequence of numbers, `G1000', `G1001',
`G1002', etc. If the optional argument x is a string, that
string is used as a prefix instead of `G'. Uninterned symbols
are used in macro expansions for temporary variables, to ensure that
their names will not conflict with "real" variables in the user's
code.
{Variable} *gensym-counter*
This variable holds the counter used to generate gensym names.
It is incremented after each use by gensym. In Common Lisp
this is initialized with 0, but this package initializes it with a
random (time-dependent) value to avoid trouble when two files that
each used gensym in their compilation are loaded together.
(Uninterned symbols become interned when the compiler writes them
out to a file and the Emacs loader loads them, so their names have to
be treated a bit more carefully than in Common Lisp where uninterned
symbols remain uninterned after loading.)
{Function} gentemp &optional x
This function is like gensym, except that it produces a new
interned symbol. If the symbol that is generated already
exists, the function keeps incrementing the counter and trying
again until a new symbol is generated.
The Quiroz `cl.el' package also defined a defkeyword
form for creating self-quoting keyword symbols. This package
automatically creates all keywords that are called for by
&key argument specifiers, and discourages the use of
keywords as data unrelated to keyword arguments, so the
defkeyword form has been discontinued.
@chapno=11
Go to the previous, next chapter.