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:

<json-error>

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:

  • source – An <object>.

  • strict? (#key) – An instance of <boolean>.

  • table-class (#key) – Default to <string-table>.

Values:
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:

  • source – An instance of <string>

  • strict? (#key) – An instance of <boolean>. The default is #t.

  • table-class (#key) – A subclass of <table>.

Values:
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:

  • source – An instance of <stream>.

  • strict? (#key) – An instance of <boolean>. The default is #f.

  • table-class (#key) – A subclass of <table>.

Values:
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:

  • object – The object to print. An instance of <object>.

  • stream – Stream on wich to do output. An instance of <stream>.

  • indent (#key) – #f or an instance of <integer>.

  • sort-keys? (#key) – An instance of <boolean>.

Discussion:

If indent is false, object is printed with minimal whitespace. If indent 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 print object. 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 to print-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(<integer>) Method

Prints an <integer> on the output stream.

do-print-json(<float>) Method

Prints a <float> on the output stream.

do-print-json(<boolean>) Method

Prints a <boolean> on the output stream as “true” or “false”.

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.

do-print-json(<table>) Method

Prints a <table> on the output stream as a JSON “object”.