The yason Reference Manual

Table of Contents

The yason Reference Manual

This is the yason Reference Manual, version 0.8.3, generated automatically by Declt version 3.0 "Montgomery Scott" on Sun May 15 06:29:30 2022 GMT+0.

1 Introduction

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

This project was maintained by https://github.com/hanshuebner/ until 2019.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 yason

Author

Hans Huebner <hans@huebner.org>

License

BSD

Description

JSON parser/encoder

Long Description

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.

Version

0.8.3

Dependencies

• alexandria
• trivial-gray-streams

Source

yason.asd (file)

Components

• package.lisp (file)
• encode.lisp (file)
• parse.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 yason.asd

Location

yason.asd

Systems

yason (system)

Packages

yason.system

3.1.2 yason/package.lisp

Parent

yason (system)

Location

package.lisp

Packages

yason

3.1.3 yason/encode.lisp

Dependency

package.lisp (file)

Parent

yason (system)

Location

encode.lisp

Exported Definitions

• *list-encoder* (special variable)
• *symbol-encoder* (special variable)
• *symbol-key-encoder* (special variable)
• encode (generic function)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode-alist (function)
• encode-array-element (function)
• encode-array-elements (function)
• encode-object (generic function)
• encode-object (method)
• encode-object-element (function)
• encode-object-elements (function)
• encode-object-slots (compiler macro)
• encode-object-slots (function)
• encode-plain-list-to-array (function)
• encode-plist (function)
• encode-slots (generic function)
• encode-symbol-as-lowercase (function)
• encode-symbol-as-string (function)
• make-json-output-stream (generic function)
• make-json-output-stream (method)
• no-json-output-context (condition)
• with-array (macro)
• with-object (macro)
• with-object-element (macro)
• with-output (macro)
• with-output-to-string* (macro)

Internal Definitions

• *char-replacements* (special variable)
• *default-indent* (special variable)
• *default-indent-width* (special variable)
• *json-output* (special variable)
• change-indentation (generic function)
• change-indentation (method)
• change-indentation (method)
• encode-assoc-key/value (function)
• encode-key/value (function)
• encode-symbol-error (function)
• encode-symbol-key-error (function)
• indent (method)
• indent% (method)
• (setf indent%) (method)
• indent-depth (method)
• (setf indent-depth) (method)
• json-output-stream (class)
• next-aggregate-element (function)
• output-stream (method)
• stack (method)
• (setf stack) (method)
• unicode-char (function)
• unicode-code (function)
• with-aggregate/object (macro)
• with-aggregate/stream (macro)
• write-delimiter (generic function)
• write-delimiter (method)
• write-delimiter (method)
• write-indentation (generic function)
• write-indentation (method)
• write-indentation (method)
• write-surrogate-pair-escape (function)

3.1.4 yason/parse.lisp

Dependency

package.lisp (file)

Parent

yason (system)

Location

parse.lisp

Exported Definitions

• *parse-json-arrays-as-vectors* (special variable)
• *parse-json-booleans-as-symbols* (special variable)
• *parse-json-null-as-keyword* (special variable)
• *parse-object-as* (special variable)
• *parse-object-as-alist* (special variable)
• *parse-object-key-fn* (special variable)
• parse (function)

Internal Definitions

• %parse-array (function)
• +default-string-length+ (constant)
• +initial-array-size+ (constant)
• add-attribute (function)
• cannot-convert-key (condition)
• create-container (function)
• duplicate-key (condition)
• expected-colon (condition)
• key-string (method)
• key-string (method)
• key-string (method)
• make-adjustable-string (function)
• parse% (generic function)
• parse% (method)
• parse% (method)
• parse% (method)
• parse-array (function)
• parse-constant (function)
• parse-number (function)
• parse-object (function)
• parse-string (function)
• parse-unicode-escape (function)
• peek-char-skipping-whitespace (function)
• skip-whitespace (function)
• whitespace-p (function)

4 Packages

Packages are listed by definition order.

4.1 yason.system

Source

yason.asd

Use List

• asdf/interface
• common-lisp

4.2 yason

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

