Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the shasht Reference Manual, version 0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 17:45:34 2021 GMT+0.
| • Introduction | What shasht is all about | |
| • Systems | The systems documentation | |
| • Modules | The modules documentation | |
| • Files | The files documentation | |
| • Packages | The packages documentation | |
| • Definitions | The symbols documentation | |
| • Indexes | Concepts, functions, variables and data types |
[![Build Status][ci-badge]][ci]
Common Lisp JSON reading and writing for the Kzinti.
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.
common-lisp:*read-default-float-format* — Controls the floating-point format
that is to be used when reading a floating-point number.*read-default-true-value* — The default value to return when reading a true
token. Initially set to t.*read-default-false-value* — The default value to return when reading a
false token. Initially set to nil.*read-default-null-value* — The default value to return when reading a null
token. Initially set to :null.*read-default-array-format* — The default format to use when reading an
array. Current supported formats are :vector or :list. Initially set to
:vector.*read-default-object-format* — The default format to use when reading an
object. Current supported formats are :hash-table, :alist or :plist.
Initially set to :hash-table.There is also a keyword variant read-json* which will set the various dynamic
variables from supplied keywords.
(read-json* :stream nil
:eof-error t
:eof-value nil
:single-value nil
:true-value t
:false-value nil
:null-value :null
:array-format :vector
:object-format :hash-table
:float-format 'single-float)
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.
common-lisp:*print-pretty* — If true then a simple indentation algorithm
will be used.*write-indent-string* — The string to use when indenting objects and arrays.
Initially set to #\space.*write-ascii-encoding* — If true then any non ASCII values will be encoded
using Unicode escape sequences. Initially set to nil.*write-true-values* — Values that will be written as a true token. Initially
set to '(t :true).*write-false-values* — Values that will be written as a false token.
Initially set to '(nil :false).*write-null-values* — Values that will be written as a null token. Initially
set to (:null).*write-alist-as-object* — If true then assocation lists will be written as
an object. Initially set to nil.*write-plist-as-object* — If true then property lists will be written as an
object. Initially set to nil.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)
There is also a keyword variant write-json* which will set the various dynamic
variables from supplied keywords.
(write-json* value :stream t
:ascii-encoding nil
:true-values '(t :true)
:false-values '(nil :false)
:null-values '(:null)
:empty-array-values '(:empty-array)
:empty-object-values '(:empty-object)
:alist-as-object nil
:plist-as-object nil
:pretty nil
:indent-string " ")
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.
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.
A simple benchmark can be done with tests/bench.lisp. For SBCL the following
results are typical.
JSON Read Times
0 7.002169e-6 1.4004338e-5
˫--------------------------------+--------------------------------˧
cl-json ███████████████████████████████████▉
jonathan ████████▊
json-streams ███████████████████████████████████████████████████████████████████
jsown █████████▋
shasht █████████████▏
st-json █████████████████████████████████▊
yason ████████████████████████████████████████▉
JSON Write Times
0 6.2018808e-6 1.24037615e-5
˫--------------------------------+--------------------------------˧
cl-json ███████████████████████████████████████████████████████████████████
jonathan ████████████████████████████████████▍
json-streams ███████████████████████████████▎
jsown ████████████████████████████████████████▉
shasht ███████████▍
st-json ███████
Next: Modules, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The shasht system |
Tarn W. Burton
MIT
JSON reading and writing for the Kzinti.
0.1
trivial-do
shasht.asd (file)
src (module)
Modules are listed depth-first from the system components tree.
| • The shasht/src module |
shasht (system)
src/
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files |
| • The shasht.asd file | ||
| • The shasht/src/packages.lisp file | ||
| • The shasht/src/utils.lisp file | ||
| • The shasht/src/config.lisp file | ||
| • The shasht/src/read.lisp file | ||
| • The shasht/src/write.lisp file |
Next: The shasht/src/packages․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
shasht.asd
shasht (system)
Next: The shasht/src/utils․lisp file, Previous: The shasht․asd file, Up: Lisp files [Contents][Index]
Next: The shasht/src/config․lisp file, Previous: The shasht/src/packages․lisp file, Up: Lisp files [Contents][Index]
packages.lisp (file)
src (module)
src/utils.lisp
make-object (function)
Next: The shasht/src/read․lisp file, Previous: The shasht/src/utils․lisp file, Up: Lisp files [Contents][Index]
utils.lisp (file)
src (module)
src/config.lisp
Next: The shasht/src/write․lisp file, Previous: The shasht/src/config․lisp file, Up: Lisp files [Contents][Index]
config.lisp (file)
src (module)
src/read.lisp
Previous: The shasht/src/read․lisp file, Up: Lisp files [Contents][Index]
read.lisp (file)
src (module)
src/write.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The shasht package |
packages.lisp (file)
common-lisp
Definitions are sorted by export status, category, package, and then by lexicographic order.
| • Exported definitions | ||
| • Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
| • Exported special variables | ||
| • Exported macros | ||
| • Exported functions | ||
| • Exported generic functions | ||
| • Exported conditions |
Next: Exported macros, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
The default format to use when reading an array. Current supported formats are :vector or :list.
config.lisp (file)
The default value to return when reading a false token.
config.lisp (file)
The default value to return when reading a null token.
config.lisp (file)
The default format to use when reading an object. Current supported formats are :hash-table, :alist or :plist.
config.lisp (file)
The default value to return when reading a true token.
config.lisp (file)
If true then assocation lists will be written as an object.
config.lisp (file)
If true then any non ASCII values will be encoded using Unicode escape sequences.
config.lisp (file)
Values that will be written as an empty array.
config.lisp (file)
Values that will be written as an empty object.
config.lisp (file)
Values that will be written as a false token.
config.lisp (file)
The string to use when indenting objects and arrays.
config.lisp (file)
Values that will be written as a null token.
config.lisp (file)
If true then property lists will be written as an object.
config.lisp (file)
Values that will be written as a true token.
config.lisp (file)
Next: Exported functions, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
Enable JSON array writing for body. Array open/close and commas will be automatically handled when calls to print-json-value are made.
write.lisp (file)
Enable JSON object writing for body. Object open/close and commas will be automatically handled when calls to print-json-key-value are made.
write.lisp (file)
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
Create a hash table based on args (in plist format) and a test of equal.
utils.lisp (file)
Print a JSON key value. Must be used inside of with-json-object.
write.lisp (file)
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.
Read a JSON value. Reading is influenced by the keyword arguments and not by the dynamic
variables of ‘read-json‘.
* stream - a stream, a string or t. If t is passed then *standard-input* is used.
* eof-error - if true signal eof with error, otherwise return eof-value.
* eof-value - value used if eof-error-p is nil.
* single-value - Check for trailing junk after read is complete.
* true-value - The value to return when reading a true token.
* false-value - The value to return when reading a false token.
* null-value - The value to return when reading a null token.
* array-format - The format to use when reading an array. Current supported formats are
:vector or :list.
* object-format - The format to use when reading an object. Current supported formats are
:hash-table, :alist or :plist.
* float-format - The format of floating point values.
Write a JSON value. Writing 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*,
*write-indent-string* and common-lisp:*print-pretty*.
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*.
write.lisp (file)
Write a JSON value. Writing is not influenced by the dynamic variables
of write-json.
The following arguments also control the behavior of the write.
* value - The value to be written.
* stream - a stream or nil to return a string or t to use
*standard-output*.
* ascii-encoding - If true then any non ASCII values will be encoded
using Unicode escape sequences.
* true-values - Values that will be written as a true token.
* false-values - Values that will be written as a false token.
* null-values - Values that will be written as a null token.
* empty-array-values - Values that will be written as an empty array.
* empty-object-values - Values that will be written as an empty object.
* alist-as-object - If true then assocation lists will be written as an object.
* plist-as-object - If true then property lists will be written as an object.
* pretty - Use indentation in printing.
* indent-string - The string to use when indenting objects and arrays.
write.lisp (file)
Write value as a JSON string to stream specified by output-stream.
write.lisp (file)
Next: Exported conditions, Previous: Exported functions, Up: Exported definitions [Contents][Index]
Print a JSON value to output-stream. Used by write-json to dispatch based on type.
write.lisp (file)
Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
read.lisp (file)
parse-error (condition)
:expected
(quote nil)
shasht-parse-error-expected (generic function)
:char
shasht-parse-error-char (generic function)
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal special variables | ||
| • Internal macros | ||
| • Internal functions | ||
| • Internal generic functions | ||
| • Internal structures | ||
| • Internal types |
Next: Internal macros, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
write.lisp (file)
write.lisp (file)
write.lisp (file)
write.lisp (file)
write.lisp (file)
Next: Internal functions, Previous: Internal special variables, Up: Internal definitions [Contents][Index]
Next: Internal generic functions, Previous: Internal macros, Up: Internal definitions [Contents][Index]
utils.lisp (file)
utils.lisp (file)
utils.lisp (file)
utils.lisp (file)
utils.lisp (file)
write.lisp (file)
utils.lisp (file)
utils.lisp (file)
utils.lisp (file)
Next: Internal structures, Previous: Internal functions, Up: Internal definitions [Contents][Index]
Next: Internal types, Previous: Internal generic functions, Up: Internal definitions [Contents][Index]
read.lisp (file)
structure-object (structure)
:value
reader-state-type (function)
(setf reader-state-type) (function)
reader-state-value (function)
(setf reader-state-value) (function)
reader-state-key (function)
(setf reader-state-key) (function)
Previous: Internal structures, Up: Internal definitions [Contents][Index]
utils.lisp (file)
utils.lisp (file)
Previous: Definitions, Up: Top [Contents][Index]
| • Concept index | ||
| • Function index | ||
| • Variable index | ||
| • Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
| Jump to: | F L M S |
|---|
| Jump to: | F L M S |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | (
A C E F G H I M O P R S V W |
|---|
| Jump to: | (
A C E F G H I M O P R S V W |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | *
C E K S T V |
|---|
| Jump to: | *
C E K S T V |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | C H L P R S T |
|---|
| Jump to: | C H L P R S T |
|---|