The cl-hash-util Reference Manual

This is the cl-hash-util Reference Manual, version 0.1.7, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 15:19:16 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 cl-hash-util

A simple and natural wrapper around Common Lisp’s hash functionality.

Author

Andrew Danger Lyon <>

License

MIT

Version

0.1.7

Source

cl-hash-util.asd.

Child Components

3 Files

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


3.1 Lisp


3.1.1 cl-hash-util/cl-hash-util.asd

Source

cl-hash-util.asd.

Parent Component

cl-hash-util (system).

ASDF Systems

cl-hash-util.


3.1.2 cl-hash-util/hash-util.lisp

Source

cl-hash-util.asd.

Parent Component

cl-hash-util (system).

Packages

cl-hash-util.

Public Interface
Internals

3.1.3 cl-hash-util/more-hash-util.lisp

Dependency

hash-util.lisp (file).

Source

cl-hash-util.asd.

Parent Component

cl-hash-util (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 cl-hash-util

Source

hash-util.lisp.

Nickname

hu

Use List
  • common-lisp.
  • common-lisp-user.
Public Interface
Internals

5 Definitions

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


5.1 Public Interface


5.1.1 Special variables

Special Variable: *error-on-nil*

If hget encounters a nil, error out.

Package

cl-hash-util.

Source

hash-util.lisp.


5.1.2 Macros

Macro: collecting-hash-table ((&key test existing mode) &body body)

A collection macro that builds and outputs a hash table. To add to the hash table, call the collect function with a key and a value from within the scope of the collecting-hash-table macro. The value will be inserted or combined with existing values according to the specified mode.

This code collects words into bins based on their length:

“‘common-lisp
(collecting-hash-table (:mode :append)
(dotimes (i 10)
(let ((word (format nil "~r" i)))
(collect (length word) word)))
“‘
Result: <hash table: 5 => ("three" "seven" "eight")
3 => ("one" "two" "six")
4 => ("zero" "four" "five" "nine")>

The mode can be set in the parameters section of collecting-hash-table with the :mode keyword. The :mode keyword can also be passed to individual collect calls.

Keyword parameters:

:test - Test function parameter passed to make-hash-table when creating a new hash table

:existing - Pass an existing hash table to the macro for modification. Using this option at the same time as :test will result in an error.

:mode - Set the default mode for the collect function. Modes are :replace :keep :tally :sum :append :push :concatenate or a function that will be applied in a reduce-like fashion to the existing and new values of a key.

Package

cl-hash-util.

Source

more-hash-util.lisp.

Macro: hash (&rest pairs)

Extends hash-create syntax to make it nicer.

Package

cl-hash-util.

Source

hash-util.lisp.

Macro: with-keys (keys hash-table &body body)

With-keys is the hash table equivalent of with-slots.

(with-keys
("name" (loc "location"))
(hash ("name" "andrew") ("location" "santa cruz"))
(setf loc (string-upcase loc))
(format nil "Hi, ~a in ~a!" name loc))
"Hi, andrew in SANTA CRUZ!"

The first parameter is a list of keys that with-keys will reference in the hash table provided in the second parameter. With-keys will attempt to convert each key into a symbol, binding the hash table value to it during body execution. String keys are upcased before conversion to symbols.

If you don’t want with-keys to guess at a symbol for a key, supply a list - (<symbol> <key>) - in place of the key, as in (loc "location") above.

Package

cl-hash-util.

Source

more-hash-util.lisp.


5.1.3 Ordinary functions

Function: alist->hash (al &key mode existing)

Converts an alist to a hash table.

The :existing keyword can be used to supply a hash table to which the contents of the alist will be added. Otherwise, a new hash table is created.

Since alists can contain multiple entries for a given key, alist->hash has a variety of accumulation modes to handle them. The accumulation mode can be set with the :mode keyword. Available modes are :replace :keep :tally :sum :append and :push. :replace is the default.

If a function is supplied instead of a recognized mode, then values will be accumulated to each key as by a reduce of the function.

Package

cl-hash-util.

Source

more-hash-util.lisp.

Function: alist->plist (alist)

Converts an alist to a plist

Package

cl-hash-util.

Source

more-hash-util.lisp.

Function: hash->alist (hsh)

Converts a hash table to an alist

Package

cl-hash-util.

Source

more-hash-util.lisp.

Function: hash->plist (hsh)

Converts a hash table to a plist

Package

cl-hash-util.

Source

more-hash-util.lisp.

Function: hash-copy (hash &key test size rehash-size rehash-threshold)

Performs a shallow (non-recursive) copy of a hash table.

Package

cl-hash-util.

Source

hash-util.lisp.

Function: hash-create (pairs &key test)

Create a hash table with limited syntax:

(hash ‘(("name" "andrew") ("city" "santa cruz")))

which would otherwise be:

(let ((hash (make-hash-table :test #’equal))) (setf (gethash "name" hash) "andrew")
(setf (gethash "city" hash) "santa cruz") hash)

yuck city.

Package

cl-hash-util.

Source

hash-util.lisp.

Function: hash-get (obj path &key fill-func)

Allows you to specify a path to get values out of a hash/list object. For instance, if you did:

(let ((myhash (hash ’("lol" ’(3 4 5)))))
(hget myhash ’("lol" 1)))

which would return 4 (1st index of list stored under key ’lol of the hash table). Simplifies traversing responses from decoded JSON objects by about a trillion times.

The second and third values returned by hget indicate how much success it had in looking up your request. If the second value is T, everything was found, right up to the end node. When the second value is NIL, the third value is the portion of the supplied path that was missing.

By setting *error-on-nil* to true, hget can be persuaded to throw an error if any of the upper part of the tree is missing . It will not throw an error if the final value is not set.

Package

cl-hash-util.

Alias for

hget.

Function: (setf hash-get) (obj path &key fill-func)

Defines a setf for the hget function. Uses hget to get all but the
last item in the path, then setfs that last object (either a gethash or an elt).

If any of the path aside from the last item is missing, it will throw an error. To change this behavior, supply an object construction function with the :fill-func parameter. (Setf hget) will fill out the tree up to the last path item with the objects that this function returns.

Package

cl-hash-util.

Alias for

(setf hget).

Function: hash-keys (hash)

Grab all the hash keys of the passed hash into a list.

Package

cl-hash-util.

Source

hash-util.lisp.

Function: hget (obj path &key fill-func)

Allows you to specify a path to get values out of a hash/list object. For instance, if you did:

(let ((myhash (hash ’("lol" ’(3 4 5)))))
(hget myhash ’("lol" 1)))

which would return 4 (1st index of list stored under key ’lol of the hash table). Simplifies traversing responses from decoded JSON objects by about a trillion times.

The second and third values returned by hget indicate how much success it had in looking up your request. If the second value is T, everything was found, right up to the end node. When the second value is NIL, the third value is the portion of the supplied path that was missing.

By setting *error-on-nil* to true, hget can be persuaded to throw an error if any of the upper part of the tree is missing . It will not throw an error if the final value is not set.

Package

cl-hash-util.

Source

hash-util.lisp.

Function: (setf hget) (obj path &key fill-func)

Defines a setf for the hget function. Uses hget to get all but the
last item in the path, then setfs that last object (either a gethash or an elt).

If any of the path aside from the last item is missing, it will throw an error. To change this behavior, supply an object construction function with the :fill-func parameter. (Setf hget) will fill out the tree up to the last path item with the objects that this function returns.

Package

cl-hash-util.

Source

hash-util.lisp.

Function: plist->alist (plist)

Converts a plist to an alist

Package

cl-hash-util.

Source

more-hash-util.lisp.

Function: plist->hash (plist &key mode existing)

Converts a plist to a hash table.

The :existing keyword can be used to supply a hash table to which the contents of the plist will be added. Otherwise, a new hash table is created.

Since plists can contain multiple entries for a given key, plist->hash has a variety of accumulation modes to handle them. The accumulation mode can be set with the :mode keyword. Available modes are :replace :keep :tally :sum :append and :push. :replace is the default.

If a function is supplied instead of a recognized mode, then values will be accumulated to each key as by a reduce of the function.

Package

cl-hash-util.

Source

more-hash-util.lisp.


5.2 Internals


5.2.1 Ordinary functions

Function: %find-lowest-store (obj path)
Package

cl-hash-util.

Source

hash-util.lisp.

Function: %hash-collecting-modes (mode)
Package

cl-hash-util.

Source

more-hash-util.lisp.

Function: %hget-access (obj key)
Package

cl-hash-util.

Source

hash-util.lisp.

Function: %hget-set (store key value)
Package

cl-hash-util.

Source

hash-util.lisp.

Function: %store-p (obj key)

Is the object something from which key could be fetched?

Package

cl-hash-util.

Source

hash-util.lisp.

Function: mkstr (&rest args)
Package

cl-hash-util.

Source

more-hash-util.lisp.

Function: symbolize (entity &key package)
Package

cl-hash-util.

Source

more-hash-util.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

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

%
%find-lowest-store: Private ordinary functions
%hash-collecting-modes: Private ordinary functions
%hget-access: Private ordinary functions
%hget-set: Private ordinary functions
%store-p: Private ordinary functions

(
(setf hash-get): Public ordinary functions
(setf hget): Public ordinary functions

A
alist->hash: Public ordinary functions
alist->plist: Public ordinary functions

C
collecting-hash-table: Public macros

F
Function, %find-lowest-store: Private ordinary functions
Function, %hash-collecting-modes: Private ordinary functions
Function, %hget-access: Private ordinary functions
Function, %hget-set: Private ordinary functions
Function, %store-p: Private ordinary functions
Function, (setf hash-get): Public ordinary functions
Function, (setf hget): Public ordinary functions
Function, alist->hash: Public ordinary functions
Function, alist->plist: Public ordinary functions
Function, hash->alist: Public ordinary functions
Function, hash->plist: Public ordinary functions
Function, hash-copy: Public ordinary functions
Function, hash-create: Public ordinary functions
Function, hash-get: Public ordinary functions
Function, hash-keys: Public ordinary functions
Function, hget: Public ordinary functions
Function, mkstr: Private ordinary functions
Function, plist->alist: Public ordinary functions
Function, plist->hash: Public ordinary functions
Function, symbolize: Private ordinary functions

H
hash: Public macros
hash->alist: Public ordinary functions
hash->plist: Public ordinary functions
hash-copy: Public ordinary functions
hash-create: Public ordinary functions
hash-get: Public ordinary functions
hash-keys: Public ordinary functions
hget: Public ordinary functions

M
Macro, collecting-hash-table: Public macros
Macro, hash: Public macros
Macro, with-keys: Public macros
mkstr: Private ordinary functions

P
plist->alist: Public ordinary functions
plist->hash: Public ordinary functions

S
symbolize: Private ordinary functions

W
with-keys: Public macros


A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*error-on-nil*: Public special variables

S
Special Variable, *error-on-nil*: Public special variables