Elisp: Property List
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:
- 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 .
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 usingequal
.
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 usingequal
.
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 valuenil
. - 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)