jsown, high performance Common Lisp json parser

jsown is a high performance Common Lisp json parser. Its aim is to allow for the fast parsing of json objects in CL.

jsown allows you to parse json objects quickly to a modifiable lisp list and write them back. If you only need partial retrieval of objects, jsown allows you to select the keys which you would like to see parsed. jsown also has a json writer and some helper methods to alter the json objects themselves.

parsing json objects

In order to parse a json object, simply use the parse function.

  (jsown:parse "{\"foo\":\"bar\",\"baz\":100.25}")
  =>(:OBJ ("foo" . "bar") ("baz" . 401/4))

Without any extra arguments, the parse function will return all keywords. In order to select only a few keywords, you can add those keywords in which you’re interested:

  (jsown:parse "{\"foo\":\"bar\",\"frolic\":100,\"fragrance\":10.01,\"for\":\"markup\"}" "foo" "frolic" "fragrance")
  => (:OBJ ("foo" . "bar") ("frolic" . 100) ("fragrance" . 1001/100))

In order to achieve high performance when parsing specific keywords, the keywords to be found should be known at compile time. The compiler-macro-function can calculate the keyword container with the requested keywords at compile-time. When specifying the keywords in which you’re interested you should ignore any escaped characters. For instance, supplying the string “foo” will automatically match “f\\\\oo” too."

Editing json objects

jsown ships with some convience functions to inspect and alter the returned json content.

In order to see which keywords have been defined in a parsed json object, you can use the keywords function:

  (jsown:keywords '(:obj ("foo" . "bar") ("frolic" . 100) ("fragrance" . 1001/100)))
  => ("foo" "frolic" "fragrance")

You can traverse over all keywords by using the do-json-keys function.

  CL-USER> (jsown:do-json-keys (keyword value)
               '(:obj ("foo" . "bar") ("frolic" . 100) ("fragrance" . 1001/100))
             (format T "~A => ~A~&" keyword value))
  foo => bar
  frolic => 100
  fragrance => 1001/100
  NIL

The fetching of the value given to a certain keyword may be done by using the val function. This function also has a setf defined on it.
The (setf val) function may alter the original object, it is however not guaranteed to do so.

  (jsown:val '(:obj ("foo" . "bar") ("frolic" . 100) ("fragrance" . 1001/100)) "frolic")
  => 100
  (setf (jsown:val '(:obj ("foo" . "bar") ("frolic" . 100) ("fragrance" . 1001/100)) "frolic") "I wasn't here before")
  => (:obj ("foo" . "bar") ("frolic" . "I wasn't here before") ("fragrance" . 1001/100))

You can build objects by using the val function too, albeit it doesn’t look really sexy.

  (setf (jsown:val (setf (jsown:val (setf (jsown:val (jsown:empty-object) "foo") "bar") "bang") (list 1 2 3 "foo" 4 5)) "bingo") 24.93)
  =>(:obj ("bingo" . 24.93) ("bang" 1 2 3 "foo" 4 5) ("foo" . "bar"))

Writing json objects

jsown supports the writing of json objects too, use the to-json CLOS method for this. You can provide an implementation for this method for your own objects so those can easily be converted to json too (and it will ensure that nested objects are correctly transformed to json).

  (jsown:to-json '(:obj ("bingo" . 24.93) ("bang" 1 2 3 "foo" 4 5) ("foo" . "bar")))
  => "{\"bingo\":24.93,\"bang\":[1,2,3,\"foo\",4,5],\"foo\":\"bar\"}"