Elisp: Property List

What is Property List (aka plist)

Property List 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. Typically they are Keyword Symbol (Colon Prefix)
• Value can be any lisp object.

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

Use of Property List

Property list is used extensively in emacs.

The 2 major use of property list are:

• Symbol Property List. Each symbol, has a attached property list. Used primarily to store info related to the symbol, such as compiler info, but can be anything.
• Text Properties. Any part of text in a buffer often have a property list, used to store syntax color info, special keyboard shortcut, etc.

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)

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 Item, 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.

Reference

• Property Lists (ELISP Manual)