Common Lisp Package: YASON

README:

YASON

> YASON is a Common Lisp library for encoding and decoding data in the >JSON> interchange format. JSON is used as a lightweight alternative to > XML. YASON has the sole purpose of encoding and decoding data and > does not impose any object model on the Common Lisp application that > uses it.

Please proceed to the Documentation

FUNCTION

Public

ENCODE-ARRAY-ELEMENT (OBJECT)

Encode OBJECT as next array element to the last JSON array opened with WITH-ARRAY in the dynamic context. OBJECT is encoded using the ENCODE generic function, so it must be of a type for which an ENCODE method is defined.

ENCODE-ARRAY-ELEMENTS (&REST OBJECTS)

Encode OBJECTS, a list of JSON encodable objects, as array elements.

ENCODE-OBJECT-ELEMENT (KEY VALUE)

Encode KEY and VALUE as object element to the last JSON object opened with WITH-OBJECT in the dynamic context. KEY and VALUE are encoded using the ENCODE generic function, so they both must be of a type for which an ENCODE method is defined.

ENCODE-OBJECT-ELEMENTS (&REST ELEMENTS)

Encode plist ELEMENTS as object elements.

NULL (OBJECT)

Return true if OBJECT is a NULL, and NIL otherwise.

PARSE (INPUT &KEY (OBJECT-KEY-FN *PARSE-OBJECT-KEY-FN*) (OBJECT-AS *PARSE-OBJECT-AS*) (JSON-ARRAYS-AS-VECTORS *PARSE-JSON-ARRAYS-AS-VECTORS*) (JSON-BOOLEANS-AS-SYMBOLS *PARSE-JSON-BOOLEANS-AS-SYMBOLS*) (JSON-NULLS-AS-KEYWORD *PARSE-JSON-NULL-AS-KEYWORD*))

Parse INPUT, which needs to be a string or a stream, as JSON. Returns the lisp representation of the JSON structure parsed. The keyword arguments can be used to override the parser settings as defined by the respective special variables.

Undocumented

ENCODE-ALIST (OBJECT &OPTIONAL (STREAM *STANDARD-OUTPUT*))

ENCODE-PLIST (OBJECT &OPTIONAL (STREAM *STANDARD-OUTPUT*))

Private

%PARSE-ARRAY (INPUT ADD-ELEMENT-FUNCTION)

Parse JSON array from input, calling ADD-ELEMENT-FUNCTION for each array element parsed.

MAKE-ADJUSTABLE-STRING

Return an adjustable empty string, usable as a buffer for parsing strings and numbers.

Undocumented

ADD-ATTRIBUTE (TO KEY VALUE)

CREATE-CONTAINER

ENCODE-ASSOC-KEY/VALUE (KEY VALUE STREAM)

ENCODE-KEY/VALUE (KEY VALUE STREAM)

NEXT-AGGREGATE-ELEMENT

PARSE-ARRAY (INPUT)

PARSE-CONSTANT (INPUT)

PARSE-NUMBER (INPUT)

PARSE-OBJECT (INPUT)

PARSE-STRING (INPUT)

PEEK-CHAR-SKIPPING-WHITESPACE (INPUT &OPTIONAL (EOF-ERROR-P T))

SKIP-WHITESPACE (INPUT)

WHITESPACE-P (CHAR)

MACRO

Public

WITH-ARRAY (NIL &BODY BODY)

Open a JSON array, then run BODY. Inside the body, ENCODE-ARRAY-ELEMENT must be called to encode elements to the opened array. Must be called within an existing JSON encoder context, see WITH-OUTPUT and WITH-OUTPUT-TO-STRING*.

WITH-OBJECT (NIL &BODY BODY)

Open a JSON object, then run BODY. Inside the body, ENCODE-OBJECT-ELEMENT or WITH-OBJECT-ELEMENT must be called to encode elements to the object. Must be called within an existing JSON encoder context, see WITH-OUTPUT and WITH-OUTPUT-TO-STRING*.

WITH-OBJECT-ELEMENT ((KEY) &BODY BODY)

Open a new encoding context to encode a JSON object element. KEY is the key of the element. The value will be whatever BODY serializes to the current JSON output context using one of the stream encoding functions. This can be used to stream out nested object structures.

