README.org

dc-ds

A collection of functions for representing and rendering data structures.

The ds function allows you to create a nested data structure consisting of hash tables, lists, and arrays. Creating a very simple such structure in Common Lisp might look like this:

(let ((x (make-hash-table :test 'equal)))
  (setf (gethash "one" x) (list 1 2 3)
        (gethash "two" x) (list 4 5 6)
        (gethash "three" x) (list 7 8 (let ((y (make-hash-table :test 'equal)))
                                        (setf (gethash "z" y) 1
                                              (gethash "y" y) 2
                                              (gethash "x" y) 3)
                                        y)))
  x)

Creating the same data structure using the ds function looks like this:

(ds '(:map "one" (:list 1 2 3)
           "two" (:list 4 5 6)
           "three" (:list 7 8 (:map "z" 1 "y" 2 "x" 3))))

You’ll need code to render a human-readable representation of the the data structure. Or, you can use human, which will return the following for the example data structure that we created above (manually or using ds):

(human x)
;; which gives us the following
;;
;;     (:map "one" (:list 1 2 3)                          
;;           "two" (:list 4 5 6)                          
;;           "three" (:list 7 8 (:map "z" 1 "y" 2 "x" 3)))
;;
;; which is perfectly human-readable

Now, let’s say you want to select the value associated with "x" in the above data structure. In Common Lisp, you might do something like this:

(gethash "x" (elt (gethash "three" *ds*) 2))
;; which gives us 3

Even for a super simple nested data structure, the path to an element of the structure looks unintuitive. Here’s the way to access the element using the pick function:

(pick *ds* "three" 2 "x")

If you have a large, complex JSON file, for example, and you need to access elements of that serialized data structure, you can convert the whole thing into a ds data structure with the function from-json. Then, traversing the tree in Common Lisp is trivial.

To convert a ds data structure into a JSON string, use `to-json`.