The cl-hash-util Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-hash-util Reference Manual

This is the cl-hash-util Reference Manual, version 0.1.7, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:10:27 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

cl-hash-util

cl-hash-util is a very basic library for dealing with CL's hash tables. The idea was spawned through working with enough JSON APIs and config files, causing a lot of headaches in the process. For instance, to get a value deep within a hash, you have to do:

(gethash "city" (gethash "location" (gethash "user" obj)))

I find the inside-out approach unintuitive, regardless of how many lisp nerds are going to yell at me about how it's correct.

With cl-hash-util, you can write:

(hash-get obj '("user" "location" "city"))

hash-get can also deal with getting elements out of lists and arrays:

(hash-get obj '("user" "friends" 0 "name"))

which normally would have to be written as such:

(gethash "name" (elt (gethash "friends" (gethash "user" obj)) 0))

...uuuugly.

cl-hash-util also provides an easy way to build hash tables on the fly. Where you'd normally have to do something like:

(let ((myhash (make-hash-table :test #'equal)))
  (setf (gethash "name" myhash) "andrew")
  (setf (gethash "location" myhash) "santa cruz")
  myhash)

You can now do:

;; functional version
(hash-create '(("name" "andrew") ("location" "santa cruz")))

;; convenience macro `hash`
(hash ("name" "andrew") ("location" "santa cruz"))

You can also do nested hashes:

(hash ("name" "andrew")
      ("location" (hash ("city" "santa cruz")
                        ("state" "CA"))))

This saves a lot of typing =].

With-keys

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

(defvar ht (hash ("name" "andrew") ("location" "santa cruz")))
(with-keys
   ("name" (loc "location"))
    ht
    (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. With-keys will reference the keys in the hash table provided as the second parameter. With-keys will attempt to convert each key into a symbol in the current package, 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, supply a list - (symbol key) - in place of the key, as in (loc "location") above.

Collecting-hash-table

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 accumulation mode.

This code collects words into bins based on their length:

(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

:replace - Acts the same as (setf (gethash key ht) value), replacing any existing value with the new one.

:keep - Only inserts the value if the key did not previously exist.

:tally - Ignores the input value, instead adding 1 to the key value.

:sum - Adds the input value to the key value. Input should be numeric.

:append - Appends the value to the list that is presumed to be under the key. If the key doesn't yet exist, places the value in a new list.

:push - Like append, but sticks things on the other end.

:concatenate - Assumes that both new and existing values are lists, storing the concatenation of them under the key.

Obviously, not all modes are compatible with each other. Collecting-hash-table makes no attempt to save you from intermingling them.

Custom modes may be created by supplying a function instead of a mode descriptor. This function will be applied in a reduce-like fashion: when a value already exists under a key, the existing value and the new value will be passed to the supplied function. Its return value will be stored under the key.

If more flexibility is needed, then a list of two functions can be supplied. The first function should accept two parameters: first, the existing value; second the new value. It will be called when a key already exists. The second function should take one parameter. It is called when a key does not exist yet. In both cases the key value is set to the function return value.

Conversion functions

Included is a suite of functions for converting between hash tables, alists and plists: alist->plist, plist->alist, alist->hash, plist->hash, hash->alist, and hash->plist.

The alist->hash and plist->hash take the same :existing and :mode keywords that collecting-hash-table takes.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 cl-hash-util

Author

Andrew Danger Lyon <orthecreedence@gmail.com>

License

MIT

Description

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

Version

0.1.7

Source

cl-hash-util.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 cl-hash-util.asd

Location

cl-hash-util.asd

Systems

cl-hash-util (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

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

Parent

cl-hash-util (system)

Location

hash-util.lisp

Packages

cl-hash-util

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

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

Dependency

hash-util.lisp (file)

Parent

cl-hash-util (system)

Location

more-hash-util.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 cl-hash-util

Source

hash-util.lisp (file)

Nickname

hu

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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

Macro: hash &rest PAIRS

Extends hash-create syntax to make it nicer.

Package

cl-hash-util

Source

hash-util.lisp (file)

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


Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 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 (file)

Function: alist->plist ALIST

Converts an alist to a plist

Package

cl-hash-util

Source

more-hash-util.lisp (file)

Function: hash->alist HSH

Converts a hash table to an alist

Package

cl-hash-util

Source

more-hash-util.lisp (file)

Function: hash->plist HSH

Converts a hash table to a plist

Package

cl-hash-util

Source

more-hash-util.lisp (file)

Function: hash-copy HASH &key TEST

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

Package

cl-hash-util

Source

hash-util.lisp (file)

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

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

Source

hash-util.lisp (file)

Writer

(setf hash-get) (function)

Function: (setf hash-get) VAL 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 (file)

Reader

hash-get (function)

Function: hash-keys HASH

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

Package

cl-hash-util

Source

hash-util.lisp (file)

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

Writer

(setf hget) (function)

Function: (setf hget) VAL 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 (file)

Reader

hget (function)

Function: plist->alist PLIST

Converts a plist to an alist

Package

cl-hash-util

Source

more-hash-util.lisp (file)

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


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Functions

Function: %find-lowest-store OBJ PATH
Package

cl-hash-util

Source

hash-util.lisp (file)

Function: %hash-collecting-modes MODE
Package

cl-hash-util

Source

more-hash-util.lisp (file)

Function: %hget-access OBJ KEY
Package

cl-hash-util

Source

hash-util.lisp (file)

Function: %hget-set STORE KEY VALUE
Package

cl-hash-util

Source

hash-util.lisp (file)

Function: %store-p OBJ KEY

Is the object something from which key could be fetched?

Package

cl-hash-util

Source

hash-util.lisp (file)

Function: mkstr &rest ARGS
Package

cl-hash-util

Source

more-hash-util.lisp (file)

Function: symbolize ENTITY &key PACKAGE
Package

cl-hash-util

Source

more-hash-util.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-hash-util.asd: The cl-hash-util<dot>asd file
cl-hash-util/hash-util.lisp: The cl-hash-util/hash-util<dot>lisp file
cl-hash-util/more-hash-util.lisp: The cl-hash-util/more-hash-util<dot>lisp file

F
File, Lisp, cl-hash-util.asd: The cl-hash-util<dot>asd file
File, Lisp, cl-hash-util/hash-util.lisp: The cl-hash-util/hash-util<dot>lisp file
File, Lisp, cl-hash-util/more-hash-util.lisp: The cl-hash-util/more-hash-util<dot>lisp file

L
Lisp File, cl-hash-util.asd: The cl-hash-util<dot>asd file
Lisp File, cl-hash-util/hash-util.lisp: The cl-hash-util/hash-util<dot>lisp file
Lisp File, cl-hash-util/more-hash-util.lisp: The cl-hash-util/more-hash-util<dot>lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

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

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

(
(setf hash-get): Exported functions
(setf hget): Exported functions

A
alist->hash: Exported functions
alist->plist: Exported functions

C
collecting-hash-table: Exported macros

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

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

M
Macro, collecting-hash-table: Exported macros
Macro, hash: Exported macros
Macro, with-keys: Exported macros
mkstr: Internal functions

P
plist->alist: Exported functions
plist->hash: Exported functions

S
symbolize: Internal functions

W
with-keys: Exported macros

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

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

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

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

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
cl-hash-util: The cl-hash-util system
cl-hash-util: The cl-hash-util package

P
Package, cl-hash-util: The cl-hash-util package

S
System, cl-hash-util: The cl-hash-util system

Jump to:   C   P   S