medea

medea
1. Description
2. API
3. Examples
4. About this egg
  1. Source
  2. Author
  3. Version history
  4. License

A JSON reader and writer based on the Comparse parsing library. In contrast to the alternative implementations json and json-abnf its representation of JSON data types in Scheme can be fully customized. It's also possible to change how and what Scheme data types are serialized to JSON.

API

[procedure] (read-json [port-or-string] #!key consume-trailing-whitespace)

Reads a JSON document from port-or-string which is (current-input-port) by default. The returned object is assembled according to the current json-parsers parameter.

By default trailing whitespace in the input is consumed (as per the grammar defined in RFC 4627). To disable this behavior (e.g. to allow early return when streaming a sequence of JSON documents) the keyword argument consume-trailing-whitespace can be passed as #f.

[procedure] (write-json datum [port])

Writes the given JSON datum to port which is (current-output-port) by default. datum's conversion to JSON is inferred by its Scheme type via the current json-unparsers parameter.

A common gotcha is that the default json-unparsers assume lists to be alists which are written as JSON objects. If you want to write a JSON array you need to pass a Scheme vector instead.

[procedure] (json->string datum)

Like write-json but returns a string instead of writing to a port.

[parameter] (json-parsers [parsers])

An alist which maps JSON data type symbols to procedures which are used to convert the corresponding data types to Scheme data structures. By default the following mappings apply:

string: string
number: number
member: pair (keys are represented as symbols)
object: list of member pairs
array: vector
true: #t
false: #f
null: 'null

[parameter] (json-unparsers [unparsers])

An alist which maps predicate functions to emitter functions. When a datum is to be written the predicates are tried in order until one returns #t. The datum is passed to the corresponding emitter function which is expected to write its JSON representation to (current-output-port). By default the following mappings apply:

list?: object (an alist with symbols for keys is expected)
vector?: array
string?: string
number?: number
(lambda (x) (eq? x #t)): "true"
(lambda (x) (eq? x #f)): "false"
(lambda (x) (eq? x 'null)): "null"

Examples

(import medea (chicken port))

;; Reading from a port
(with-input-from-string "[1,2,3]" read-json) ; => #(1 2 3)


;; Reading from a string
(read-json "[1,2,3]") ; => #(1 2 3)


;; Writing to a port
(write-json '((foo . 1) (bar . 2))) ; output: {"foo":1,"bar":2}


;; Writing to a string
(json->string '((foo . "bar"))) ; => "{\"foo\":\"bar\"}"


;; Parsing JSON arrays as lists instead of vectors
(define array-as-list-parser
  (cons 'array (lambda (x) x)))

(json-parsers (cons array-as-list-parser (json-parsers)))

(read-json "[1,2,3]") ; => (1 2 3)

  
;; Adding support for writing u8vectors
(import srfi-4 (chicken blob))

(define (u8vector-unparser v)
  (write-json (blob->string (u8vector->blob/shared v))))

(json-unparsers (cons (cons u8vector? u8vector-unparser) (json-unparsers)))

(write-json '((nice . #u8(99 104 105 99 107 101 110 33)))) ; output: {"nice":"chicken!"}

0.1.1: Add consume-trailing-whitespace option
0.1.0: Update to Comparse 0.0.2
0.0.4: First release based on Comparse (previous versions were based on genturfa'i)

License

 Copyright (C) 2011-2013 Moritz Heidkamp
 
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:
     * Redistributions of source code must retain the above copyright
       notice, this list of conditions and the following disclaimer.
     * Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in the
       documentation and/or other materials provided with the distribution.
     * Neither the name of the <organization> nor the
       names of its contributors may be used to endorse or promote products
       derived from this software without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

medea

Description

API

Examples

About this egg

Source

Author

Version history

License