• *list-encoder* (special variable)
• *parse-json-arrays-as-vectors* (special variable)
• *parse-json-booleans-as-symbols* (special variable)
• *parse-json-null-as-keyword* (special variable)
• *parse-object-as* (special variable)
• *parse-object-as-alist* (special variable)
• *parse-object-key-fn* (special variable)
• *symbol-encoder* (special variable)
• *symbol-key-encoder* (special variable)
• encode (generic function)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode-alist (function)
• encode-array-element (function)
• encode-array-elements (function)
• encode-object (generic function)
• encode-object (method)
• encode-object-element (function)
• encode-object-elements (function)
• encode-object-slots (compiler macro)
• encode-object-slots (function)
• encode-plain-list-to-array (function)
• encode-plist (function)
• encode-slots (generic function)
• encode-symbol-as-lowercase (function)
• encode-symbol-as-string (function)
• make-json-output-stream (generic function)
• make-json-output-stream (method)
• no-json-output-context (condition)
• parse (function)
• with-array (macro)
• with-object (macro)
• with-object-element (macro)
• with-output (macro)
• with-output-to-string* (macro)

Internal Definitions

• %parse-array (function)
• *char-replacements* (special variable)
• *default-indent* (special variable)
• *default-indent-width* (special variable)
• *json-output* (special variable)
• +default-string-length+ (constant)
• +initial-array-size+ (constant)
• add-attribute (function)
• cannot-convert-key (condition)
• change-indentation (generic function)
• change-indentation (method)
• change-indentation (method)
• create-container (function)
• duplicate-key (condition)
• encode-assoc-key/value (function)
• encode-key/value (function)
• encode-symbol-error (function)
• encode-symbol-key-error (function)
• expected-colon (condition)
• indent (generic function)
• indent (method)
• indent% (generic function)
• indent% (method)
• (setf indent%) (method)
• (setf indent%) (generic function)
• indent-depth (generic function)
• indent-depth (method)
• (setf indent-depth) (method)
• (setf indent-depth) (generic function)
• json-output-stream (class)
• key-string (generic function)
• key-string (method)
• key-string (method)
• key-string (method)
• make-adjustable-string (function)
• next-aggregate-element (function)
• output-stream (generic function)
• output-stream (method)
• parse% (generic function)
• parse% (method)
• parse% (method)
• parse% (method)
• parse-array (function)
• parse-constant (function)
• parse-number (function)
• parse-object (function)
• parse-string (function)
• parse-unicode-escape (function)
• peek-char-skipping-whitespace (function)
• skip-whitespace (function)
• stack (generic function)
• stack (method)
• (setf stack) (method)
• (setf stack) (generic function)
• unicode-char (function)
• unicode-code (function)
• whitespace-p (function)
• with-aggregate/object (macro)
• with-aggregate/stream (macro)
• write-delimiter (generic function)
• write-delimiter (method)
• write-delimiter (method)
• write-indentation (generic function)
• write-indentation (method)
• write-indentation (method)
• write-surrogate-pair-escape (function)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *list-encoder*

The actual function used to encode a LIST.
Can be changed to encode ALISTs or PLISTs as dictionaries by setting it to ENCODE-ALIST or ENCODE-PLIST.

Package

yason

Source

encode.lisp (file)

Special Variable: *parse-json-arrays-as-vectors*

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

Package

yason

Source

parse.lisp (file)

Special Variable: *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.

Package

yason

Source

parse.lisp (file)

Special Variable: *parse-json-null-as-keyword*

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

Package

yason

Source

parse.lisp (file)

Special Variable: *parse-object-as*

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

Package

yason

Source

parse.lisp (file)

Special Variable: *parse-object-as-alist*

DEPRECATED, provided for backward compatibility

Package

yason

Source

parse.lisp (file)

Special Variable: *parse-object-key-fn*

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

Package

yason

Source

parse.lisp (file)

Special Variable: *symbol-encoder*

The actual function used to encode a SYMBOL. You might want ENCODE-SYMBOL-AS-LOWERCASE or ENCODE-SYMBOL-AS-STRING here.

Package

yason

Source

encode.lisp (file)

Special Variable: *symbol-key-encoder*

The actual function used to encode a SYMBOL when seen as a key.
You might want ENCODE-SYMBOL-AS-LOWERCASE or
ENCODE-SYMBOL-AS-STRING here.
The function returns just a string - the quotes are added when writing the key.

