For Gauche 0.9.5

Next: , Previous: , Up: Library modules - Utilities   [Contents][Index]

12.36 rfc.json - JSON parsing and construction

Module: rfc.json

Procedures to parse JSON (RFC7159) data to S-expressions, and convert S-expressions to JSON representation, are provided.

Condition type: <json-parse-error>

The parser parse-json and parse-json-string raise this condition when they encounter invalid JSON syntax. It inherits <error>, and adds the following slot.

Instance Variable of <json-parse-error>: position

The input position, counted in characters, where the error occurred.

Function: parse-json :optional input-port

Reads and parses the JSON representation from input-port (default is the current input port), and returns the result in an S-expression. May raise a <json-parse-error> condition when parse error occurs.

The following table shows how JSON datatypes are mapped to Scheme objects.

true, false, null

Symbols true, false and null. (Customizable by json-special-handler)


Scheme vectors. (Customizable by json-array-handler)


Scheme assoc-lists, in which keys are strings, and values are Scheme objects. (Customizable by json-object-handler)


Scheme inexact real numbers.


Scheme strings.

Since the parser used internally in parse-json prefetches characters, some characters after the parsed JSON expression may already been read from port when parse-json returns. That is, you cannot call parse-json repeatedly on port to read subsequent JSON expressions. Use parse-json* if you need to read multiple JSON expressions.

Function: parse-json* :optional input-port

Read JSON repeatedly from input-port until it reaches EOF, and returns parsed results as a list.

Function: parse-json-string str

Parses the JSON string and returns the result in an S-expression. May raise a <json-parse-error> condition when parse error occurs.

See parse-json above for the mappings from JSON datatypes to Scheme types.

Parameter: json-array-handler
Parameter: json-object-handler
Parameter: json-special-handler

The value of these parameters must be a procedure that takes one argument: for json-array-handler, it is a list of elements of a JSON array, for json-object-handler, it is a list of conses of key and value of a JSON object, and for json-special-handler, it is one of the symbols false, true or null.

Whenever parse-json reads a JSON array, a JSON object, or one of those special values, it calls corresponding parameter to get a Scheme object.

The default value of these parameters are list->vector, identity, and identity, respectively.

The following example maps JSON objects to hash tables.

(use gauche.parameter)
(parameterize ([json-object-handler (cut alist->hash-table <> 'string=?)])
  (parse-json-string "{\"a\":1, \"b\":2}"))
 ⇒ #<hash-table ...>
Condition type: <json-construct-error>

The converters construct-json and construct-json-string raise this condition when they cannot convert given Scheme object to JSON. It inherits <error>, and adds the following slot.

Instance Variable of <json-construct-error>: object

The Scheme object that cannot convert to JSON representation.

Function: construct-json obj :optional output-port
Function: construct-json-string obj

Creates JSON representation of Scheme object obj. construct-json writes out the result to output-port, whose default is the current output port. construct-json-string returns the result in a string. Note that RFC4627 defines JSON text to be an object or an array; so obj must be a Scheme object that can be mapped to either a JSON object or a JSON array.

If obj contains a Scheme object that cannot be mapped to JSON representation, a <json-construct-error> condition is raised.

Scheme objects are mapped to JSON as follows:

symbol false, #f


symbol true, #t


symbol null


list, instance of <dictionary>

JSON object (list must be an assoc list of key and value).



real number


instance of <sequence> (except strings and lists)

JSON array

Next: , Previous: , Up: Library modules - Utilities   [Contents][Index]