The shasht Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The shasht Reference Manual

This is the shasht Reference Manual, version 0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Nov 04 15:13:01 2020 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

shasht

Build Status

Common Lisp JSON reading and writing for the Kzinti.

Reading

The primary interface to parsing and reading JSON is the read-json function.

(read-json &optional input-stream-or-string (eof-error-p t) eof-value single-value-p)

The argument input-stream-or-string can be an stream, a string to read from, or nil to use *standard-input*. The arguments eof-error-p and eof-value have the same affect as they do in the Common Lisp function read. If the single-value-p argument is true then the input to read-json is assumed to be a single value, which means that extra tokens at the end will cause an error to be generated.

There are a number of dynamic variables that will influence the parsing of JSON data.

Writing

The primary interface to serializing and writing JSON is the write-json function.

(write-json value &optional (output-stream t))

The output-stream argument can be a stream, t for *standard-output*, or nil for output to a string. If the output is to a string then this string will be returned, otherwise the original value will be returned.

There are a number of dynamic variables that will influence the serialization of JSON data.

The actual serialization of JSON data is done by the generic function print-json-value which can be specialized for additional value types.

(print-json-value value output-stream)

In order to facilitate extending the serialization facilities of shasht there are a number of helper functions available. To aid in the printing of JSON strings there is the following.

(write-json-string value output-stream)

In order to ease the serialization of objects and arrays there is with-json-object and with-json-array. Both of these macros take an output stream as the first argument then enable indentation and automatic handling of all delimiter tokens. Inside the body of with-json-object the function (print-json-key-value key value output-stream) should be used to output a key value pair. Inside the body of with-json-array the function (print-json-value value output-stream) should be used to output a single value. Example usage can be seen in the source code.

Compliance

Although concise the JSON specification is very vague on a number of points and thus accurate compliance by implementations is often substandard. Without comprehensive tests compliance is difficult to ascertain. The JSONTestSuite includes over 300 reading tests including those left ambiguous by the specification. The test suite of shasht includes all of these tests in addition to various write tests. For a comparision of the compliance of the Common Lisp implementations of JSON see Compliance Comparision.

Benchmarks

A simple benchmark can be done with tests/bench.lisp. For SBCL the following results are typical.

                                JSON Read Times                                 
             0                     6.8727204e-6                     1.3745441e-5
             ˫--------------------------------+--------------------------------˧
     cl-json ███████████████████████████████████▋
    jonathan ████████▍
json-streams ███████████████████████████████████████████████████████████████████
       jsown ████████▉
      shasht ██████████████▎
     st-json ██████████████████████████████████▎
       yason ████████████████████████████████████████▌


                                JSON Write Times                                
             0                     6.0235893e-6                     1.2047179e-5
             ˫--------------------------------+--------------------------------˧
     cl-json ███████████████████████████████████████████████████████████████████
    jonathan █████████████████████████████████▊
json-streams ██████████████████████████████▎
       jsown ██████████████████████

Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 shasht

Author

Tarn W. Burton

Home Page

https://yitzchak.github.io/shasht/

Bug Tracker

https://github.com/yitzchak/shasht/issues

License

MIT

Description

JSON reading and writing for the Kzinti.

Version

0.1

Dependency

alexandria

Source

shasht.asd (file)

Component

src (module)


Next: , Previous: , Up: Top   [Contents][Index]

3 Modules

Modules are listed depth-first from the system components tree.


Previous: , Up: Modules   [Contents][Index]

3.1 shasht/src

Parent

shasht (system)

Location

src/

Components

Next: , Previous: , Up: Top   [Contents][Index]

4 Files

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


Previous: , Up: Files   [Contents][Index]

4.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.1 shasht.asd

Location

shasht.asd

Systems

