cl-hash-util

API Reference

cl-hash-util

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

CL-HASH-UTIL

  • Variable *ERROR-ON-NIL*
    nil
    If hget encounters a nil, error out.
  • Function HASH-CREATE (pairs &key (test #'equal))
    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.
  • Macro HASH (&rest pairs)
    Extends hash-create syntax to make it nicer.
  • 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.
  • 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.
  • Function HASH-COPY (hash &key (test #'equal))
    Performs a shallow (non-recursive) copy of a hash table.
  • Function HASH-KEYS (hash)
    Grab all the hash keys of the passed hash into a list.
  • 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.
  • Macro COLLECTING-HASH-TABLE ((&key (test '#'eql test-set-p) existing (mode :append)) &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.
  • Function ALIST->PLIST (alist)
    Converts an alist to a plist
  • Function PLIST->ALIST (plist)
    Converts a plist to an alist
  • Function ALIST->HASH (al &key (mode :replace) 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.
  • Function PLIST->HASH (plist &key (mode :replace) 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.
  • Function HASH->ALIST (hsh)
    Converts a hash table to an alist
  • Function HASH->PLIST (hsh)
    Converts a hash table to a plist