Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the cl-hash-util Reference Manual, version 0.1.7, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 14:53:10 2021 GMT+0.
| • Introduction | What cl-hash-util is all about | |
| • Systems | The systems documentation | |
| • Files | The files documentation | |
| • Packages | The packages documentation | |
| • Definitions | The symbols documentation | |
| • Indexes | Concepts, functions, variables and data types |
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 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.
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.
: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.
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: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The cl-hash-util system |
Andrew Danger Lyon <orthecreedence@gmail.com>
MIT
A simple and natural wrapper around Common Lisp’s hash functionality.
0.1.7
cl-hash-util.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files |
| • The cl-hash-util.asd file | ||
| • The cl-hash-util/hash-util.lisp file | ||
| • The cl-hash-util/more-hash-util.lisp file |
Next: The cl-hash-util/hash-util․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
cl-hash-util.asd
cl-hash-util (system)
Next: The cl-hash-util/more-hash-util․lisp file, Previous: The cl-hash-util․asd file, Up: Lisp files [Contents][Index]
cl-hash-util (system)
hash-util.lisp
Previous: The cl-hash-util/hash-util․lisp file, Up: Lisp files [Contents][Index]
hash-util.lisp (file)
cl-hash-util (system)
more-hash-util.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The cl-hash-util package |
hash-util.lisp (file)
hu
Definitions are sorted by export status, category, package, and then by lexicographic order.
| • Exported definitions | ||
| • Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
| • Exported special variables | ||
| • Exported macros | ||
| • Exported functions |
Next: Exported macros, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
If hget encounters a nil, error out.
hash-util.lisp (file)
Next: Exported functions, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
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.
more-hash-util.lisp (file)
Extends hash-create syntax to make it nicer.
hash-util.lisp (file)
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.
more-hash-util.lisp (file)
Previous: Exported macros, Up: Exported definitions [Contents][Index]
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.
more-hash-util.lisp (file)
Converts an alist to a plist
more-hash-util.lisp (file)
Converts a hash table to an alist
more-hash-util.lisp (file)
Converts a hash table to a plist
more-hash-util.lisp (file)
Performs a shallow (non-recursive) copy of a hash table.
hash-util.lisp (file)
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.
hash-util.lisp (file)
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.
hash-util.lisp (file)
(setf hash-get) (function)
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.
hash-util.lisp (file)
hash-get (function)
Grab all the hash keys of the passed hash into a list.
hash-util.lisp (file)
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.
hash-util.lisp (file)
(setf hget) (function)
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.
hash-util.lisp (file)
hget (function)
Converts a plist to an alist
more-hash-util.lisp (file)
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.
more-hash-util.lisp (file)
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal functions |
Previous: Internal definitions, Up: Internal definitions [Contents][Index]
hash-util.lisp (file)
more-hash-util.lisp (file)
hash-util.lisp (file)
hash-util.lisp (file)
Is the object something from which key could be fetched?
hash-util.lisp (file)
more-hash-util.lisp (file)
more-hash-util.lisp (file)
Previous: Definitions, Up: Top [Contents][Index]
| • Concept index | ||
| • Function index | ||
| • Variable index | ||
| • Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
| Jump to: | C F L |
|---|
| Jump to: | C F L |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | %
(
A C F H M P S W |
|---|
| Jump to: | %
(
A C F H M P S W |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| 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: Variable index, Up: Indexes [Contents][Index]
| 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 |
|---|