Package

yason

Source

encode.lisp (file)

5.1.2 Macros

Macro: with-array () &body BODY

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

Package

yason

Source

encode.lisp (file)

Macro: with-object () &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*.

Package

yason

Source

encode.lisp (file)

Macro: 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.

Package

yason

Source

encode.lisp (file)

Macro: with-output (STREAM &rest ARGS &key INDENT) &body BODY

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

Package

yason

Source

encode.lisp (file)

Macro: with-output-to-string* (&rest ARGS &key INDENT STREAM-SYMBOL) &body BODY

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

Package

yason

Source

encode.lisp (file)

5.1.3 Compiler macros

Compiler Macro: encode-object-slots OBJECT RAW-SLOTS &key LOWERCASE-KEYS?

Compiler macro to allow open-coding with ENCODE-OBJECT-SLOTS when slots are a literal list.

Package

yason

Source

encode.lisp (file)

5.1.4 Functions

Function: encode-alist OBJECT &optional STREAM

Package

yason

Source

encode.lisp (file)

Function: 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.

Package

yason

Source

encode.lisp (file)

Function: encode-array-elements &rest OBJECTS

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

Package

yason

Source

encode.lisp (file)

Function: 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.

Package

yason

Source

encode.lisp (file)

Function: encode-object-elements &rest ELEMENTS

Encode plist ELEMENTS as object elements.

Package

yason

Source

encode.lisp (file)

Function: encode-object-slots OBJECT SLOTS &key LOWERCASE-KEYS?

For each slot in SLOTS, encode that slot on OBJECT as an object element. Equivalent to calling ENCODE-OBJECT-ELEMENT for each slot where the key is the slot name, and the value is the (SLOT-VALUE OBJECT slot). LOWERCASE-KEYS? says whether the key should be in lowercase.

Package

yason

Source

encode.lisp (file)

Function: encode-plain-list-to-array OBJECT STREAM

Package

yason

Source

encode.lisp (file)

Function: encode-plist OBJECT &optional STREAM

Package

yason

Source

encode.lisp (file)

Function: encode-symbol-as-lowercase KEY

Encodes a symbol KEY as a lowercase string.
Ensure that there’s no intentional lower-case character lost.

Package

yason

Source

encode.lisp (file)

Function: encode-symbol-as-string SYM &optional PREFIX

Encodes a symbol SYM as string PACKAGE:SYMBOL-NAME. Always prints a double colon, as exportedness might not make sense for the receiver;
this way reading the input in again is consistent. Preserves case.
Breaks if the package name includes colons.

Package

yason

Source

encode.lisp (file)

Function: parse INPUT &key OBJECT-KEY-FN OBJECT-AS JSON-ARRAYS-AS-VECTORS JSON-BOOLEANS-AS-SYMBOLS JSON-NULLS-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.

Package

yason

Source

parse.lisp (file)

5.1.5 Generic functions

Generic Function: encode OBJECT &optional STREAM

Encode OBJECT to STREAM in JSON format. May be
specialized by applications to perform specific rendering. STREAM must be a JSON-OUTPUT-STREAM; you can get one via MAKE-JSON-OUTPUT-STREAM, WITH-OUTPUT, or WITH-OUTPUT-TO-STRING*.

Package

yason

Source

encode.lisp (file)

Methods

Method: encode (OBJECT (eql nil)) &optional STREAM

Method: encode (OBJECT (eql t)) &optional STREAM

Method: encode (OBJECT (eql null)) &optional STREAM

Method: encode (OBJECT (eql false)) &optional STREAM

Method: encode (OBJECT (eql true)) &optional STREAM

Method: encode (OBJECT symbol) &optional STREAM

Method: encode (OBJECT list) &optional STREAM

Method: encode (OBJECT vector) &optional STREAM

Method: encode (OBJECT hash-table) &optional STREAM

Method: encode (OBJECT integer) &optional STREAM

Method: encode (OBJECT float) &optional STREAM

Method: encode (OBJECT ratio) &optional STREAM

Method: encode (STRING string) &optional STREAM

Generic Function: encode-object OBJECT

