JSON
| (require json) | package: base |
This library provides utilities for parsing and producing data in the JSON data exchange format to/from Racket values. See the JSON web site and the JSON RFC for more information about JSON.
1 JS-Expressions
This library defines a subset of Racket values that can be represented as JSON strings, and this predicates checks for such values. A JS-Expression, or jsexpr, is one of:
the value of jsnull, 'null by default, which is recognized using eq?
> (jsexpr? 'null) #t
> (jsexpr? #t) #t
> (jsexpr? "cheesecake") #t
> (jsexpr? 3.5) #t
> (jsexpr? (list 18 'null #f)) #t
> (jsexpr? #hasheq((turnip . 82))) #t
> (jsexpr? (vector 1 2 3 4)) #f
> (jsexpr? #hasheq(("turnip" . 82))) #f
> (jsexpr? +inf.0) #f
Note that the value of (json-null) (or an explicitly-provided #:null argument) is recognized using eq?.
2 Generating JSON Text from JS-Expressions
procedure
(write-json x [ out #:null jsnull #:encode encode]) → any x : jsexpr? out : output-port? = (current-output-port) jsnull : any/c = (json-null) encode : (or/c 'control 'all) = 'control
By default, only ASCII control characters are encoded as “\uHHHH”. If encode is given as 'all, then in addition to ASCII control characters, non-ASCII characters are encoded as well. This can be useful if you need to transport the text via channels that might not support UTF-8. Note that characters in the range of U+10000 and above are encoded as two \uHHHH escapes, see Section 2.5 of the JSON RFC.
> (with-output-to-string (λ () (write-json #hasheq((waffle . (1 2 3)))))) "{\"waffle\":[1,2,3]}"
> (with-output-to-string (λ () (write-json #hasheq((와플 . (1 2 3))) #:encode 'all))) "{\"\\uc640\\ud50c\":[1,2,3]}"
procedure
(jsexpr->string x [ #:null jsnull #:encode encode]) → string? x : jsexpr? jsnull : any/c = (json-null) encode : (or/c 'control 'all) = 'control
> (jsexpr->string #hasheq((waffle . (1 2 3)))) "{\"waffle\":[1,2,3]}"
procedure
(jsexpr->bytes x [ #:null jsnull #:encode encode]) → bytes? x : jsexpr? jsnull : any/c = (json-null) encode : (or/c 'control 'all) = 'control
> (jsexpr->bytes #hasheq((waffle . (1 2 3)))) #"{\"waffle\":[1,2,3]}"
3 Parsing JSON Text into JS-Expressions
procedure
(read-json [in #:null jsnull]) → (or/c jsexpr? eof-object?)
in : input-port? = (current-input-port) jsnull : any/c = (json-null)
> (with-input-from-string "{\"arr\" : [1, 2, 3, 4]}" (λ () (read-json))) '#hasheq((arr . (1 2 3 4)))
> (with-input-from-string "sandwich sandwich" ; invalid JSON (λ () (read-json))) string::1: read-json: bad input starting #"sandwich
sandwich"
procedure
(string->jsexpr str [#:null jsnull]) → jsexpr?
str : string? jsnull : any/c = (json-null)
> (string->jsexpr "{\"pancake\" : 5, \"waffle\" : 7}") '#hasheq((pancake . 5) (waffle . 7))
procedure
(bytes->jsexpr str [#:null jsnull]) → jsexpr?
str : bytes? jsnull : any/c = (json-null)
> (bytes->jsexpr #"{\"pancake\" : 5, \"waffle\" : 7}") '#hasheq((pancake . 5) (waffle . 7))
4 A Word About Design
4.1 The JS-Expression Data Type
JSON syntactically distinguishes “null”, array literals, and object literals, and therefore there is a question of what Racket value should represent a JSON “null”. This library uses the Racket 'null symbol by default. Note that this is unambiguous, since Racket symbols are used only as object keys, which are required to be strings in JSON.
Several other options have been used by various libaries. For example, Dave Herman’s PLaneT library (which has been the basis for this library) uses the #\nul character, other libraries for Racket and other Lisps use (void), NIL (some use it also for JSON “false”), and more. The approach taken by this library is to use a keyword argument for all functions, with a parameter that determines its default, making it easy to use any value that fits your needs.
The JSON RFC only states that object literal expressions “SHOULD” contain unique keys, but does not proscribe them entirely. Looking at existing practice, it appears that popular JSON libraries parse object literals with duplicate keys by simply picking one of the key-value pairs and discarding the others with the same key. This behavior is naturally paralleled by Racket hash tables, making them a natural analog.
Finally, the JSON RFC is almost completely silent about the order of key-value pairs. While the RFC only specifies the syntax of JSON, which of course always must represent object literals as an ordered collection, the introduction states:
An object is an unordered collection of zero or more name/value pairs, where a name is a string and a value is a string, number, boolean, null, object, or array.
In practice, JSON libraries discard the order of object literals in parsed JSON text and make no guarantees about the order of generated object literals, usually using a hash table of some flavor as a natural choice. We therefore do so as well.
4.2 Naming Conventions
Some names in this library use “jsexpr” and some use “json”. The rationale that the first is used for our representation, and the second is used as information that is received from or sent to the outside world.