▼Parser Combinator
►3 JSON
On this page:
3.1 JSON Values
string->json
3.2 Grammar
VALUE
NUMBER
STRING
ARRAY
OBJECT
PAIR
SPACE
9.3
    contents    up  next → 

3 JSON🔗

 (require parser-combinator/json)
  package: parser-combinator

This library parses text in the JSON data exchange format into Racket values. See the JSON web site for more about JSON. The library is written entirely with parser-combinator/parse.

3.1 JSON Values🔗

JSON : any/c

A JSON is one of:

An empty JSON array is '() and an empty JSON object is #hasheq(), so every kind of JSON value can be told apart with list?, hash?, and the other predicates above. If a name appears more than once in an object, the last value wins. The order of the names in the text is not kept.

Examples:
; {"a": [1, 2], "b": {}}
> (define obj (string->json "{\"a\": [1, 2], \"b\": {}}"))
> (hash-ref obj 'a)

'(1 2)

> (list-ref (hash-ref obj 'a) 1)

2

procedure

(string->json str) → JSON

  str : string?
parses str as a JSON value, ignoring whitespace around it. It raises exn:fail if str is not valid JSON. It is the same as (parse VALUE str).

Examples:
> (string->json "[]")

'()

> (string->json "-1.5e3")

-1500

; [1, {"foo": false}, null]
> (string->json "[1, {\"foo\": false}, null]")

'(1 #hasheq((foo . #f)) null)

> (string->json "[1, 2")

bad input, got error

Escape sequences in strings are decoded, so \n becomes a newline character. See STRING.

Examples:
; "a\nb"
> (string->json "\"a\\nb\"")

"a\nb"

3.2 Grammar🔗

The grammar behind string->json is made of the parsers below. SPACE matches whitespace, and its Value is the matched text. The rest produce the JSON itself, using seq and seq* constructors: NUMBER, STRING, ARRAY, and OBJECT for those kinds of value, PAIR for one name and value in an object, and VALUE for any JSON value. These parsers are exported so that programs can use them directly.

value

VALUE : Parser

matches any JSON value along with the whitespace around it. It produces 'null, #t, or #f for null, true, and false, or what NUMBER, STRING, ARRAY, or OBJECT produces.

Examples:
> (parse VALUE "  null ")

'null

> (parse VALUE "[1, true]")

'(1 #t)

value

NUMBER : Parser

matches a JSON number: an optional -, then either 0 or a non-zero digit followed by any number of digits, then an optional fraction, then an optional exponent. The fraction is a . followed by one or more digits. The exponent is an e or E, an optional + or -, and one or more digits.

It produces the number as an exact number.

Examples:
> (parse NUMBER "7")

7

> (parse NUMBER "-1.5e2")

-150

> (parse NUMBER "1.")

bad input, had leftover text "."

value

STRING : Parser

matches a JSON string, including its quotes. Inside the quotes it accepts any character other than \, ", and the control characters U+0000 through U+001F. It also accepts the escape sequences \", \\, \/, \b, \f, \n, \r, \t, and \u followed by four hexadecimal digits, in either case.

It produces the text between the quotes as a string, with each escape sequence replaced by the character it stands for. A \u escape names a UTF-16 code unit, so a character outside the Basic Multilingual Plane is written as a surrogate pair, two \u escapes in a row, which together produce one character. A surrogate without its other half produces the replacement character U+FFFD.

Examples:
; "hi"
> (parse STRING "\"hi\"")

"hi"

; "a\tb \u00e9 \uD83D\uDE00"
> (parse STRING "\"a\\tb \\u00e9 \\uD83D\\uDE00\"")

"a\tb é 😀"

; "\uD83D!"
> (parse STRING "\"\\uD83D!\"")

"�!"

; "a b" with a raw tab, which JSON doesn't allow
> (parse STRING "\"a\tb\"")

bad input, got error

value

ARRAY : Parser

matches a JSON array, that is, zero or more VALUEs separated by commas and surrounded by brackets. It produces the list of values, in order.

Example:
> (parse ARRAY "[true, false]")

'(#t #f)

value

OBJECT : Parser

matches a JSON object, that is, zero or more PAIRs separated by commas and surrounded by braces. It produces an immutable hasheq from the name of each PAIR to its value.

Examples:
> (parse OBJECT "{}")

'#hasheq()

; {"a": 1, "b": 2}
> (parse OBJECT "{\"a\": 1, \"b\": 2}")

'#hasheq((a . 1) (b . 2))

value

PAIR : Parser

matches one name and value in a JSON object, such as "name": true, and produces a pair of the name, as a symbol, and the value, as produced by VALUE.

Examples:
; "a": true
> (parse PAIR "\"a\": true")

'(a . #t)

Wherever the grammar allows whitespace around a value or a punctuation mark, the parsers skip an optional SPACE with unwrap.

value

SPACE : Parser

matches one or more whitespace characters: #\space, #\tab, #\newline, and #\return. The Value is the matched text.

Examples:
> ((opt SPACE) " \t\nx")

(result " \t\n" "x")

> ((opt SPACE) "x")

(result '() "x")

    contents    up  next →