Accessor get

Syntax:

Arguments and Values:

symbol—a symbol.

indicator—an object.

default—an object. The default is nil.

value—if the indicated property exists, the object that is its value; otherwise, the specified default.

new-value—an object.

Description:

10.1.0 8 Barrett: Redundant with next paragraph. \funref{get} searches the \term{property list} of \param{symbol} for an indicator \funref{eq} to \param{indicator}.

\funref{get} returns the corresponding value of an indicator from the \term{property list} of \param{symbol} \funref{eq} to \param{indicator}, if one is found.get finds a property on the property list₂ of symbol whose property indicator is identical to indicator, and returns its corresponding property value. If there are multiple properties₁ with that property indicator, get uses the first such property. If there is no property with that property indicator, default is returned.

10.1.0 12 \macref{setf} may be used with \funref{get} to create a new property-value pair, possibly replacing an old pair with the same property name.setf of get may be used to associate a new object with an existing indicator already on the symbol's property list, or to create a new assocation if none exists. If there are multiple properties₁ with that property indicator, setf of get associates the new-value with the first such property. When a get form is used as a setf place, any default which is supplied is evaluated according to normal left-to-right evaluation rules, but its value is ignored.

Examples:

 (defun make-person (first-name last-name)
   (let ((person (gensym "PERSON")))
     (setf (get person 'first-name) first-name)
     (setf (get person 'last-name) last-name)
     person)) → MAKE-PERSON
 (defvar *john* (make-person "John" "Dow")) → *JOHN*
 *john* → #:PERSON4603
 (defvar *sally* (make-person "Sally" "Jones")) → *SALLY*
 (get *john* 'first-name) → "John"
 (get *sally* 'last-name) → "Jones"
 (defun marry (man woman married-name)
   (setf (get man 'wife) woman)
   (setf (get woman 'husband) man)
   (setf (get man 'last-name) married-name)
   (setf (get woman 'last-name) married-name)
   married-name) → MARRY
 (marry *john* *sally* "Dow-Jones") → "Dow-Jones"
 (get *john* 'last-name) → "Dow-Jones"
 (get (get *john* 'wife) 'first-name) → "Sally"
 (symbol-plist *john*)
→ (WIFE #:PERSON4604 LAST-NAME "Dow-Jones" FIRST-NAME "John")
 (defmacro age (person &optional (default ''thirty-something)) 
   `(get ,person 'age ,default)) → AGE
 (age *john*) → THIRTY-SOMETHING
 (age *john* 20) → 20
 (setf (age *john*) 25) → 25
 (age *john*) → 25
 (age *john* 20) → 25

Side Effects:

None.

Affected By:

None.

Exceptional Situations:

Should signal an error of type type-error if symbol is not a symbol.

See Also:

getf, symbol-plist, remprop

Notes:

 (get x y) ≡ (getf (symbol-plist x) y)

Numbers and characters are not recommended for use as indicators in portable code since get tests with eq rather than eql, and consequently the effect of using such indicators is implementation-dependent.

\code (get 'clyde 'species) \EV NIL (setf (get 'clyde 'species) 'elephant) \EV elephant (get 'clyde 'species) \EV ELEPHANT \endcode \param{Default} may be supplied to \funref{get} in this context; it is ignored by the \macref{setf} expander function for \funref{get}, but may be useful in such macros as \macref{push} that are related to \macref{setf}: \code (push item (get sym 'token-stack '(initial-item))) \endcode means approximately the same as \code (setf (get sym 'token-stack '(initial-item)) (cons item (get sym 'token-stack '(initial-item)))) \endcode which in turn would be treated as \code (setf (get sym 'token-stack) (cons item (get sym 'token-stack '(initial-item)))) \endcode

There is no way using get to distinguish an absent property from one whose value is default. However, see get-properties.

10.1.0 15 Using \funref{get} on the result of \funref{symbol-plist} does not work; the \term{symbol} itself must be given to \funref{get}. \funref{getf} can be used to extract properties from a disembodied property list.