Elisp: Property List

By Xah Lee. Date: . Last updated: .

What is Property List

Property List (aka plist) is a List , but to be interpreted as list of pairs, like this:

'(:key1 value1 :key2 value2 etc)

Property list is not supposed to have duplicate keys, and should always have even length.

Key should be lisp Symbols , value can be any lisp object.

Typically, the key name start with a colon :

Use of Property List

Property List is used as a simplest form of (key and value) pairs.

Property list is used extensively in emacs.

The 2 major use of property list are:

Property list isn't a generic data structure. If you have more than ten items, you probably should use Association List or Hash Table .

Get a Key's Value

plist-get

(plist-get PLIST PROP)

  • return the value of key PROP from property list PLIST.
  • If key does not exist, return nil.
  • Existence of key is checked with eq. 〔see Elisp: Equality Test
(plist-get '(x 1 y 2) 'y) ; 2
(plist-get '(x 1 y 2) 'b) ; nil
lax-plist-get

similar to plist-get, but compare key using equal.

Add / Modify item

plist-put

(plist-put PLIST PROP VAL)

  • add or change the value of key PROP in PLIST to VAL. The new plist is returned.
  • Old plist may or may not be changed.
  • Always use setq on original variable.
  • Existence of key is checked with eq.
;; create a var xx with value of property list
(setq xx '(a 1 b 2))

;; set value to a existing key
(setq xx (plist-put xx 'b 3))

xx
;; (a 1 b 3)
lax-plist-put

similar to plist-put, but compare key using equal.

Check Key Existence

plist-member
  • (plist-member PLIST PROP)
  • Return true if PLIST has the property PROP.
  • The PROP is a symbol.
  • Unlike plist-get, this allows you to distinguish between a missing property and a property with the value nil.
  • The return value is actual the tail of PLIST whose car is PROP.
  • 〔see Elisp: Cons Cell
(setq xx '(a 1 b 2))

;; check if a key exist
(plist-member xx 'b)
;; (b 2)

Reference

Emacs Lisp, list

Special Lists

List Structure