Gerbil Scheme

JSON

To use the bindings from this module:

(import :std/text/json)

read-json

(read-json [input = (current-input-port)]) -> json | error

  input := input source to read JSON data

Returns JSON object from given input source. Signals an error if fails to parse JSON

The input source can be:

  • An input port.
  • A BufferedStringReader.
  • A BufferedReader.

write-json

(write-json obj [sink = (current-output-port)]) -> void | error

  obj  := JSON object
  sink := output sink to write JSON data

Writes JSON object obj optionally given port. Defaults to using current-output-port. Signals an error on failed write.

The output sink can be:

  • An output port.
  • A BufferedStringWriter.
  • A BufferedWriter.
  • A StringWriter.
  • A Writer.

string->json-object

(string->json-object str) -> json | error

  str := a string of JSON data

Parses given str and returns JSON object or signals an error if it fails to parse.

json-object->string

(json-object->string obj) -> string | error

  obj := JSON object

Returns a newly allocated string with JSON object as a string. Signals an error if fails to print JSON.

bytes->json-object

(bytes->json-object str) -> json | error

  bytes := u8vector encoding a UTF-8 string of JSON data

Parses given bytes and returns JSON object or signals an error if it fails to parse.

json-object->bytes

(json-object->bytes obj) -> u8vector | error

  obj := JSON object

Returns a newly allocated u8vector with JSON object as bytes. Signals an error if it fails to print JSON.

port->json-object

(port->json-object port) -> json | error

  port := input port

Parses data on given port and returns JSON object or signals an error if it fails to parse.

read-json-key-as-symbol?

read-json-key-as-symbol?

Boolean parameter to control whether JSON “objects” be decoded as using symbols rather than strings as keys? #f the default means strings, #t means symbols.

NB: Before v0.18.2, this parameter used to be called json-symbolic-keys and default to #t. The name is still available as an alias (sharing the default #f), but may be removed as early as v0.19.

Examples

> (hash->list (string->json-object "{\"a\":1}"))
(("a" . 1))

> (parameterize ((read-json-key-as-symbol? #t))
    (hash->list (string->json-object "{\"a\":1}")))
((a . 1))

json-object-walist?

json-object-walist?

Parameter to control how JSON objects should be decoded. If false (the default), JSON objects will be hash-tables. If true, JSON objects will be walistq (or walist if read-json-key-as-symbol? is false).

This allows you to preserve the order of keys from JSON text, in cases where this order matters, e.g. for the sake of pretty-printing JSON or reading pretty-printed JSON, where the order will make the data more readable to humans.

NB: This parameter was introduced in Gerbil v0.18.2.

Examples

> (parameterize ((json-object-walist? #f))
    (hash->list (string->json-object "{\"a\":1,\"b\":2}")))
((a . 1) (b . 2))

> (parameterize ((json-object-walist? #t))
    (walist->alist (string->json-object "{\"a\":1,\"b\":2}")))
((a . 1) (b . 2))

read-json-array-as-vector?

read-json-array-as-vector?

Parameter to control how JSON “arrays” should be transformed. Defaults to #f, which means keep them as lists. Binding it to #t instead will mean read them as vectors.

NB: Since Gerbil v0.18.2, this parameter replaces with reduced but more streamlined functionality the previous json-list-wrapper parameter. That previous parameter isn’t used anymore, and may be removed as early as v0.19.

Examples

> (string->json-object "[\"a\",1,[]]")
("a" 1 ())

> (parameterize ((read-json-array-as-vector? #t))
    (string->json-object "[\"a\",1]"))
#("a" 1 ())

write-json-sort-keys?

write-json-sort-keys?

This is a parameter that can be used to control how JSON objects should be written. If false (the default), keys in JSON objects represented by hash-tables will be written in no particular predictable order, by iterating as fast as possible through the hash-table. If true, keys in JSON objects represented by hash-tables will be written in asciibetical order. In either case, JSON objects represented by walists will be written in the order specified by the walist. You can sort the walist yourself according to the order that matters to you, whether asciibetical or not.

NB: This parameter used to be called json-sort-keys and default to #t before Gerbil v0.18.2. The name is still available as an alias (sharing the default #f), but may be removed as early as v0.19.

Examples

> (parameterize ((write-json-sort-keys? #t))
    (json-object->string (hash (foo 1) (bar 2) (baz 3))))
"{\"bar\":2,\"baz\":3,\"foo\":1}"
> (parameterize ((write-json-sort-keys? #f))
    (json-object->string (hash (foo 1) (bar 2) (baz 3))))
"{\"baz\":3,\"bar\":2,\"foo\":1}"

trivial-class->json-object

(trivial-class->json-object object) -> json | error

  object := an object

Extracts a printable JSON object from the slots of an object, or signals an error if it fails.

json-object->trivial-class

(json-object->trivial-class class-descriptor json) -> object | error

  class-descriptor := class-descriptor
  json := hash-table

Creates an object of the class corresponding to the class-descriptor by extracting its slots from a json hash-table.

JSON

JSON -> class
JSON::t -> class-descriptor

A class for object that can be printed as JSON. The default :json method is trivial-class->json-object.

pretty-json

(pretty-json object [output]
   [indent: 2] [sort-keys?: (json-sort-keys)] [lisp-style?: #f])

A function that pretty-prints a JSON object to the specified output as per open-buffered-string-writer (defaults to #f, i.e. print to string). The indent keyword specifies how much to increase indentation at each level of nesting (must be a positive integer, defaults to 2). The sort-keys? keyword offers a shortcut to parameterizing write-json-sort-keys? which is heeded just like by write-json. The lisp-style? keyword if true specifies a format that follows Lisp style, and saves number of lines by starting objects and lists on the same line as the square or curly bracket, and closing it on the same line as the last entry, as opposed to regular style that uses newlines copiously.

NB: Since Gerbil v0.18.2, this function no longer invokes jq -M . as an external program, and no longer uses with-output but instead open-buffered-string-writer, and has extra keyword arguments.

← UTF-16→