Generic function to encode an object. The default implementation opens a new object encoding context and calls ENCODE-SLOTS on the argument.

Package

yason

Source

encode.lisp (file)

Methods

Method: encode-object OBJECT

Generic Function: encode-slots OBJECT

Generic function to encode object slots. It should be called in an object encoding context. It uses PROGN combination with MOST-SPECIFIC-LAST order, so that base class slots are encoded before derived class slots.

Package

yason

Source

encode.lisp (file)

Method Combination

progn (short method combination)

Options: :most-specific-last

Generic Function: make-json-output-stream STREAM &key INDENT

Package

yason

Source

encode.lisp (file)

Methods

Method: make-json-output-stream STREAM &key INDENT

Create a JSON output stream with indentation enabled.

5.1.6 Conditions

Condition: 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.

Package

yason

Source

encode.lisp (file)

Direct superclasses

error (condition)

5.2 Internal definitions

5.2.1 Constants

Constant: +default-string-length+

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

Package

yason

Source

parse.lisp (file)

Constant: +initial-array-size+

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

Package

yason

Source

parse.lisp (file)

5.2.2 Special variables

Special Variable: *char-replacements*

Package

yason

Source

encode.lisp (file)

Special Variable: *default-indent*

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

Package

yason

Source

encode.lisp (file)

Special Variable: *default-indent-width*

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

Package

yason

Source

encode.lisp (file)

Special Variable: *json-output*

Package

yason

Source

encode.lisp (file)

5.2.3 Macros

Macro: with-aggregate/object (STREAM OPENING-CHAR CLOSING-CHAR) &body BODY

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

Package

yason

Source

encode.lisp (file)

Macro: with-aggregate/stream (BEGIN-CHAR END-CHAR) &body BODY

Set up context for aggregate serialization for the stream encoder.

Package

yason

Source

encode.lisp (file)

5.2.4 Functions

Function: %parse-array INPUT ADD-ELEMENT-FUNCTION

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

Package

yason

Source

parse.lisp (file)

Function: add-attribute TO KEY VALUE

Package

yason

Source

parse.lisp (file)

Function: create-container HT

Package

yason

Source

parse.lisp (file)

Function: encode-assoc-key/value KEY VALUE STREAM

Package

yason

Source

encode.lisp (file)

Function: encode-key/value KEY VALUE STREAM

Package

yason

Source

encode.lisp (file)

Function: encode-symbol-error KEY

Package

yason

Source

encode.lisp (file)

Function: encode-symbol-key-error KEY

Package

yason

Source

encode.lisp (file)

Function: make-adjustable-string ()

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

Package

yason

Source

parse.lisp (file)

Function: next-aggregate-element ()

Package

yason

Source

encode.lisp (file)

Function: parse-array INPUT

Package

yason

Source

parse.lisp (file)

Function: parse-constant INPUT

Package

yason

Source

parse.lisp (file)

Function: parse-number INPUT

Package

yason

Source

parse.lisp (file)

Function: parse-object INPUT

Package

yason

Source

parse.lisp (file)

Function: parse-string INPUT

Package

yason

Source

parse.lisp (file)

Function: parse-unicode-escape INPUT

Package

yason

Source

parse.lisp (file)

Function: peek-char-skipping-whitespace INPUT &optional EOF-ERROR-P

Package

yason

Source

parse.lisp (file)

Function: skip-whitespace INPUT

Package

yason

Source

parse.lisp (file)

Function: unicode-char CODE

Package

yason

Source

encode.lisp (file)

Function: unicode-code CHAR

Package

yason

Source

encode.lisp (file)

Function: whitespace-p CHAR

Package

yason

Source

parse.lisp (file)

Function: write-surrogate-pair-escape CODE STREAM

Package

yason

Source

encode.lisp (file)

5.2.5 Generic functions

Generic Function: change-indentation STREAM INCREMENT

Package

yason

Source

encode.lisp (file)

Methods

Method: change-indentation STREAM OPERATOR

Method: change-indentation (STREAM json-output-stream) INCREMENT

Generic Function: indent OBJECT

Package

yason

Methods

Method: indent (JSON-OUTPUT-STREAM json-output-stream)

automatically generated reader method

Source

