json¶
This library provides essential functionality for working with JSON data. JSON (JavaScript Object Notation) is a lightweight data interchange format that is easy for humans to read and write, and easy for machines to parse and generate.
The json Module¶
Constants¶
- $null Constant¶
When parsing, JSON’s “null” is converted to this value and when printing this value is printed as “null”.
Conditions¶
- <json-error> Open Instantiable Class¶
All JSON errors are subclasses of this class.
- Superclasses:
<format-string-condition>
<error>
- <json-parse-error> Instantiable Class¶
Any error signalled during parsing (except for file system errors) will be an instance of this class.
- Superclasses:
Parsing¶
- parse-json Open Generic function¶
Parse JSON formatted text from the given source. This is the main user-visible entry point for parsing. table-class, if provided, should be a subclass of
<table>
to use when creating a json “object”.- Signature:
parse-json (source, #key strict?, table-class) => (json)
- Parameters:
- Values:
json – A JSON
<object>
- Discussion:
The parse is strict by default. If
strict?:
#f
is used then:# is allowed as a comment character
\<c>
is equivalent to<c>
, where<c>
is not a defined escape character.Trailing commas are allowed in arrays and objects.
- parse-json(<string>) Method¶
Parse a JSON object from a
<string>
.- Signature:
parse-json (source, #key strict?, table-class) => (json)
- Parameters:
- Values:
json – An instance of
<object>
.
- Example:
let data = """{"a": 1, "b": 2,}"""; let parsed = parse-json(data, strict?: #f); let a = parsed["a"];
Run this example in https://play.opendylan.org
Note the use of
strict?: #f
is needed since data has a trailing comma after the number 2.
- parse-json(<stream>) Method¶
Parse a JSON object from a
<stream>
.- Signature:
parse-json (source, #key strict?, table-class) => (json)
- Parameters:
- Values:
json – An instance of
<object>
.
- Example:
with-open-file (fs = "data.json") let data = parse-json(fs, strict?: #f); ... end;
Run an example with a string stream in https://play.opendylan.org
Printing¶
- print-json Function¶
Print an object in JSON format.
- Signature:
print-json (object, stream, #key indent, sort-keys?) => ()
- Parameters:
- Discussion:
If
indent
is false, object is printed with minimal whitespace. Ifindent
is an integer, then pretty printing is used, with indent spaces for each indent level.If
sort-keys?
is true, output object keys in lexicographical order.This function does some initial setup and then calls
do-print-json
to printobject
.do-print-json
has methods for most built-in Dylan types.
- do-print-json Open Generic function¶
- Signature:
do-print-json (object, stream) => ()
- Parameters:
object – An instance of
<object>
.stream – An instance of
<stream>
.
- Discussion:
This method may be overridden for your own classes in order to print them in JSON format. Often the simplest way to implement your method will be to convert your object to a
<table>
and then pass it toprint-json
to print it on stream.It is also possible to write JSON syntax directly to stream. If indent: was passed to print then stream will be a pretty printing stream and the pprint module in the IO library may be used to implement pretty printing.
- do-print-json(== $null) Method¶
Prints “null” on the output stream.
- do-print-json(<string>) Method¶
Prints a
<string>
on the output stream as a JSON compatible string. Specifically, this method limits the escape codes to those recognized by the JSON format and converts non-printable characters to Unicode escape sequences.
- do-print-json(<collection>) Method¶
Prints a
<collection>
on the output stream as a JSON array.