Elisp: 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 )

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.

(info "(elisp) Property Lists")

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. [see Elisp: Association List]

Get a Key's Value

(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.
lax-plist-get
similar to plist-get, but compare key using equal.
(plist-get '(x 1 y 2) 'y) ; 2
(plist-get '(x 1 y 2) 'b) ; nil

Add/Modify item

(plist-put PLIST PROP VAL)
add or change the value of key PROP in PLIST to VAL. The new plist is returned. Use (setq x (plist-put x prop val)) to be sure to use the new value. Existence of key is checked with eq.
lax-plist-put
similar to plist-put, but compare key using equal.
;; create a property list xx
(setq xx '(a 1 b 2))

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

xx
;; (a 1 b 3)

Check Key Existence

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

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

(info "(elisp) Plist Access")

Symbol's Property List

Each elisp symbol, can be attached a property list. Such is called “symbol plist”.

Elisp: Symbol Property List

Text Properties

Text in a buffer region can be attached a property list. Such is called “Text Properties”.

Elisp: Text Properties

If you have a question, put $5 at patreon and message me on xah discord.
Or support me by Buy Xah Emacs Tutorial

Emacs Tutorial

Emacs Init

Emacs Keys

ELisp

ELisp Examples

ELisp Write Major Mode


ELisp

Basics

Basic Functions

Writing Command

Writing Script

Lisp Data Structure

Lisp Symbol

Elisp Misc