json-r7rs/doc/index.sxml

(html (@ (xmlns "http://www.w3.org/1999/xhtml")
         (xml:lang "en"))
(head
 (title "JSON Parser")
 (style (@ (type "text/css"))
 "
  body {
   color: #000000;
   background-color: #d6e6e6;
   margin-top: 1cm;
   margin-left: 1cm;
   line-height: 1.6;
   font-family: sans-serif;
  }
  h1, h2 {
   color: #004646;
  }
  "))
(body
 (h1 "JSON Parser")
 (h2 "(import (macduffie json))")
 (p
  "(macduffie json) is just a simple JSON parser. This library
  is now based on the "
  (a (@ (href "https://github.com/fourthbit/spheres"))
  "SchemeSpheres") " JSON parser, and no longer has any code from
  Dominique Boucher. With this change, the license is now Expat
  (MIT). Furthermore, the parser looks close to standards
  compliant, but there remains a problem with Unicode surrogate
  pairs.")
 (p
  "This library depends on (srfi 69) to represent JSON objects.
  Otherwise, only scheme-small libraries are used.")
 (p
  "This library is regularly tested in Chibi, Kawa, and Gauche (in
  R7RS-strict mode).")

(h2 "Library Procedures")
 (ul (@ (style "list-style: none;"))
  (li (@ (style "margin-bottom: 20px;"))
   (b "(json-read [port])")
   " Reads a JSON file from " (i "port") " and converts it to
   Scheme data. " (i "port") " defaults to (current-input-port).")
  (li (@ (style "margin-bottom: 20px;"))
   (b "(json-write value [port])")
   " Converts " (i "value") " to a JSON file and writes it to "
   (i "port") ". " (i "port") " defaults to (current-output-port).")
  (li (@ (style "margin-bottom: 20px;"))
   (b "(json-read-string str)")
   " Reads a JSON string " (i "str") " and returns the corresponding
   Scheme data.")
  (li (@ (style "margin-bottom: 20px;"))
   (b "(json-read-file filepath)")
   " Reads a JSON file at " (i "filepath") " and returns the
   corresponding Scheme data.")
  (li (@ (style "margin-bottom: 20px;"))
   (b "(json-write-string value [prettify] [space-char space-count])")
   " Writes " (i "value") " to a new JSON string which is returned. "
   (i "prettify") " writes the JSON in pretty-printed form, and defaults
   to #f. " (i "space-char") " and " (i "space-count") " specify the
   indentation for pretty-printing, and default to #\\tab and 1.")
  (li (@ (style "margin-bottom: 20px;"))
   (b "(json-write-file value filepath [prettify] [space-char
   space-count])") " Writes " (i "value") " to a JSON file at "
   (i "filepath") ". The optional arguments are the same as
   json-write-string and have the same defaults.")
  (li (@ (style "margin-bottom: 20px;"))
   (b "(json-null)") " Returns a record of the type json-null, for which
   (eq? (json-null) (json-null)) always returns #t.")
  (li (@ (style "margin-bottom: 20px;"))
   (b "(json-null? v)") " Returns #t if " (i "v") " is a record of
   the type json-null."))

(h2 "To do:")
 (ul
  (li
   "Correctly write Unicode surrogate pairs"))

(h2 "Performance")
 (p
  "This library will not work well for very large files. According
  to my tests, here are the relative performance of Chibi, Kawa,
  and Gauche: ")
 (ul
  (li
   "Kawa was ok with a 1,000-line JSON file. Performance was
   unacceptable for a 5,000-line JSON file.")
  (li
   "Chibi was ok with a 5,000-line JSON file. Performance was
   unacceptable for a 10,000-line JSON file.")
  (li
   "Gauche was ok with a 100,000-line JSON file. Performance
   was unacceptable for a 500,000-line JSON file."))

(h2 "Data types")
 (p
  "Note that keys are internally represented as symbols.")
 (table (@ (border "1")
           (style "width:400")
           (summary "Comparison of JSON vs Scheme data"))
  (tr
   (td (@ (width "200"))
    (b "Scheme"))
   (td (@ (width "200"))
    (b "JSON")))
  (tr
   (td "AList (with symbol keys)")
   (td "Object"))
  (tr
   (td "Vector")
   (td "Array"))
  (tr
   (td "String")
   (td "String"))
  (tr
   (td "Number")
   (td "Number"))
  (tr
   (td "#t")
   (td "true"))
  (tr
   (td "#f")
   (td "false"))
  (tr
   (td "json-null record type")
   (td "null")))))