WITH-OUTPUT ((STREAM &REST ARGS &KEY INDENT) &BODY BODY)

Set up a JSON streaming encoder context on STREAM, then evaluate BODY.

WITH-OUTPUT-TO-STRING* ((&REST ARGS &KEY INDENT) &BODY BODY)

Set up a JSON streaming encoder context, then evaluate BODY. Return a string with the generated JSON output.

Private

WITH-AGGREGATE/OBJECT ((STREAM OPENING-CHAR CLOSING-CHAR) &BODY BODY)

Set up serialization context for aggregate serialization with the object encoder.

WITH-AGGREGATE/STREAM ((BEGIN-CHAR END-CHAR) &BODY BODY)

Set up context for aggregate serialization for the stream encoder.

GENERIC-FUNCTION

Public

ENCODE (OBJECT &OPTIONAL STREAM)

Encode OBJECT to STREAM in JSON format. May be specialized by applications to perform specific rendering. STREAM defaults to *STANDARD-OUTPUT*.

ENCODE-OBJECT (OBJECT)

Encode OBJECT, presumably a CLOS object as a JSON object, invoking the ENCODE-SLOTS method as appropriate.

ENCODE-SLOTS (OBJECT)

Generic function to encode objects. Every class in a hierarchy implements a method for ENCODE-OBJECT that serializes its slots. It is a PROGN generic function so that for a given instance, all slots are serialized by invoking the ENCODE-OBJECT method for all classes that it inherits from.

Undocumented

MAKE-JSON-OUTPUT-STREAM (STREAM &KEY INDENT (INDENT T))

Private

Undocumented

CHANGE-INDENTATION (STREAM OPERATOR)

KEY-STRING (CONDITION)

PARSE% (INPUT)

WRITE-DELIMITER (CHAR STREAM)

WRITE-INDENTATION (STREAM)

SLOT-ACCESSOR

Private

Undocumented

INDENT (OBJECT)

INDENT% (OBJECT)

SETFINDENT% (NEW-VALUE OBJECT)

INDENT-STRING (OBJECT)

SETFINDENT-STRING (NEW-VALUE OBJECT)

OUTPUT-STREAM (OBJECT)

STACK (OBJECT)

SETFSTACK (NEW-VALUE OBJECT)

VARIABLE

Public

*PARSE-JSON-ARRAYS-AS-VECTORS*

If set to a true value, JSON arrays will be parsed as vectors, not as lists.

*PARSE-JSON-BOOLEANS-AS-SYMBOLS*

If set to a true value, JSON booleans will be read as the symbols TRUE and FALSE, not as T and NIL, respectively.

*PARSE-JSON-NULL-AS-KEYWORD*

If set to a true value, JSON nulls will be read as the keyword :NULL, not as NIL.

*PARSE-OBJECT-AS*

Set to either :hash-table, :plist or :alist to determine the data structure that objects are parsed to.

*PARSE-OBJECT-AS-ALIST*

DEPRECATED, provided for backward compatibility

*PARSE-OBJECT-KEY-FN*

Function to call to convert a key string in a JSON array to a key in the CL hash produced.

Private

*DEFAULT-INDENT*

Set to T or an numeric indentation width in order to have YASON indent its output by default.

*DEFAULT-INDENT-WIDTH*

Default indentation width for output if indentation is selected with no indentation width specified.

Undocumented

*CHAR-REPLACEMENTS*

CLASS

Public

Undocumented

NULL (OBJECT)

Private

JSON-OUTPUT-STREAM

Objects of this class capture the state of a JSON stream encoder.

CONDITION

Public

NO-JSON-OUTPUT-CONTEXT

This condition is signalled when one of the stream encoding function is used outside the dynamic context of a WITH-OUTPUT or WITH-OUTPUT-TO-STRING* body.

Private

Undocumented

CANNOT-CONVERT-KEY

EXPECTED-COLON

CONSTANT

Private

+DEFAULT-STRING-LENGTH+

Default length of strings that are created while reading json input.

+INITIAL-ARRAY-SIZE+

Initial size of JSON arrays read, they will grow as needed.