Elisp: Property List

By Xah Lee. Date: 2016-09-15. Last updated: 2024-05-20.

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 :

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:

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

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

plist-get

(plist-get PLIST PROP)

(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.

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.

plist-member

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)