The assoc-utils Reference Manual

This is the assoc-utils Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 15 04:18:58 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 assoc-utils

Utilities for manipulating association lists

Author

Eitaro Fukamachi

License

Public Domain

Long Description

# Assoc-Utils

[![Build Status](https://travis-ci.org/fukamachi/assoc-utils.svg?branch=master)](https://travis-ci.org/fukamachi/assoc-utils) [![Coverage Status](https://coveralls.io/repos/fukamachi/assoc-utils/badge.svg?branch=master)](https://coveralls.io/r/fukamachi/assoc-utils) [![Quicklisp dist](http://quickdocs.org/badge/assoc-utils.svg)](http://quickdocs.org/assoc-utils/)

Utilities for manipulating association lists.

## Usage

### aget

“‘common-lisp
(defvar *person*
’(("name" . "Eitaro") ("email" . "e.arrows@gmail.com")))

(aget *person* "name")
;=> "Eitaro"

(aget *person* "address")
;=> NIL

(aget *person* "address" "Tokyo, Japan")
;=> "Tokyo, Japan"

(setf (aget *person* "name") "Eitaro Fukamachi")

*person*
;=> (("name" . "Eitaro Fukamachi") ("email" . "e.arrows@gmail.com"))
“‘

### alist-get

“‘common-lisp
(defvar *data*
’((:VERSION . "0.6")
(:GENERATOR . "openstreetmap-cgimap 2.0.1 (1992 spike-08.openstreetmap.org)")
(:COPYRIGHT . "OpenStreetMap and contributors")
(:ATTRIBUTION . "http://www.openstreetmap.org/copyright")
(:LICENSE . "http://opendatacommons.org/licenses/odbl/1-0/")
(:ELEMENTS
((:TYPE . "node") (:ID . 1) (:LAT . 42.79572) (:LON . 13.569003)
(:TIMESTAMP . "2024-09-13T11:52:01Z") (:VERSION . 39)
(:CHANGESET . 156568263) (:USER . "SomeoneElse_Revert") (:UID . 1778799)
(:TAGS (:|COMMUNICATION:MICROWAVE| . "yes") (:|COMMUNICATION:RADIO| . "fm")
(:DESCRIPTION . "Radio Subasio") (:FREQUENCY . "105.5 MHz")
(:MAN–MADE . "mast") (:NAME . "Monte Piselli - San Giacomo")
(:NOTE . "This is the very first node on OpenStreetMap.")
(:|TOWER:CONSTRUCTION| . "lattice") (:|TOWER:TYPE| . "communication"))))))

(alist-get *data* ’(:elements 0 :tags :note))
;=> "This is the very first node on OpenStreetMap."
“‘

### with-keys

The macro ‘with-keys‘ is the alist equivalent of [‘with-slots‘](https://novaspec.org/cl/f_with-slots).

“‘common-lisp
(with-keys
("name" (loc "location") (time "time" 2024))
(list (cons "name" "eitaro") (cons "location" "vienna"))
(declare (string name))
(setf loc (string-upcase loc))
(format nil "Hi, ~a in ~a around ~a!" name loc time))
;; => "Hi, eitaro in VIENNA around 2024!"
“‘

The first parameter is a list of keys that ‘with-keys‘ will reference in the alist
provided in the second parameter. ‘With-keys‘ will attempt to convert each
key into a symbol, binding the alist value to it during body execution.

If you don’t want ‘with-keys‘ to guess the symbol for a key, supply a list -
‘(symbol key)‘ - in place of the key, as in ‘(loc "location")‘ above.
If the key is a number, you have to supply a symbol name since common lisp
symbols can not consist of only numbers.

If you want to supply a default value, you have to supply a list -
‘(symbol key default)‘ - in place of the key, as in ‘(time "time" 2024)‘.

Code and documentation adapted from [cl-hash-util](https://github.com/orthecreedence/cl-hash-util).

### remove-from-alist & delete-from-alist

“‘common-lisp
(defvar *person*
’(("name" . "Eitaro") ("email" . "e.arrows@gmail.com")))

(remove-from-alist *person* "name")
;=> (("email" . "e.arrows@gmail.com"))

;; Destructive version
(delete-from-alist *person* "name")
;=> (("email" . "e.arrows@gmail.com"))
“‘

### alist-plist & plist-alist

“‘common-lisp
(defvar *person*
’(("name" . "Eitaro") ("email" . "e.arrows@gmail.com")))

(alist-plist *person*)
;=> (:NAME "Eitaro" :EMAIL "e.arrows@gmail.com")

(plist-alist ’(:name "Eitaro" :email "e.arrows@gmail.com"))
;=> (("name" . "Eitaro") ("email" . "e.arrows@gmail.com"))
“‘

### alist-hash & hash-alist

“‘common-lisp
(defvar *person*
’(("name" . "Eitaro") ("email" . "e.arrows@gmail.com")))

(alist-hash *person*)
;=> #<HASH-TABLE :TEST EQUAL :COUNT 2 {1004329443}>

(hash-alist *)
;=> (("name" . "Eitaro") ("email" . "e.arrows@gmail.com"))
“‘

### alist-keys & alist-values

“‘common-lisp
(defvar *person*
’(("name" . "Eitaro") ("email" . "e.arrows@gmail.com")))

(alist-keys *person*)
;=> ("name" "email")

(alist-values *person*)
;=> ("Eitaro" "e.arrows@gmail.com")
“‘

### alistp

“‘common-lisp
(alistp ’(("name" . "Eitaro") ("email" . "e.arrows@gmail.com")))
;=> T

(alistp 1)
;=> NIL

(alistp nil)
;=> T

;; Type: alist is also available
(typep ’(("name" . "Eitaro") ("email" . "e.arrows@gmail.com")) ’alist)
;=> T
“‘

### alist=

“‘common-lisp
(alist= ’(("name" . "Eitaro") ("email" . "e.arrows@gmail.com"))
’(("email" . "e.arrows@gmail.com") ("name" . "Eitaro")))
;=> T
“‘

## Installation

“‘common-lisp
(ql:quickload :assoc-utils)
“‘

## Author

* Eitaro Fukamachi (e.arrows@gmail.com)

## License

Assoc-Utils is free and unencumbered software released into the public domain.

Version

0.1

Source

assoc-utils.asd.

Child Component

src (module).


3 Modules

Modules are listed depth-first from the system components tree.


3.1 assoc-utils/src

Source

assoc-utils.asd.

Parent Component

assoc-utils (system).

Child Component

assoc-utils.lisp (file).


4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


4.1 Lisp


4.1.1 assoc-utils/assoc-utils.asd

Source

assoc-utils.asd.

Parent Component

assoc-utils (system).

ASDF Systems

assoc-utils.

Packages

assoc-utils-asd.


4.1.2 assoc-utils/src/assoc-utils.lisp

Source

assoc-utils.asd.

Parent Component

src (module).

Packages

assoc-utils.

Public Interface
Internals

5 Packages

Packages are listed by definition order.


5.1 assoc-utils

Source

assoc-utils.lisp.

Use List

common-lisp.

Public Interface
Internals

5.2 assoc-utils-asd

Source

assoc-utils.asd.

Use List
  • asdf/interface.
  • common-lisp.

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


6.1 Public Interface


6.1.1 Special variables

Special Variable: *assoc-test*
Package

assoc-utils.

Source

assoc-utils.lisp.


6.1.2 Macros

Macro: delete-from-alist (place &rest keys)
Package

assoc-utils.

Source

assoc-utils.lisp.

Macro: delete-from-alistf (place &rest keys)
Package

assoc-utils.

Source

assoc-utils.lisp.

Macro: remove-from-alistf (place &rest keys)
Package

assoc-utils.

Source

assoc-utils.lisp.

Macro: with-keys (keys alist &body body)

The macro ‘with-keys‘ is the alist equivalent of ‘with-slots‘.

(with-keys
("name" (loc "location") (time "time" 2024))
(list (cons "name" "eitaro") (cons "location" "vienna"))
(declare (string name))
(setf loc (string-upcase loc))
(format nil "Hi, ~a in ~a around ~a!" name loc time))
;; => "Hi, eitaro in VIENNA around 2024!"

The first parameter is a list of keys that ‘with-keys‘ will reference in the alist provided in the second parameter. ‘With-keys‘ will attempt to convert each
key into a symbol, binding the alist value to it during body execution.

If you don’t want ‘with-keys‘ to guess the symbol for a key, supply a list - ‘(symbol key)‘ - in place of the key, as in ‘(loc "location")‘ above.
If the key is a number, you have to supply a symbol name since common lisp symbols can not consist of only numbers.

If you want to supply a default value, you have to supply a list -
‘(symbol key default)‘ - in place of the key, as in ‘(time "time" 2024)‘.
q
Code and documentation adapted from cl-hash-util.

Package

assoc-utils.

Source

assoc-utils.lisp.


6.1.3 Ordinary functions

Function: aget (alist key &optional default)
Setf Expander: (setf aget) (alist key &optional default)
Package

assoc-utils.

Source

assoc-utils.lisp.

Function: alist-get (alist keys)
Package

assoc-utils.

Source

assoc-utils.lisp.

Function: alist-hash (alist &key recursivep)
Package

assoc-utils.

Source

assoc-utils.lisp.

Function: alist-keys (alist)
Package

assoc-utils.

Source

assoc-utils.lisp.

Function: alist-plist (alist)
Package

assoc-utils.

Source

assoc-utils.lisp.

Function: alist-values (alist)
Package

assoc-utils.

Source

assoc-utils.lisp.

Function: alist= (alist1 alist2)
Package

assoc-utils.

Source

assoc-utils.lisp.

Function: alistp (value)
Package

assoc-utils.

Source

assoc-utils.lisp.

Function: hash-alist (hash &key recursivep)
Package

assoc-utils.

Source

assoc-utils.lisp.

Function: plist-alist (plist)
Package

assoc-utils.

Source

assoc-utils.lisp.

Function: remove-from-alist (alist &rest keys)
Package

assoc-utils.

Source

assoc-utils.lisp.


6.1.4 Types

Type: alist ()
Package

assoc-utils.

Source

assoc-utils.lisp.


6.2 Internals


6.2.1 Ordinary functions

Function: %aput (alist key value)
Package

assoc-utils.

Source

assoc-utils.lisp.

Function: aget* (seq key &optional default)
Package

assoc-utils.

Source

assoc-utils.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   %   (  
A   D   F   H   M   P   R   S   W  
Index Entry  Section

%
%aput: Private ordinary functions

(
(setf aget): Public ordinary functions

A
aget: Public ordinary functions
aget*: Private ordinary functions
alist-get: Public ordinary functions
alist-hash: Public ordinary functions
alist-keys: Public ordinary functions
alist-plist: Public ordinary functions
alist-values: Public ordinary functions
alist=: Public ordinary functions
alistp: Public ordinary functions

D
delete-from-alist: Public macros
delete-from-alistf: Public macros

F
Function, %aput: Private ordinary functions
Function, aget: Public ordinary functions
Function, aget*: Private ordinary functions
Function, alist-get: Public ordinary functions
Function, alist-hash: Public ordinary functions
Function, alist-keys: Public ordinary functions
Function, alist-plist: Public ordinary functions
Function, alist-values: Public ordinary functions
Function, alist=: Public ordinary functions
Function, alistp: Public ordinary functions
Function, hash-alist: Public ordinary functions
Function, plist-alist: Public ordinary functions
Function, remove-from-alist: Public ordinary functions

H
hash-alist: Public ordinary functions

M
Macro, delete-from-alist: Public macros
Macro, delete-from-alistf: Public macros
Macro, remove-from-alistf: Public macros
Macro, with-keys: Public macros

P
plist-alist: Public ordinary functions

R
remove-from-alist: Public ordinary functions
remove-from-alistf: Public macros

S
Setf Expander, (setf aget): Public ordinary functions

W
with-keys: Public macros


A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*assoc-test*: Public special variables

S
Special Variable, *assoc-test*: Public special variables