json-streams is a Common Lisp library for reading and writing JSON text.
- Designed to used as a building block for more high level libraries.
- No dependencies.
- Easy to use streaming API.
- Validates input and output.
- Unambiguous mapping of datatypes between lisp and JSON.
- Streaming design, can proccess JSON text of unlimted size.
- Proper handling of Unicode.
High level interface
The high level interface uses the following datatype mapping:
|number||integer, float or ratio|
|array||(:ARRAY … )|
|object||(:OBJECT (key . value) … )|
The options are explained under MAKE-JSON-INPUT-STREAM and MAKE-JSON-OUTPUT-STREAM.
Function JSON-STREAMS:JSON-PARSE source &rest options => json, position
Parses a single JSON text from source. The second value is the position where parsing stopped.
Function JSON-STREAMS:JSON-PARSE-MULTIPLE source &rest options => jsons
Parses zero or more JSON texts from source. Returns a list of JSON values.
Function JSON-STREAMS:JSON-STRINGIFY value &optional target &rest options
Stringifies value into JSON text. If target is not provided or NIL, returns a string with the JSON text. Otherwise target must be a character stream.
Function JSON-STREAMS:JSON-STRINGIFY-MULTIPLE values &optional target &rest options
Stringifies multiple json values.
The streaming interface
See parse.lisp and stringify.lisp for examples of how to use the streaming interface.
Function JSON-STREAMS:MAKE-JSON-INPUT-STREAM source &key start end close-stream multiple duplicate-key-check use-ratios max-exponent raw-strings => json-input-stream
- source - A character stream or a string. When source is a string, start and end are bounding index designators of string.
- use-ratios - Default NIL. When false, numbers that can not be represented as integers are returned as double-floats. Then true, these numbers are returned as ratios.
- max-exponent - Default 325. The maximum (positive and negative) exponent accepted in numbers. Setting to a high number opens up for a easy to use denial-of-service attack.
- raw-strings - Default NIL. When true, strings are returned as (:STRING numbers*), where numbers represent Unicode code points. For Unicode escape sequences in strings (\uXXXX), no UTF-16 validation or decoding is done.
Function JSON-STREAMS:MAKE-JSON-OUTPUT-STREAM stream &key close-stream multiple duplicate-key-check indent escape-non-ascii => json-input-stream
- stream - A character stream.
- indent - Default NIL. When true, the JSON text is broken into lines and indented.
- escape-non-ascii - Default NIL. When true, any character outside the ASCII character set will be escaped using the \uXXXX syntax.
- close-stream - Default NIL. When T, the source stream will be closed by JSON-CLOSE.
- multiple - Default NIL. When NIL, only a single JSON text (object or array) is expected in the stream. When T, zero or more JSON texts can be read from or written to stream.
- duplicate-key-check - Default T. When true, an error will be signaled when duplicate keys are detected in an object. Setting this to NIL avoids the added overhead of checking for duplicate keys.
Function JSON-STREAMS:JSON-READ json-input-stream => token
Parses JSON text from the underlying stream and returns the next token.
Function JSON-STREAMS:JSON-WRITE token json-output-stream => token
Outputs JSON text to underlying stream based on the given token.
Function JSON-STREAMS:JSON-CLOSE json-stream
Closes the json-stream. Applications should always call JSON-CLOSE when finished with a JSON stream. This ensures that all syntax errors are detected.
Macro JSON-STREAMS:WITH-OPEN-JSON-STREAM (var json-stream) &body
Binds var to json-stream, executes body, and ensures that JSON-CLOSE is called on json-stream.
The possible tokens for input and output are
- A number
- A string or (:STRING integer*)
After a :BEGIN-OBJECT is returned, JSON-READ will alternate between returning keys and values of the object, until :END-OBJECT is returned instead of a key. Keys are always returned as strings. Values can be anything, except :END-OBJECT, :END-ARRAY and :EOF. Thus some kind of recursive or stack based algorithm is neccearry.
Handling of numbers
The syntax doesn’t matter: 20, 20.0 or 2e1 are all the same number, the integer 20.
The integer range is +/- (expt 10 53). Numbers outside this range can’t be represented accurately. This library will refuse to write an integer outside this range. If you need to output such large numbers, convert them to double-float or string.
At input the handling of numbers outside the integer range depends on syntax. If the number contains a decimal point or an exponent it will be returned as a double-float. Otherwise an error will be signalled. The option :USE-RATIOS disables this check.