Emacs Lisp: Property List

By Xah Lee. Date: . Last updated: .

What is Property List

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

'(key1 val1 key2 val2 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.

Use of Property List

Property List is used as a simplest form of key/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 100 items, you probably should use Association List instead.

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 Emacs Lisp: Test Equality]
(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 is not changed. Use setq if you need to change it.
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. [see Emacs Lisp: Test Equality]

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 Emacs Lisp: Cons Pair]
(setq xx '(a 1 b 2))

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

Reference

(info "(elisp) Property Lists")

Lisp Data Structure

ErgoEmacs mascot-s276x226
Buy Xah Emacs Tutorial

Lisp Basics

Basics

Lisp Data Structure

Function

Lisp Symbol

Lisp Misc

Working with Elisp