encode.lisp (file)

Generic Function: indent% OBJECT

Generic Function: (setf indent%) NEW-VALUE OBJECT

Package

yason

Methods

Method: indent% (JSON-OUTPUT-STREAM json-output-stream)

automatically generated reader method

Source

encode.lisp (file)

Method: (setf indent%) NEW-VALUE (JSON-OUTPUT-STREAM json-output-stream)

automatically generated writer method

Source

encode.lisp (file)

Generic Function: indent-depth OBJECT

Generic Function: (setf indent-depth) NEW-VALUE OBJECT

Package

yason

Methods

Method: indent-depth (JSON-OUTPUT-STREAM json-output-stream)

automatically generated reader method

Source

encode.lisp (file)

Method: (setf indent-depth) NEW-VALUE (JSON-OUTPUT-STREAM json-output-stream)

automatically generated writer method

Source

encode.lisp (file)

Generic Function: key-string CONDITION

Package

yason

Methods

Method: key-string (CONDITION expected-colon)

Source

parse.lisp (file)

Method: key-string (CONDITION duplicate-key)

Source

parse.lisp (file)

Method: key-string (CONDITION cannot-convert-key)

Source

parse.lisp (file)

Generic Function: output-stream OBJECT

Package

yason

Methods

Method: output-stream (JSON-OUTPUT-STREAM json-output-stream)

automatically generated reader method

Source

encode.lisp (file)

Generic Function: parse% INPUT

Package

yason

Source

parse.lisp (file)

Methods

Method: parse% (INPUT stream)

Method: parse% (INPUT pathname)

Method: parse% (INPUT string)

Generic Function: stack OBJECT

Generic Function: (setf stack) NEW-VALUE OBJECT

Package

yason

Methods

Method: stack (JSON-OUTPUT-STREAM json-output-stream)

automatically generated reader method

Source

encode.lisp (file)

Method: (setf stack) NEW-VALUE (JSON-OUTPUT-STREAM json-output-stream)

automatically generated writer method

Source

encode.lisp (file)

Generic Function: write-delimiter CHAR STREAM

Package

yason

Source

encode.lisp (file)

Methods

Method: write-delimiter CHAR STREAM

Method: write-delimiter CHAR (STREAM json-output-stream)

Generic Function: write-indentation STREAM

Package

yason

Source

encode.lisp (file)

Methods

Method: write-indentation STREAM

Method: write-indentation (STREAM json-output-stream)

5.2.6 Conditions

Condition: cannot-convert-key ()

Package

yason

Source

parse.lisp (file)

Direct superclasses

error (condition)

Direct methods

key-string (method)

Direct slots

Slot: key-string

Initargs

:key-string

Readers

key-string (generic function)

Condition: duplicate-key ()

Package

yason

Source

parse.lisp (file)

Direct superclasses

error (condition)

Direct methods

key-string (method)

Direct slots

Slot: key-string

Initargs

:key-string

Readers

key-string (generic function)

Condition: expected-colon ()

Package

yason

Source

parse.lisp (file)

Direct superclasses

error (condition)

Direct methods

key-string (method)

Direct slots

Slot: key-string

Initargs

:key-string

Readers

key-string (generic function)

5.2.7 Classes

Class: json-output-stream ()

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

Package

yason

Source

encode.lisp (file)

Direct superclasses

fundamental-character-output-stream (class)

Direct methods

• change-indentation (method)
• write-delimiter (method)
• write-indentation (method)
• stream-write-char (method)
• initialize-instance (method)
• indent% (method)
• indent (method)
• indent% (method)
• indent-depth (method)
• indent-depth (method)
• stack (method)
• stack (method)
• output-stream (method)

Direct slots

Slot: output-stream

Initargs

:output-stream

Readers

output-stream (generic function)

Slot: stack

Readers

stack (generic function)

Writers

(setf stack) (generic function)

Slot: indent-depth

Initform

0

Readers

indent-depth (generic function)

Writers

(setf indent-depth) (generic function)

Slot: indent

Initargs

:indent

Readers

• indent% (generic function)
• indent (generic function)

Writers

(setf indent%) (generic function)

Direct Default Initargs

Initarg	Value
:indent	yason::*default-indent*

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types