JSON

is a JSON data type, parser, and serializer for Carp.

Installation

(load "git@github.com:carpentry-org/json@0.4.0")

Usage

; Parse JSON
(match (JSON.parse "{\"name\": \"carp\"}")
  (Result.Success j) (println* &j)
  (Result.Error e) (IO.errorln &(JSON.parse-error-str &e)))

; Build JSON
(def j (JSON.obj [(JSON.entry @"name" (JSON.Str @"carp"))
                  (JSON.entry @"version" (JSON.Num 1.0))]))

; Access values
(JSON.get &j "name") ; => (Maybe.Just (JSON.Str "carp"))

; Convert native values via to-json
(to-json @"hello") ; => (JSON.Str "hello")

Arr

instantiate

(Fn [(Array (Box JSON))] JSON)

creates a Arr.

Bool

instantiate

(Fn [Bool] JSON)

creates a Bool.

Null

instantiate

(Fn [] JSON)

creates a Null.

Num

instantiate

(Fn [Double] JSON)

creates a Num.

Obj

instantiate

(Fn [(Map String (Box JSON))] JSON)

creates a Obj.

ParseError

module

Module

wraps a ParseErrorKind together with the byte position in the input where the error was detected.

ParseErrorKind

module

Module

describes the cause of a parse failure.

The associated ParseError carries this together with the byte position where the error was detected.

SerializeError

module

Module

describes the cause of a serialization failure.

NonFiniteNumber is emitted when a JSON.Num contains NaN or infinity, neither of which is representable in JSON.

Str

instantiate

(Fn [String] JSON)

creates a Str.

arr?

defn

(Fn [(Ref JSON a)] Bool) 

                        (arr? j)

checks whether a JSON value is an array.

as-arr

defn

(Fn [(Ref JSON a)] (Maybe (Array (Box JSON)))) 

                        (as-arr j)

extracts a copy of the array value, or Nothing.

as-bool

defn

(Fn [(Ref JSON a)] (Maybe Bool)) 

                        (as-bool j)

extracts the boolean value, or Nothing if not a bool.

as-num

defn

(Fn [(Ref JSON a)] (Maybe Double)) 

                        (as-num j)

extracts the numeric value, or Nothing if not a number.

as-obj

defn

(Fn [(Ref JSON a)] (Maybe (Map String (Box JSON)))) 

                        (as-obj j)

extracts a copy of the object map, or Nothing.

as-str

defn

(Fn [(Ref JSON a)] (Maybe String)) 

                        (as-str j)

extracts a copy of the string value, or Nothing.

bool?

defn

(Fn [(Ref JSON a)] Bool) 

                        (bool? j)

checks whether a JSON value is a boolean.

copy

instantiate

(Fn [(Ref JSON a)] JSON)

copies a JSON.

delete

instantiate

(Fn [JSON] ())

deletes a JSON. This should usually not be called manually.

delete-key

defn

(Fn [JSON, (Ref String a)] JSON) 

                        (delete-key j k)

removes a key from a JSON object. If the value is not an object or the key is absent, returns it unchanged.

entry

defn

(Fn [a, b] (Pair a (Box b))) 

                        (entry k v)

creates a key-value pair for use with obj. The value is automatically boxed.

get

defn

(Fn [(Ref JSON a), (Ref String a)] (Maybe JSON)) 

                        (get j k)

looks up a key in a JSON object. Returns Nothing if the value is not an object or the key is absent. Returns a copy of the value.

get-in

defn

(Fn [(Ref JSON a), (Ref (Array String) b)] (Maybe JSON)) 

                        (get-in j keys)

performs nested lookup through objects and arrays. String path elements that parse as non-negative integers index into arrays; all other elements are used as object keys. Returns a copy.

(JSON.get-in &j &[@"data" @"users" @"0" @"name"])

get-tag

instantiate

(Fn [(Ref JSON a)] Int)

Gets the tag from a JSON.

nth

defn

(Fn [(Ref JSON a), Int] (Maybe JSON)) 

                        (nth j i)

