tjson
1 Introduction
1.1 Object Mappings
2 Json Parsed Data Structure
3 Json Parsing
4 Json Construction
5 Js  Object
5.1 Js  Object Attribute Lookup
5.2 Js  Object Modification
6 Json Emission
7 Port Serialization
7.1

tjson

Raymond Racine <[email protected]>

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.