7. Symbols

This package defines several symbol-related features that were missing from Emacs Lisp.

7.1 Property Lists

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

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 function is 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.

Macro: 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.

7.2 Creating Symbols

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.

XEmacs note: As of XEmacs 21.0, an uninterned symbol remains uninterned even after being dumped to bytecode. Older versions of Emacs didn’t distinguish the printed representation of interned and uninterned symbols, so their names had to be treated more carefully.

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.

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.