#lang scribble/doc

@require[scribble/manual
         scribble/base
         scribble/eval
         scribble/bnf
         scheme/runtime-path
         (planet cce/scheme:4:1/planet)]

@require[(for-syntax scheme/base)]

@require[(for-label (except-in scheme/base read write)
                    (this-package-in main))]

@define-runtime-path[home (build-path 'same)]

@define[the-eval
        (let ([the-eval (make-base-eval)])
          (parameterize ([current-directory home])
            (the-eval `(require (file ,(path->string (build-path home "main.ss"))))))
          the-eval)]

@title[#:tag "top"]{@bold{JSON}}

by Dave Herman (@tt{dherman at ccs dot neu dot edu})

This library provides utilities for marshalling and unmarshalling data in the JSON data exchange format.
See the @link["http://www.json.org"]{JSON web site} for more information about JSON.

The data structures of this library are immutable.

@defmodule/this-package[]

@table-of-contents[]

This library uses the following Scheme representation of JSON data:

@BNF[
(list @nonterm{json} @BNF-alt[@nonterm{object}
                              @nonterm{array}
                              @nonterm{number}
                              @nonterm{string}
                              @nonterm{boolean}
                              @nonterm{null}])
(list @nonterm{object} @scheme[(hashof symbol? #, @nonterm{json})])
(list @nonterm{array} @scheme[(listof #, @nonterm{json})])
(list @nonterm{number} @BNF-alt[@scheme[integer?] @scheme[inexact-real?]])
(list @nonterm{string} @scheme[string?])
(list @nonterm{boolean} @scheme[boolean?])
(list @nonterm{null} @scheme[void?])]

@defproc[(json? [x any]) boolean?]{
Performs a deep check to determine whether @scheme[x] is a JSON value,
i.e., a Scheme value following the grammar for the @nonterm{json} non-terminal
above.}

@defproc[(read [in input-port? (current-input-port)]) json?]{
Reas a JSON value from input port @scheme[in].}

@defproc[(write [x json?] [out output-port? (current-output-port)]) any]{
Writes the JSON value @scheme[x] to output port @scheme[out].}

@defproc[(json->string [x json?]) string?]{
Generates a JSON source string for the JSON value @scheme[x].}

@defproc[(string->json [s string?]) json?]{
Parses the JSON string @scheme[s] as a JSON value.}

@;examples[#:eval the-eval 42]