shasht (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.2 shasht/src/packages.lisp

Parent

src (module)

Location

src/packages.lisp

Packages

shasht


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.3 shasht/src/utils.lisp

Dependency

packages.lisp (file)

Parent

src (module)

Location

src/utils.lisp

Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.4 shasht/src/config.lisp

Dependency

utils.lisp (file)

Parent

src (module)

Location

src/config.lisp

Exported Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.5 shasht/src/read.lisp

Dependency

config.lisp (file)

Parent

src (module)

Location

src/read.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

4.1.6 shasht/src/write.lisp

Dependency

read.lisp (file)

Parent

src (module)

Location

src/write.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

5.1 shasht

Source

packages.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

6 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.1 Special variables

Special Variable: *indent-character*

The character to use when indenting objects and arrays.

Package

shasht

Source

config.lisp (file)

Special Variable: *indent-increment*

The number of *indent-character* to use at each indention level if *print-pretty* is true.

Package

shasht

Source

config.lisp (file)

Special Variable: *read-default-array-format*

The default format to use when reading an array. Current supported formats are :vector or :list.

Package

shasht

Source

config.lisp (file)

Special Variable: *read-default-false-value*

The default value to return when reading a false token.

Package

shasht

Source

config.lisp (file)

Special Variable: *read-default-null-value*

The default value to return when reading a null token.

Package

shasht

Source

config.lisp (file)

Special Variable: *read-default-object-format*

The default format to use when reading an object. Current supported formats are :hash-table, :alist or :plist.

Package

shasht

Source

config.lisp (file)

Special Variable: *read-default-true-value*

The default value to return when reading a true token.

Package

shasht

Source

config.lisp (file)

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

If true then assocation lists will be written as an object.

Package

shasht

Source

config.lisp (file)

Special Variable: *write-ascii-encoding*

If true then any non ASCII values will be encoded using Unicode escape sequences.

Package

shasht

Source

config.lisp (file)

Special Variable: *write-empty-array-values*

Values that will be written as an empty array.

Package

shasht

Source

config.lisp (file)

Special Variable: *write-empty-object-values*

Values that will be written as an empty object.

Package

shasht

Source

config.lisp (file)

Special Variable: *write-false-values*

Values that will be written as a false token.

Package

shasht

Source

config.lisp (file)

Special Variable: *write-null-values*

Values that will be written as a null token.

Package

shasht

Source

config.lisp (file)

Special Variable: *write-plist-as-object*

If true then property lists will be written as an object.

Package

shasht

Source

config.lisp (file)

Special Variable: *write-true-values*

Values that will be written as a true token.

Package

shasht

Source

config.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.2 Macros

Macro: with-json-array OUTPUT-STREAM &body BODY

Enable JSON array writing for body. Array open/close and commas will be automatically handled when calls to print-json-value are made.

Package

shasht

Source

write.lisp (file)

Macro: with-json-object OUTPUT-STREAM &body BODY

Enable JSON object writing for body. Object open/close and commas will be automatically handled when calls to print-json-key-value are made.

Package

shasht

Source

write.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.3 Functions

Function: print-json-key-value KEY VALUE OUTPUT-STREAM

Print a JSON key value. Must be used inside of with-json-object.

Package

shasht

Source

write.lisp (file)

Function: read-json &optional INPUT-STREAM-OR-STRING EOF-ERROR-P EOF-VALUE SINGLE-VALUE-P

Read a JSON value. Reading is influenced by the dynamic variables *read-default-true-value*, *read-default-false-value*, *read-default-null-value*, *read-default-array-format*, *read-default-object-format* and common-lisp:*read-default-float-format* which each determine the default values and formats used. The following arguments also control the behavior of the read.

* input-stream-or-string - a stream, a string or t. If t is passed then *standard-input* is used.
* eof-error-p - if true signal eof with error, otherwise return eof-value.
* eof-value - value used if eof-error-p is nil.
* single-value-p - Check for trailing junk after read is complete.

Package

shasht

Source

read.lisp (file)

Function: write-json VALUE &optional OUTPUT-STREAM

Read a JSON value. Reading is influenced by the dynamic variables *write-ascii-encoding*, *write-true-values*, *write-false-values*, *write-null-values*, *write-alist-as-object*, *write-plist-as-object*, *indent-increment*, *indent-character* and common-lisp:*print-pretty* which simple indentation of arrays and objects.

The following arguments also control the behavior of the write.

* value - The value to be written.
* output-stream - a stream or nil to return a string or t to use *standard-output*.

Package

shasht

Source

write.lisp (file)

Function: write-json-string VALUE OUTPUT-STREAM

Write value as a JSON string to stream specified by output-stream.

Package

shasht

Source

write.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.4 Generic functions

Generic Function: print-json-value VALUE OUTPUT-STREAM

Print a JSON value to output-stream. Used by write-json to dispatch based on type.

Package

shasht

Source

write.lisp (file)

Methods
Method: print-json-value (VALUE symbol) OUTPUT-STREAM
Method: print-json-value (VALUE vector) OUTPUT-STREAM
Method: print-json-value (VALUE list) OUTPUT-STREAM
Method: print-json-value (VALUE hash-table) OUTPUT-STREAM
Method: print-json-value (VALUE string) OUTPUT-STREAM
Method: print-json-value (VALUE integer) OUTPUT-STREAM
Method: print-json-value (VALUE number) OUTPUT-STREAM
Method: print-json-value VALUE OUTPUT-STREAM before

Previous: , Up: Exported definitions   [Contents][Index]

6.1.5 Conditions

Condition: shasht-parse-error ()
Package

shasht

Source

read.lisp (file)

Direct superclasses

parse-error (condition)

Direct methods
Direct slots
Slot: expected
Initargs

:expected

Initform

(quote nil)

Readers

shasht-parse-error-expected (generic function)

Slot: char
Initargs

:char

Readers

shasht-parse-error-char (generic function)


Previous: , Up: Definitions   [Contents][Index]

6.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.1 Special variables

Special Variable: *delimiter*
Package

shasht

Source

write.lisp (file)

Special Variable: *indent-level*
Package

shasht

Source

write.lisp (file)

Special Variable: *next-delimiter*
Package

shasht

Source

write.lisp (file)

Special Variable: *next-terminator*
Package

shasht

Source

write.lisp (file)

Special Variable: *terminator*
Package

shasht

Source

write.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.2 Macros

Macro: array-begin EXPRESSION-STACK
Package

shasht

Source

read.lisp (file)

Macro: array-end EXPRESSION-STACK
Package

shasht

Source

read.lisp (file)

Macro: object-begin EXPRESSION-STACK
Package

shasht

Source

read.lisp (file)

Macro: object-end EXPRESSION-STACK
Package

shasht

Source

read.lisp (file)

Macro: object-key EXPRESSION-STACK KEY
Package

shasht

Source

read.lisp (file)

Macro: value EXPRESSION-STACK VALUE-FORM
Package

shasht

Source

read.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.3 Functions

Function: alistp ALIST
Package

shasht

Source

utils.lisp (file)

Function: ascii-printable-p CHAR-CODE
Package

shasht

Source

utils.lisp (file)

Function: control-char-p CH
Package

shasht

Source

utils.lisp (file)

Function: copy-reader-state INSTANCE
Package

shasht

Source

read.lisp (file)

Function: expect-char INPUT-STREAM VALUE SKIP-WHITESPACE ERROR-P
Package

shasht

Source

read.lisp (file)

Function: high-surrogate-p CODE
Package

shasht

Source

utils.lisp (file)

Function: integer-char-p CHAR
Package

shasht

Source

utils.lisp (file)

Function: make-reader-state &key (TYPE TYPE) (VALUE VALUE) (KEY KEY)
Package

shasht

Source

read.lisp (file)

Function: plistp PLIST
Package

shasht

Source

utils.lisp (file)

Function: read-encoded-char INPUT-STREAM
Package

shasht

Source

read.lisp (file)

Function: read-json-number INPUT-STREAM
Package

shasht

Source

read.lisp (file)

Function: read-json-string INPUT-STREAM SKIP-QUOTE
Package

shasht

Source

read.lisp (file)

Function: reader-state-key INSTANCE
Function: (setf reader-state-key) VALUE INSTANCE
Package

shasht

Source

read.lisp (file)

Function: reader-state-p OBJECT
Package

shasht

Source

read.lisp (file)

Function: reader-state-type INSTANCE
Function: (setf reader-state-type) VALUE INSTANCE
Package

shasht

Source

read.lisp (file)

Function: reader-state-value INSTANCE
Function: (setf reader-state-value) VALUE INSTANCE
Package

shasht

Source

read.lisp (file)

Function: skip-whitespace INPUT-STREAM
Package

shasht

Source

read.lisp (file)

Function: supplementary-plane-p CHAR-CODE
Package

shasht

Source

utils.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.4 Generic functions

Generic Function: shasht-parse-error-char CONDITION
Package

shasht

Methods
Method: shasht-parse-error-char (CONDITION shasht-parse-error)
Source

read.lisp (file)

Generic Function: shasht-parse-error-expected CONDITION
Package

shasht

Methods
Method: shasht-parse-error-expected (CONDITION shasht-parse-error)
Source

read.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

6.2.5 Structures

Structure: reader-state ()
Package

shasht

Source

read.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots
Slot: type
Initform

:value

Readers

reader-state-type (function)

Writers

(setf reader-state-type) (function)

Slot: value
Readers

reader-state-value (function)

Writers

(setf reader-state-value) (function)

Slot: key
Readers

reader-state-key (function)

Writers

(setf reader-state-key) (function)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   M   S  
Index Entry  Section

F
File, Lisp, shasht.asd: The shasht․asd file
File, Lisp, shasht/src/config.lisp: The shasht/src/config․lisp file
File, Lisp, shasht/src/packages.lisp: The shasht/src/packages․lisp file
File, Lisp, shasht/src/read.lisp: The shasht/src/read․lisp file
File, Lisp, shasht/src/utils.lisp: The shasht/src/utils․lisp file
File, Lisp, shasht/src/write.lisp: The shasht/src/write․lisp file

L
Lisp File, shasht.asd: The shasht․asd file
Lisp File, shasht/src/config.lisp: The shasht/src/config․lisp file
Lisp File, shasht/src/packages.lisp: The shasht/src/packages․lisp file
Lisp File, shasht/src/read.lisp: The shasht/src/read․lisp file
Lisp File, shasht/src/utils.lisp: The shasht/src/utils․lisp file
Lisp File, shasht/src/write.lisp: The shasht/src/write․lisp file

M
Module, shasht/src: The shasht/src module

S
shasht.asd: The shasht․asd file
shasht/src: The shasht/src module
shasht/src/config.lisp: The shasht/src/config․lisp file
shasht/src/packages.lisp: The shasht/src/packages․lisp file
shasht/src/read.lisp: The shasht/src/read․lisp file
shasht/src/utils.lisp: The shasht/src/utils․lisp file
shasht/src/write.lisp: The shasht/src/write․lisp file

Jump to:   F   L   M   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
A   C   E   F   G   H   I   M   O   P   R   S   V   W  
Index Entry  Section

(
(setf reader-state-key): Internal functions
(setf reader-state-type): Internal functions
(setf reader-state-value): Internal functions

A
alistp: Internal functions
array-begin: Internal macros
array-end: Internal macros
ascii-printable-p: Internal functions

C
control-char-p: Internal functions
copy-reader-state: Internal functions

E
expect-char: Internal functions

F
Function, (setf reader-state-key): Internal functions
Function, (setf reader-state-type): Internal functions
Function, (setf reader-state-value): Internal functions
Function, alistp: Internal functions
Function, ascii-printable-p: Internal functions
Function, control-char-p: Internal functions
Function, copy-reader-state: Internal functions
Function, expect-char: Internal functions
Function, high-surrogate-p: Internal functions
Function, integer-char-p: Internal functions
Function, make-reader-state: Internal functions
Function, plistp: Internal functions
Function, print-json-key-value: Exported functions
Function, read-encoded-char: Internal functions
Function, read-json: Exported functions
Function, read-json-number: Internal functions
Function, read-json-string: Internal functions
Function, reader-state-key: Internal functions
Function, reader-state-p: Internal functions
Function, reader-state-type: Internal functions
Function, reader-state-value: Internal functions
Function, skip-whitespace: Internal functions
Function, supplementary-plane-p: Internal functions
Function, write-json: Exported functions
Function, write-json-string: Exported functions

G
Generic Function, print-json-value: Exported generic functions
Generic Function, shasht-parse-error-char: Internal generic functions
Generic Function, shasht-parse-error-expected: Internal generic functions

H
high-surrogate-p: Internal functions

I
integer-char-p: Internal functions

M
Macro, array-begin: Internal macros
Macro, array-end: Internal macros
Macro, object-begin: Internal macros
Macro, object-end: Internal macros
Macro, object-key: Internal macros
Macro, value: Internal macros
Macro, with-json-array: Exported macros
Macro, with-json-object: Exported macros
make-reader-state: Internal functions
Method, print-json-value: Exported generic functions
Method, print-json-value: Exported generic functions
Method, print-json-value: Exported generic functions
Method, print-json-value: Exported generic functions
Method, print-json-value: Exported generic functions
Method, print-json-value: Exported generic functions
Method, print-json-value: Exported generic functions
Method, print-json-value: Exported generic functions
Method, shasht-parse-error-char: Internal generic functions
Method, shasht-parse-error-expected: Internal generic functions

O
object-begin: Internal macros
object-end: Internal macros
object-key: Internal macros

P
plistp: Internal functions
print-json-key-value: Exported functions
print-json-value: Exported generic functions
print-json-value: Exported generic functions
print-json-value: Exported generic functions
print-json-value: Exported generic functions
print-json-value: Exported generic functions
print-json-value: Exported generic functions
print-json-value: Exported generic functions
print-json-value: Exported generic functions
print-json-value: Exported generic functions

R
read-encoded-char: Internal functions
read-json: Exported functions
read-json-number: Internal functions
read-json-string: Internal functions
reader-state-key: Internal functions
reader-state-p: Internal functions
reader-state-type: Internal functions
reader-state-value: Internal functions

S
shasht-parse-error-char: Internal generic functions
shasht-parse-error-char: Internal generic functions
shasht-parse-error-expected: Internal generic functions
shasht-parse-error-expected: Internal generic functions
skip-whitespace: Internal functions
supplementary-plane-p: Internal functions

V
value: Internal macros

W
with-json-array: Exported macros
with-json-object: Exported macros
write-json: Exported functions
write-json-string: Exported functions

Jump to:   (  
A   C   E   F   G   H   I   M   O   P   R   S   V   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
C   E   K   S   T   V  
Index Entry  Section

*
*delimiter*: Internal special variables
*indent-character*: Exported special variables
*indent-increment*: Exported special variables
*indent-level*: Internal special variables
*next-delimiter*: Internal special variables
*next-terminator*: Internal special variables
*read-default-array-format*: Exported special variables
*read-default-false-value*: Exported special variables
*read-default-null-value*: Exported special variables
*read-default-object-format*: Exported special variables
*read-default-true-value*: Exported special variables
*terminator*: Internal special variables
*write-alist-as-object*: Exported special variables
*write-ascii-encoding*: Exported special variables
*write-empty-array-values*: Exported special variables
*write-empty-object-values*: Exported special variables
*write-false-values*: Exported special variables
*write-null-values*: Exported special variables
*write-plist-as-object*: Exported special variables
*write-true-values*: Exported special variables

C
char: Exported conditions

E
expected: Exported conditions

K
key: Internal structures

S
Slot, char: Exported conditions
Slot, expected: Exported conditions
Slot, key: Internal structures
Slot, type: Internal structures
Slot, value: Internal structures
Special Variable, *delimiter*: Internal special variables
Special Variable, *indent-character*: Exported special variables
Special Variable, *indent-increment*: Exported special variables
Special Variable, *indent-level*: Internal special variables
Special Variable, *next-delimiter*: Internal special variables
Special Variable, *next-terminator*: Internal special variables
Special Variable, *read-default-array-format*: Exported special variables
Special Variable, *read-default-false-value*: Exported special variables
Special Variable, *read-default-null-value*: Exported special variables
Special Variable, *read-default-object-format*: Exported special variables
Special Variable, *read-default-true-value*: Exported special variables
Special Variable, *terminator*: Internal special variables
Special Variable, *write-alist-as-object*: Exported special variables
Special Variable, *write-ascii-encoding*: Exported special variables
Special Variable, *write-empty-array-values*: Exported special variables
Special Variable, *write-empty-object-values*: Exported special variables
Special Variable, *write-false-values*: Exported special variables
Special Variable, *write-null-values*: Exported special variables
Special Variable, *write-plist-as-object*: Exported special variables
Special Variable, *write-true-values*: Exported special variables

T
type: Internal structures

V
value: Internal structures

Jump to:   *  
C   E   K   S   T   V  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   R   S  
Index Entry  Section

C
Condition, shasht-parse-error: Exported conditions

P
Package, shasht: The shasht package

R
reader-state: Internal structures

S
shasht: The shasht system
shasht: The shasht package
shasht-parse-error: Exported conditions
Structure, reader-state: Internal structures
System, shasht: The shasht system

Jump to:   C   P   R   S