indexes into a JSON array. Returns Nothing if the value is not an array or the index is out of bounds. Returns a copy of the value.

null?

defn

(Fn [(Ref JSON a)] Bool) 

                        (null? j)

checks whether a JSON value is null.

num?

defn

(Fn [(Ref JSON a)] Bool) 

                        (num? j)

checks whether a JSON value is a number.

obj

defn

(Fn [(Array (Pair String (Box JSON)))] JSON) 

                        (obj entries)

builds a JSON object from an array of key-value pairs.

(JSON.obj [(JSON.entry @"a" (JSON.Num 1.0)) (JSON.entry @"b" (JSON.Bool true))])

obj?

defn

(Fn [(Ref JSON a)] Bool) 

                        (obj? j)

checks whether a JSON value is an object.

parse

defn

(Fn [(Ref String a)] (Result JSON JSON.ParseError)) 

                        (parse s)

parses a JSON value from a string.

Returns a (Result JSON ParseError) -- a Success with the parsed value, or an Error carrying the failure kind and the byte position where it was detected. Use JSON.parse-error-str to format the error for display.

parse-error-kind-str

defn

(Fn [(Ref JSON.ParseErrorKind a)] String) 

                        (parse-error-kind-str k)

formats a ParseErrorKind as a human-readable message, without position information.

parse-error-str

defn

(Fn [(Ref JSON.ParseError a)] String) 

                        (parse-error-str e)

formats a ParseError as a human-readable message including the byte position where the error was detected.

pretty-str

defn

(Fn [(Ref JSON a), Int] (Result String JSON.SerializeError)) 

                        (pretty-str j indent)

serializes a JSON value to a human-readable indented string.

The indent parameter specifies the number of spaces per indentation level. Returns a (Result String SerializeError). Errors are returned only when a JSON.Num contains NaN or infinity.

prn

instantiate

(Fn [(Ref JSON a)] String)

converts a JSON to a string.

push

defn

(Fn [JSON, JSON] JSON) 

                        (push j v)

appends a value to a JSON array. If the value is not an array, returns it unchanged.

serialize-error-str

defn

(Fn [(Ref JSON.SerializeError a)] String) 

                        (serialize-error-str e)

formats a SerializeError as a human-readable message.

set-in

defn

(Fn [JSON, (Ref (Array String) a), JSON] JSON) 

                        (set-in j keys v)

sets a value at a nested path through objects and arrays.

Path elements that parse as non-negative integers index into arrays; all other elements are used as object keys. Missing intermediate object keys are created automatically.

(JSON.set-in j &[@"users" @"0" @"name"] (JSON.Str @"Alice"))

set-key

defn

(Fn [JSON, (Ref String a), JSON] JSON) 

                        (set-key j k v)

sets a key in a JSON object, replacing any existing value. If the value is not an object, returns it unchanged.

set-nth

defn

(Fn [JSON, Int, JSON] JSON) 

                        (set-nth j i v)

replaces the value at index i in a JSON array. If the value is not an array or the index is out of bounds, returns it unchanged.

str

defn

(Fn [(Ref JSON a)] (Result String JSON.SerializeError)) 

                        (str j)

serializes a JSON value to its string representation.

Returns a (Result String SerializeError). Errors are returned only when a JSON.Num contains NaN or infinity, neither of which is representable in JSON.

Produces compact output with no extra whitespace.

str?

defn

(Fn [(Ref JSON a)] Bool) 

                        (str? j)

checks whether a JSON value is a string.

update-in

defn

(Fn [JSON, (Ref (Array String) a), (Fn [JSON] JSON b)] JSON) 

                        (update-in j keys f)

applies a function to the value at a nested path.

Path elements that parse as non-negative integers index into arrays. If the path does not resolve to a value, returns the input unchanged.

(JSON.update-in j &[@"count"] (fn [n] (match (JSON.as-num &n) (Maybe.Just x) (JSON.Num (+ x 1.0)) (Maybe.Nothing) n)))