ST-JSON

ST-JSON ('ST' because it originated at Streamtech) is a Common Lisp library for encoding and decoding JSON values (as specified on json.org).

This library does mostly the same thing as CL-JSON, but is simpler and more precise about types (distinguishing boolean false, the empty array, and the empty object).

Download and installation

The library is available under a zlib-style license. It can be installed with asdf-install, or you can download the current release manually. The git repository can be checked out with:

git clone http://marijnhaverbeke.nl/git/st-json

The code is also on github.

Support

Mail Marijn Haverbeke with any questions, bug reports, patches, etcetera. I'll set up some mailing list when there is a need.

Documentation

ST-JSON maps JavaScript numbers to Lisp numbers, strings to strings, null to the keyword :null, booleans to the keywords :true and :false, arrays to lists, and objects to a custom type jso (JavaScript object). Since in CL boolean false, the empty list, and nullish stuff is all usually represented by nil, you will sometimes have to selectively transform your values before writing or after reading them. (The empty array is a truthy value in JavaScript, so writing out nil for a boolean is bound to get you into trouble.)

type json-bool

A type including only the values :true and :false. Useful in read-json-as-type and similar.

function as-json-bool (value)
→ json-bool

Convert a generalised boolean to a json-bool.

function from-json-bool (value)
→ bool

Convert a json-bool to a Lisp boolean.

type json-null

A type containing only :null.

function jso (&rest fields)
→ jso

jso names both a function and a type. This type is used to represent JavaScript objects. It simply wraps an alist. The function is called with an even number of arguments, which give the properties of the object and their values.

function getjso (key jso)
→ value

Looks up a value in a JavaScript object, returns a second value indicating whether the value was found (like gethash). Can be used with setf.

function getjso* (keys jso)
→ value

Takes a key of the form "a.b.c", generates a series of getjso calls that descend into the object and returns 'c'.

function mapjso (function jso)

maphash equivalent for JavaScript objects.

method read-json (source &optional junk-allowed-p)
→ value

Reads a JSON value from an input stream or string. When junk-allowed-p is nil, an error will be raised if any non-whitespace characters are found after the value. This error, and any other parsing errors, will have the type json-parse-error.

function read-json-as-type (source type)
→ value

Like read-json, but also asserts that the resulting value is of a given type, and raises an error of type json-type-error if not.

function write-json (element stream)

Writes a value to a stream. Raises an error of type json-write-error if a value for which no write-json-element method is defined is encountered.

function write-json-to-string (element)
→ string

Like write-json, but produces a string.

method write-json-element (element stream)

Generic function used to serialise values as JSON. You can specialise it for your own types, if needed.

variable *script-tag-hack*

Bind this to t when writing JSON that will end up in an HTML document. It prevents '</script>' from occurring in strings by escaping any slash following a '<' character. Default value is nil.