asoc.el provides a complete API for handling association lists (alists). In
addition to basic functions for creating, accessing and modifying alists, it
provides mapping, filtering and folding facilities in both regular and anaphoric
variants, a looping construct analogous to dolist (also with anaphoric
variant), and a special variable for configuring the equality predicate used by
asoc operations.
A note on builtin list functions
- asoc-make
(&optional keys default) - asoc-copy
(alist) - asoc-zip
(keys values) - asoc-uniq
(alist) - asoc-merge
(&rest alists) - asoc-sort-keys
(alist &optional comparator) - asoc-filter
(predicate alist) - asoc--filter
(form alist) - asoc-filter-keys
(predicate alist) - asoc-filter-values
(predicate alist) - asoc-remove
(predicate alist) - asoc-remove-keys
(predicate alist) - asoc-remove-values
(predicate alist) - asoc-partition
(flatlist)
- asoc-contains-key?
(alist key) - asoc-contains-pair?
(alist key value)
- asoc-get
(alist key &optional default) - asoc-put!
(alist key value &optional replace) - asoc-dissoc
(alist &rest keys) - asoc-pop!
(alist key) - asoc-find
(predicate alist) - asoc--find
(form alist) - asoc-find-key
(key alist) - asoc-keys
(alist) - asoc-values
(alist &optional ignore-shadowed) - asoc-unzip
(alist)
- asoc-map
(function alist) - asoc--map
(form alist) - asoc-map-keys
(func alist) - asoc-map-values
(func alist)
- asoc-fold
(func alist init) - asoc--fold
(form alist init) - asoc-merge-values
(&rest alists) - asoc-merge-values-no-dups
(&rest alists)
For some operations, no distinction need be made between alists and general
lists. asoc does not provide functions for such operations, since regular list
functions may be used. For instance, cons, car, cdr, push, pop,
append should be used for assembling and disassembling alists.
Where appropriate, the asoc API follows established conventions for naming,
argument order, etc. In particular, it follows the prefix conventions of
dash.el:
asoc-: prefix for regular functions, macros and variablesasoc--: prefix for anaphoric macrosasoc---: prefix for private functions, macros and variables
The following suffixes are used:
?or-p: marks a predicate function!: marks a function which may modify its alist argument
asoc also follows dash in using a special variable to set the predicate used
in equality tests. To control the predicate used for a given call,
asoc-compare-fn may be set within a dynamically-scoped let-block containing
the function call.
Special variable holding the equality predicate used in asoc functions.
May take the values equalp (or cl-equalp), equal, eql, eq. When unset,
functions default to using equal.
This variable may be passed to asoc functions dynamically in a let binding.
Return an alist with keys each initialized to value nil.
alias of copy-sequence.
Return a shallow copy of alist.
Return an alist associating keys with corresponding values. If keys is longer than values, the excess keys have value nil.
Return a copy of alist with duplicate keys removed.
The first occurrence of each key is retained.
(asoc-uniq `((a 1) (b 2) (b 3) (c 4) (a 5)))
;; ((a 1) (b 2) (c 4))
Return an alist with unique keys resulting from merging alists.
When identical keys occur in two alists, the latter alist takes precedence. When identical keys occur within a single alist, the foremost takes precedence (as usual).
With a single argument, equivalent to asoc-uniq.
Return a copy of alist sorted by keys.
The keys are sorted stably using comparator, or string< if none is
provided. Note that string< is only applicable to symbols and strings. For
other types of key, a comparator argument is mandatory.
(let ((a '((b . 2) (a . 1) (e . 5) (d . 4) (c . 3))))
(asoc-sort-keys a))
;; ((a . 1) (b . 2) (c . 3) (d . 4) (e . 5))
Return a copy of alist with key-value pairs failing predicate removed.
predicate should take two arguments, key and value.
;; filter for pairs where KEY > VALUE
(let ((fib `((1 . 1) (2 . 1) (3 . 2) (4 . 3) (5 . 5) (6 . 8) (7 . 13) (8 . 21))))
(asoc-filter #'> fib))
;; ((2 . 1) (3 . 2) (4 . 3))
Anaphoric variant of asoc-filter.
Return a list of those alist elements for which form evaluates t.
The included elements remain in their original order. The anaphoric variables
key and value are available for use in form.
;; remove nodes where the key is associated with itself
(asoc--filter (not (eq key value))
`((a . b) (b . c) (c . c) (d . a) (e . e)))
;; ((a . b) (b . c) (d . a))
Return a copy of alist with keys failing predicate removed.
;; filter for pairs where KEY <= 3
(let ((fib `((1 . 1) (2 . 1) (3 . 2) (4 . 3)
(5 . 5) (6 . 8) (7 . 13) (8 . 21))))
(asoc-filter-keys (lambda (k) (<= k 3)) fib))
;; ((1 . 1) (2 . 1) (3 . 2))
Return a copy of alist with pairs whose value fails predicate removed.
;; filter for pairs where VALUE <= 3
(let ((fib `((1 . 1) (2 . 1) (3 . 2) (4 . 3)
(5 . 5) (6 . 8) (7 . 13) (8 . 21))))
(asoc-filter-values (lambda (v) (<= v 3)) fib))
;; ((1 . 1) (2 . 1) (3 . 2) (4 . 3))
aliases: asoc-reject, asoc-reject-keys, asoc-reject-values
These are inverse versions of asoc-filter, asoc-filter-keys and asoc-filter-values.
They are equivalent to the corresponding functions with inverted predicates.
;; filter out pairs where KEY > VALUE
(let ((fib '((1 . 1) (2 . 1) (3 . 2) (4 . 3)
(5 . 5) (6 . 8) (7 . 13) (8 . 21))))
(asoc-remove #'> fib))
;; ((1 . 1) (5 . 5) (6 . 8) (7 . 13) (8 . 21))
;; filter out pairs where KEY <= 3
(let ((fib '((1 . 1) (2 . 1) (3 . 2) (4 . 3)
(5 . 5) (6 . 8) (7 . 13) (8 . 21))))
(asoc-remove-keys (lambda (k) (<= k 3)) fib))
;; ((4 . 3) (5 . 5) (6 . 8) (7 . 13) (8 . 21))
;; filter out pairs where VALUE <= 3
(let ((fib '((1 . 1) (2 . 1) (3 . 2) (4 . 3)
(5 . 5) (6 . 8) (7 . 13) (8 . 21))))
(asoc-remove-values (lambda (v) (<= v 3)) fib))
;; ((5 . 5) (6 . 8) (7 . 13) (8 . 21))
Return an alist whose keys and values are taken alternately from flatlist.
(asoc-partition `(a 1 b 2 c 3 d 4 e 5 f 6))
;; ((a . 1) (b . 2) (c . 3) (d . 4) (e . 5) (f . 6))
alias: asoc-contains-key-p
Return t if alist contains an item with key key, nil otherwise.
alias: asoc-contains-pair-p
Return t if alist contains an item (key.value), nil
otherwise.
Return the value associated with key in alist, or default if missing.
Associate key with value in alist.
When key already exists, if replace is non-nil, previous entries with
that key are removed. Otherwise, the pair is simply consed on the front of
the alist. In the latter case, this is equivalent to acons.
Return a modified list excluding all pairs with a key in keys
Return the first association containing key and remove it from alist.
Return the first alist association satisfying predicate.
predicate should take two arguments, key and value.
For all associations satisfying predicate, use asoc-filter.
Anaphoric variant of asoc-find.
Return the first alist association for which form evaluates t.
The anaphoric variables key and value are available for use in form.
For all associations satisfying form, use asoc--filter
Return the first association of alist with key, or nil if none match.
For all associations with key, use asoc-filter-keys.
Return a list of unique keys in alist.
For a list of all keys in order, with duplicates, use mapcar with car over
alist.
Return a list of unique values in alist.
If ignore-shadowed is non-nil, only show include associated with the first occurrence of each key.
For a list of all values in order, with duplicate values (and values of shadowed
keys), use mapcar with cdr over alist.
Return a list of all keys and a list of all values in alist.
Returns (keylist valuelist) where keylist and
valuelist contain all the keys and values in alist in order, including
repeats. The original alist can be reconstructed with
(asoc-zip KEYLIST VALUELIST).
asoc-unzip will also reverse asoc-zip as long as the original arguments of
asoc-zip were both lists and were of equal length.
Iterate through alist, executing body for each key-value pair.
For each iteration, keyvar is bound to the key and valuevar is bound to the value.
The return value is obtained by evaluating result.
(asoc-do ((k v) a)
(insert (format "%S %S\n" k v)))
;; print keys and values
(let ((sum 0))
(asoc-do ((key value) a sum)
(when (symbolp key)
(setf sum (+ sum value)))))
;; add values associated with all keys that are symbols.
Anaphoric variant of asoc-do.
Iterate through alist, executing body for each key-value pair. For each
iteration, the anaphoric variables key and value are bound to they current
key and value. The macro returns the value of the anaphoric variable result,
which is initially nil.
Optionally, initialization code can be included prior to the main body using
the syntax (:initially ...).
(let ((a '((one . 1) (two . 4) (3 . 9) (4 . 16) (five . 25) (6 . 36))))
(asoc--do a
(when (symbolp key)
(setf result (+ (or result 0) value)))))
;; 30
(let ((a '((one . 1) (two . 4) (3 . 9) (4 . 16) (five . 25) (6 . 36))))
(asoc--do a
(:initially (setf result 0))
(when (symbolp key)
(setf result (+ result value)))))
;; 30
Apply func to each element of alist and return the resulting list.
func should be a function of two arguments (key value).
;; map value to nil when key is not a symbol...
(asoc-map (lambda (k v) (cons k (when (symbolp k) v)))
`((one . 1) (two . 4) (3 . 9) (4 . 16) (five . 25) (6 . 36)))
;; ((one . 1) (two . 4) (3 . nil) (4 . nil) (five . 25) (6 . nil))
;; list of values for symbol keys (nil for other keys)
(asoc-map (lambda (k v) (when (symbolp k) v))
'((one . 1) (two . 4) (3 . 9) (4 . 16) (five . 25) (6 . 36)))
;; (1 4 nil nil 25 nil)
Anaphoric variant of asoc-map.
Evaluate form for each element of alist and return the resulting list.
The anaphoric variables key and value are available for use in form.
(asoc--map
(cons (intern (concat (symbol-name key) "-squared"))
(* value value))
`((one . 1) (two . 2) (three . 3) (four . 4)))
;; ((one-squared . 1) (two-squared . 4)
;; (three-squared . 9) (four-squared . 16))
(asoc--map (cons (intern key) value)
'(("one" . 1) ("two" . 2) ("three" . 3)))
((one . 1) (two . 2) (three . 3))
(asoc--map (format "%s=%d;" key value)
'((one . 1) (two . 2) (three . 3) (four . 4)))
("one=1;" "two=2;" "three=3;" "four=4;")
Return a modified copy of alist with keys transformed by func.
;; convert symbolic keys to strings
(asoc-map-keys #'symbol-name
'((one . 1) (two . 4) (three . 9) (four . 16)))
;; (("one" . 1) ("two" . 4) ("three" . 9) ("four" . 16))
Return a modified copy of alist with values transformed by func.
;; convert alist to nested list
(let ((a `((1 . 1) (2 . 4) (3 . 9) (4 . 16) (5 . 25))))
(asoc-map-values #'list a))
;; ((1 1) (2 4) (3 9) (4 16) (5 25))
Reduce alist using func on the values, starting with value init.
func should take a key, a value and the accumulated result and return an updated result.
;; list of keys with value of 0
(let ((a `((1 . 0) (2 . 0) (3 . 0) (4 . 1) (5 . 0)
(6 . 2) (7 . 7) (8 . 3) (9 . 2) (10 . 0))))
(asoc-fold (lambda (k v acc) (if (zerop v) (cons k acc) acc))
(reverse a) nil))
;; (1 2 3 5 10)
Anaphoric variant of asoc-fold.
Reduce alist using form on each value, starting from init.
The anaphoric variables key, value and acc represent the current
key, value and accumulated value, respectively.
The return value is the value of acc after the last element has
been processed.
;; list of keys with value of 0
(let ((a '((1 . 0) (2 . 0) (3 . 0) (4 . 1) (5 . 0)
(6 . 2) (7 . 7) (8 . 3) (9 . 2) (10 . 0))))
(asoc--fold (if (zerop value) (cons key acc) acc)
(reverse a) nil))
;; (1 2 3 5 10)
Return an alist merging multiple occurrences of each key in alists.
Each key is associated with a list containing all values in alists which were associated with the key, in order.
(let ( (a `((a . 1) (b . 2) (a . 3) (a . 1)))
(b '((a . 5) (b . 2) (c . 3))) )
(asoc-merge-values a b))
;; ((a 1 3 1 5) (b 2 2) (c 3))
;; ie. ((a . (1 3 1 5)) (b . (2 2)) (c . (3)))
Return an alist merging multiple unique values for each key in alists.
Each key is associated with a list containing all unique values in alists which were associated with the key, in order.
(let ( (a `((a . 1) (b . 2) (a . 3) (a . 1)))
(b '((a . 5) (b . 2) (c . 3))) )
(asoc-merge-values-no-dups a b))
;; ((a 1 3 5) (b 2) (c 3))
;; ie. ((a . (1 3 5)) (b . (2)) (c . (3)))
( (key1 value1) (key2 value2) ... )
An alternative format for describing a key-value mapping is a list whose
elements are 2-element (key value) sublists, rather than (key . value)
cons cells.
A list of this form is equivalent to an alist whose values are all wrapped in lists.
( (key1 . (value1)) (key2 . (value2)) ... )
Although this is pointless, such pseudo-alists are common, perhaps because the literals are more concise than those of true alists.
Such lists can be processed with alist functions if you remember to wrap and unwrap the value as needed. Alternatively, you can convert the list to an alist prior to processing:
(let (my-alist (asoc-map-values #'car my-duplelist))
.... )
When converting such a list, be careful to ensure that it strictly associates one key with one value. Sometimes an alist will legitimately have list values to allow a key to be associated with multiple values:
( (key1 value1) (key2 value2a value2b) ... )
;; or equivalently:
( (key1 . (value1)) (key2 . (value2a value2b)) ... )
This is a true alist whose values simply happen to be lists.
(key1 value 1 key2 value2 ...)
Another form of key-value list is a flat list with alternating keys and values.
When keys are distinct symbols, such a list is called a plist (property list). In Emacs Lisp, each symbol has an associated plist specifying its properties.
Such a list can be converted to an alist with asoc-partition
(let ((my-alist (asoc-partition my-flatlist)))
.... )
(... (key1 . value1a) ... (key1 . value1b) ...)
Normally, an alist may allow multiple associations with the same key, but only considers the first when accessing a value. This allows the value for a key to be non-destructively changed ("shadowed") by simply pushing an association onto the alist, and the change to be reversed by removing that association.
However, sometimes, a list may contain multiple key-value associations, all of which are relevant, ie. a key has multiple values.
Such a multi-valued alist is best converted into a list-valued alist using
asoc-merge-values.
As mentioned above, alists will sometimes have lists as values.
( (key1 value1) (key2 value2a value2b) ... )
... is the standard representation of:
( ( key1 . (value1) )
( key2 . (value2a value2b) )
...
Similarly, with an improper-list-valued alist:
( (key1 value1a . value1b) (key2 value2a value2b . value2c) ... )
... is the standard representation of:
( ( key1 . (value1a . value1b) )
( key2 . (value2a value2b . value2c))
...
A special case (or special interpretation) of improper-list-valued alists is a cons-valued alist.
For instance, consider an alist where values may be either individual atoms or cons cells:
( (key1 . value1) (key2 value2a . value2b) ... )
... is the standard representation of:
( ( key1 . value1 )
( key2 . (value2a . value2b) )
...
When a value is nil, the key-value pair is represented as a list containing
only the key:
( (key1 . value1) (key2) ... )
is the standard representation of:
( ( key1 . value1 )
( key2 . nil )
...
let-alistprovides a macro of the same name, which allows convenient access to alist values when the keys are symbols.mapprovides functions for alists, hash tables and arrays.kvprovides tools for plists, alists and hash tables.aprovides functions for alists and hash tables inspired by Clojure.