tjson

7.7

top ← prev up next →

tjson

1 Introduction

A typed Json parser and emitter.

1.1 Object Mappings

A Json Object is reified as a Racket hashmap, Json array to a Racket list and Strings, Booleans and Numbers mapped to Racket’s types. A special symbol is reserved to indicating a Json null value.

A parsed Json graph follows the naive recursive data structure definition as Json is a string, number, boolean (true or false), list of Json or an object with a multiplicity of unique symbol labeled Json.

(require tjson)

package: tjson

2 Json Parsed Data Structure

value
Json :
(Rec (U String Boolean JsNull Number (Listof Json)
(HashTable Symbol Json)))

A translation of a parsed Json data structure reflectiing it recursive nature.

value
JsObject : (HashTable Symbol Json)

A define-type alias reflecting a Json Object as a hashmap of symbols and Json values.

value
JsList : (Listof Json)

A define-type alias reflecting a Json Array as a Racket List of Json.

value
JsNull : 'JsNull

A Json null value is reflected in Racket as a special reserved symbol. JsNull is a define-type alias for the symbol value at the type level. In Typed Racket each symbol is given a unique type containing only that symbol.

While the type Symbol has all symbols as inhabiting values, the type ’JsNull has only the single inhabiting value ’JsNull.

3 Json Parsing

procedure
(string->json json) → Json
json : String

Parse a string representation of Json into a Typed Racket Json structure.

Examples:

> (string->json "42")
- : Json
42
> (string->json "\"Mary had a little lamb\"")
- : Json
"Mary had a little lamb"
> (string->json "[\"lamb\", \"cat\", \"dog\"]")
- : Json
'("lamb" "cat" "dog")
> (string->json "{\"cat\" : \"meow\", \"dog\" : \"bark\", \"lamb\" : \"bleet\"}")
- : Json
'#hasheq((lamb . "bleet") (dog . "bark") (cat . "meow"))

4 Json Construction

procedure
(jsobject attributes) → JsObject
attributes : (Listof (Pair Symbol Json))

Creates a JsObject instance from a list of symbol and json value associations. Note as a JsObject is just a transparent type alias for a HashMap any of the standard Racket hashmap construction procedures maybe used as well such as (hash ...) or (make-hash ...).

Example:

> (jsobject '((cat . "meow") (dog . "bark") (lamb . "bleet") (turtle . JsNull)))
- : JsObject
'#hasheq((lamb . "bleet") (turtle . JsNull) (dog . "bark") (cat . "meow"))

5 JsObject

5.1 JsObject Attribute Lookup

Lookup an JsObject attribute’s (key) json value.

procedure
(jsattribute? jobj key) → Boolean
jobj : JsObject
key : Symbol

Whether the attribute exists for the jsobject.

procedure
(jsattribute jobj key) → (Option Json)
jobj : JsObject
key : Symbol

Returns the value of the given attribute key if it exists otherwise #f.

Note: For boolean values attributes, given how Option values are implementinted in Typed Racket, the #f return value cannot be used to descriminate between an existing attribute whose value is #f or a missing attribute.

procedure
(jsattribute-orelse jobj key default) → Json
  jobj : JsObject
  key : Symbol
  default : (-> Json)

Returns the json value of the attribute key if it exists otherwise the json returned by the provided thunk.

5.2 JsObject Modification

By design JsObjects are currently implemented as mutable hashmaps and may be mutated. Recall that a JsObject is a type alias for a Racket mutable hashmap. For details concerning concurrent modification see the Racket documantation for hashmaps.

The Racket implemetation of hashmap operations is rich and only a subset are currently wrapped in this library. Additional capabilities such as union, jsobject-union! will added at a later time.

procedure
(jsobject-add! jobj key json) → Void
  jobj : JsObject
  key : Symbol
  json : Json

Adds the attribute to a JsObject overwriting an existing attribute.

procedure
(jsobject-remove! jobj key) → Void
jobj : JsObject
key : Symbol

Removes the attribute from the jsobject if it exists. It is not an error to attempt to remove a non-existing attribute.

procedure
(jsobject-update! jobj key updater) → Void
  jobj : JsObject
  key : Symbol
  updater : (-> Json Json)

Modifies an existing attribute value. A fail:contract exception is thrown if the attribute does not exist.

Examples:

> (define j (jsobject '((cat . "meow"))))
> (jsobject-update! j 'cat (λ (says) (string-append (cast says String) " purr")))
> j
- : JsObject
'#hasheq((cat . "meow purr"))

6 Json Emission

procedure
(json->string json) → String
json : Json

Emit a string representation of a Json data structure.

Example:

> (json->string (jsobject '((cat . "meow") (dog . "bark") (lamb . "bleet") (turtle . JsNull))))
- : String
"{\"dog\": \"bark\", \"cat\": \"meow\", \"turtle\": null, \"lamb\": \"bleet\"}"

7 Port Serialization

procedure
(write-json json outp) → Void
json : Json
outp : Output-Port

Serialize a Json data structure out the provided port as a json string.

procedure
(read-json inp) → Json
inp : Input-Port

Read a json value from the input port.

top ← prev up next →

1	Introduction
2	Json Parsed Data Structure
3	Json Parsing
4	Json Construction
5	Js Object
6	Json Emission
7	Port Serialization