tjson

8.12

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((dog . "bark") (cat . "meow") (lamb . "bleet"))

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((dog . "bark") (turtle . JsNull) (cat . "meow") (lamb . "bleet"))

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
"{\"turtle\": null, \"lamb\": \"bleet\", \"cat\": \"meow\", \"dog\": \"bark\"}"

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.

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