Skip to main content

get-properties

get-properties Function

Syntax:

get-properties plist indicator-list → indicator, value, tail

Arguments and Values:

plist—a property list.

indicator-list—a proper list (of indicators).

indicator—an object that is an element of indicator-list.

value—an object.

tail—a list.

Description:

get-properties is used to look up any of several property list entries all at once.

It searches the plist for the first entry whose indicator is identical to one of the objects in indicator-list. If such an entry is found, the indicator and value returned are the property indicator and its associated property value, and the tail returned is the tail of the plist that begins with the found entry (i.e., whose car is the indicator). If no such entry is found, the indicator, value, and tail are all nil.

Examples:

(setq x ’()) → NIL 
(setq \*indicator-list\* ’(prop1 prop2)) → (PROP1 PROP2) 
(getf x ’prop1) → NIL 
(setf (getf x ’prop1) ’val1) → VAL1 
(eq (getf x ’prop1) ’val1) → true 
(get-properties x \*indicator-list\*) → PROP1, VAL1, (PROP1 VAL1) 
x → (PROP1 VAL1)

See Also:

get, getf

Expanded Reference: get-properties​

Basic usage​

get-properties searches a property list for the first indicator that appears in the given indicator list. It returns three values: the indicator found, its value, and the tail of the plist starting at that indicator.

(get-properties '(:name "Alice" :age 30 :email "a@b.com")
                '(:age :email))
=> :AGE
=> 30
=> (:AGE 30 :EMAIL "a@b.com")

When no indicator matches​

When none of the indicators are found, all three return values are NIL.

(get-properties '(:x 1 :y 2) '(:a :b :c))
=> NIL
=> NIL
=> NIL

Searching for the first of several properties​

get-properties finds the first property in the plist that matches any indicator in the list. This is useful for checking which of several alternatives is present.

(get-properties '(:width 100 :height 200 :color red)
                '(:color :width))
=> :WIDTH
=> 100
=> (:WIDTH 100 :HEIGHT 200 :COLOR RED)

Distinguishing absent properties from NIL values​

Unlike getf, get-properties can distinguish a missing property from one with a NIL value by checking the tail.

;; Property exists with NIL value
(multiple-value-bind (indicator value tail)
    (get-properties '(:debug nil :verbose t) '(:debug))
  (values (not (null tail)) value))
=> T
=> NIL

;; Property does not exist
(multiple-value-bind (indicator value tail)
    (get-properties '(:verbose t) '(:debug))
  (values (not (null tail)) value))
=> NIL
=> NIL

Iterating through multiple properties​

The tail return value allows progressive searching through a property list.

(let ((plist '(:a 1 :b 2 :a 3 :c 4)))
  (multiple-value-bind (ind val tail)
      (get-properties plist '(:a))
    (format nil "First :A is ~A, remaining plist: ~S" val (cddr tail))))
=> "First :A is 1, remaining plist: (:B 2 :A 3 :C 4)"