JSON module for Guile
Clone or download
Latest commit f0ada50 Aug 24, 2018

README.org

guile-json

guile-json is a JSON module for Guile. It supports parsing and building JSON documents according to the http://json.org specification.

  • Complies with http://json.org specification.
  • Builds JSON documents programmatically using scheme data types.
  • Allows JSON pretty printing.

Installation

Download the latest tarball and untar it:

If you are cloning the repository make sure you run this first:

$ autoreconf -vif

Then, run the typical sequence:

$ ./configure --prefix=<guile-prefix>
$ make
$ sudo make install

Where <guile-prefix> should preferably be the same as your system Guile installation directory (e.g. /usr).

If everything installed successfully you should be up and running:

$ guile
scheme@(guile-user)> (use-modules (json))
scheme@(guile-user)> (scm->json '(1 2 3))
[1, 2, 3]

It might be that you installed guile-json somewhere differently than your system’s Guile. If so, you need to indicate Guile where to find guile-json, for example:

$ GUILE_LOAD_PATH=/usr/local/share/guile/site guile

A pkg-list.scm file is also provided for users of the Guildhall/Dorodango packaging system.

Usage

guile-json provides a few procedures to parse and build a JSON document. A JSON document is transformed into or from native Guile values according to the following table:

JSONGuile
stringstring
numbernumber
objecthash-table*
arraylist
true#t
false#f
null#nil

Note (*): Association lists are also tranformed to JSON objects, in this case ordered will be preserved.

To start using guile-json procedures and macros you first need to load the module:

scheme@(guile-user)> (use-modules (json))

Procedures

  • (json->scm #:optional port) : Reads a JSON document from the given port, or from the current input port if none is given.
    • port : is optional, it defaults to the current input port.
  • (json-string->scm str) : Reads a JSON document from the given string.
  • (scm->json native #:optional port #:key escape pretty) : Creates a JSON document from the given native Guile value. The JSON document is written into the given port, or to the current output port if non is given.
    • port : it defaults to the current output port.
    • escape : if true, the slash (/ solidus) character will be escaped.
    • pretty : if true, the JSON document will be pretty printed.
  • (scm->json-string native #:key escape pretty) : Creates a JSON document from the given native Guile value into a string.
    • escape : if true, the slash (/ solidus) character will be escaped.
    • pretty : if true, the JSON document will be pretty printed.

Exceptions

A json-invalid exception is thrown if an error is found during the JSON parsing. Since version 0.2.0, the json-invalid exception has a single parser argument (see predicate and accessors below). The line or column where the error occured can be easily obtained from the parser port (calling port-line or port-column on the port).

  • (json-parser? parser) : Tells whether the given argument is a JSON parser record type.
  • (json-parser-port parser) : Get the port that the parser was reading from.

Examples

  • Build the string “hello world”:
    scheme@(guile-user)> (scm->json "hello world ")
    "hello world"
        
  • Build the [1, 2, 3] array:
    scheme@(guile-user)> (scm->json '(1 2 3))
    [1, 2, 3]
        
  • Build the [1, 2, 3, 4] array using unquote-splicing:
    scheme@(guile-user)> (define values '(2 3))
    scheme@(guile-user)> (scm->json `(1 ,@values 4))
    [1, 2, 3, 4]
        
  • Build the object { “project” : “foo”, “author” : “bar” } using an association list (see how symbols can also be used):
    scheme@(guile-user)> (scm->json '(("project" . "foo") (author . bar)))
    {"project" : "foo","author" : "bar"}
        
  • Build again the same object { “project” : “foo”, “author” : “bar” } using a hash table:
    scheme@(guile-user)> (scm->json (alist->hash-table '((project . foo) (author . bar))))
    {"project" : "foo","author" : "bar"}
        
  • Build the object { “values” : [ 234, 98.56 ] }:
    scheme@(guile-user)> (scm->json '(("values" 234 98.56)))
    {"values" : [234, 98.56]}
        
  • Build the object { “values” : [ 234, 98.56 ] } again, this time using a variable:
    scheme@(guile-user)> (define values '(234 98.56))
    scheme@(guile-user)> (scm->json `(("values" ,@values)))
    {"values" : [234, 98.56]}
        

License

Copyright (C) 2013-2018 Aleix Conchillo Flaque <aconchillo@gmail.com>

guile-json is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

guile-json is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with guile-json. If not, see https://www.gnu.org/licenses/.