asoc.el -- Association List Library for Emacs Lisp.

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.

Table of Contents

API

A note on builtin list functions

Conventions

Variables

• asoc-compare-fn

Constructor and Filter 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)

Predicates

• asoc-contains-key? (alist key)
• asoc-contains-pair? (alist key value)

Access Functions

• 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)

Looping Constructs

• asoc-do (spec &rest body)
• asoc--do (alist &rest body)

Mapping Functions

• asoc-map (function alist)
• asoc--map (form alist)
• asoc-map-keys (func alist)
• asoc-map-values (func alist)

Folds

• asoc-fold (func alist init)
• asoc--fold (form alist init)
• asoc-merge-values (&rest alists)
• asoc-merge-values-no-dups (&rest alists)

Notes

Handling Alist Variants

• List of duples
• Flat key-value list / Property list
• Multi-valued alist

Representation of Alists

• List-valued alists
• Cons-valued alist
• Null values

Other Packages

---

API

A note on builtin list functions

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.

---

Conventions

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 variables
• asoc--: prefix for anaphoric macros
• asoc---: 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.

---

Variables

asoc-compare-fn nil

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.

---

Constructor and Filter Functions

asoc-make (&optional keys default)

Return an alist with keys each initialized to value nil.

asoc-copy (alist)

alias of copy-sequence.

Return a shallow copy of alist.

asoc-zip (keys values)

Return an alist associating keys with corresponding values. If keys is longer than values, the excess keys have value nil.

asoc-uniq (alist)

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

asoc-merge (&rest alists)

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.

asoc-sort-keys (alist &optional comparator)

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

asoc-filter (predicate alist)

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

asoc--filter (form alist)

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

asoc-filter-keys (predicate alist)

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

asoc-filter-values (predicate alist)

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

asoc-remove (predicate alist)

asoc-remove-keys (predicate alist)

asoc-remove-values (predicate alist)

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

asoc-partition (flatlist)

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

---

Predicates

asoc-contains-key? (alist key)

alias: asoc-contains-key-p

Return t if __alist