get

get Accessor

Syntax:

get symbol indicator &optional default → value

(setf (get symbol indicator &optional default**)** new-value**)**

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:

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.

get

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 

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.

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

Expanded Reference: get

Basic property access

get retrieves a property value from a symbol's property list, identified by an indicator tested with eq.

(let ((sym (make-symbol "PERSON")))
  (setf (get sym 'name) "Alice")
  (setf (get sym 'age) 30)
  (values (get sym 'name)
          (get sym 'age)))
=> "Alice"
=> 30

Default value for missing properties

When a property is not found, get returns nil by default, or an optional default value.

(let ((sym (make-symbol "ITEM")))
  (setf (get sym 'color) 'blue)
  (values (get sym 'color)
          (get sym 'weight)
          (get sym 'weight 'unknown)))
=> BLUE
=> NIL
=> UNKNOWN

Setting properties with setf

(setf (get ...) value) creates a new property or updates an existing one.

(let ((sym (make-symbol "CONFIG")))
  (setf (get sym 'debug) nil)
  (setf (get sym 'verbose) t)
  (get sym 'debug))
=> NIL

Using symbols as simple data records

Property lists on gensyms can serve as lightweight record-like structures.

(defun make-point (x y)
  (let ((pt (gensym "POINT")))
    (setf (get pt 'x) x)
    (setf (get pt 'y) y)
    pt))

(defun point-distance (p1 p2)
  (let ((dx (- (get p1 'x) (get p2 'x)))
        (dy (- (get p1 'y) (get p2 'y))))
    (sqrt (+ (* dx dx) (* dy dy)))))

(let ((a (make-point 0 0))
      (b (make-point 3 4)))
  (point-distance a b))
=> 5.0

Indicators are compared with eq

Because get uses eq for comparison, symbols should be used as indicators rather than numbers or strings.

(let ((sym (make-symbol "TEST")))
  (setf (get sym 'status) 'active)
  (values (get sym 'status)
          (get sym 'STATUS)))
=> ACTIVE
=> ACTIVE

Equivalence with getf on symbol-plist

(get symbol indicator) is equivalent to (getf (symbol-plist symbol) indicator).

(let ((sym (make-symbol "EQ-TEST")))
  (setf (get sym 'key) 'value)
  (eq (get sym 'key)
      (getf (symbol-plist sym) 'key)))
=> T