Go to the first, previous, next, last section, table of contents.

# Symbols

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

- Property Lists: `get*', `remprop', `getf', `remf'
- Creating Symbols: `gensym', `gentemp'

## 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.

@secno=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. (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 first, previous, next, last section, table of contents.