tezt 3.1.1 · OCaml Package

JSON decoding.

type error

Errors that can happen when parsing or reading JSON.

val show_error : error -> string

Convert a JSON parse error to a string.

exception Error of error

Exception that can happen when parsing or reading JSON.

type u = Ezjsonm.value

JSON unannotated ASTs.

type t

JSON ASTs annotated with their origin.

The origin is a string you give to annotate or parse, such as "RPC response". It denotes where the value comes from. It is used in error messages (see the comment in the Decoding section).

val error : t -> ('a, unit, string, 'b) Stdlib.format4 -> 'a

Raise Error.

The JSON.t argument is used to annotate the error message with the location of the JSON value.

val annotate : origin:string -> u -> t

Annotate a JSON AST with its origin.

val unannotate : t -> u

Remove annotation from an annotated JSON AST.

Encoding

val encode : t -> string

Encode a JSON annotated AST into a string.

val encode_u : u -> string

Encode a JSON unannotated AST into a string.

val encode_to_file : string -> t -> unit

Encode a JSON annotated AST into a file.

val encode_to_file_u : string -> u -> unit

Encode a JSON unannotated AST into a file.

Decoding

val parse_file : string -> t

Parse a JSON file.

raises Error
if the input is invalid JSON.

val parse : origin:string -> string -> t

Parse a JSON string.

raises Error
if the input is invalid JSON.

val parse_opt : origin:string -> string -> t option

Same as parse, but return None instead of raising Error.

The general pattern for the accessors below is that only as_x functions can fail. Getters get and geti return `Null instead of failing. This allows to chain them and only test for errors at the end with as_x, either by raising Error or by returning None (with the as_x_opt variant).

Internally, the actual error which is printed is the correct one. For instance, with json |-> "x" |> as_int, if json is not an object, the call to as_int causes the test to fail with "<origin>: not an object" where <origin> is the ~origin you gave to parse. If json is an object but "x" does not exist, as_int causes the test to fail with "<origin>: missing field: x". If "x" exists but is not an integer, as_int causes the test to fail with "<origin> at .x: expected an integer".

val get : string -> t -> t

Get the value for a field of a JSON object.

If the JSON value is not an object, or if the field does not exist, return `Null.

val (|->) : t -> string -> t

Same as get, with the arguments reversed.

val geti : int -> t -> t

Get the value for a field of a JSON array.

If the JSON value is not an array, or if the field does not exist, return `Null.

val (|=>) : t -> int -> t

Same as geti, with the arguments reversed.

val put : (string * t) -> t -> t

Updates an object with a (key, value) pair.

put (key, value) obj puts value under key in obj. If the key already exists, it is overwritten. Otherwise a new key is added at the end of the object.

raises Error
if obj is not a JSON object.

val update : string -> (t -> t) -> t -> t

Alters the value of a specific key in a JSON object by applying its value to a function. Returns updated object.

update key f obj is equivalent to put (key, f (get key obj)) obj.

Note: if key is not present in obj, `Null is passed to f instead.

raises Error
if obj is not an object.

val filter_map_object : t -> (string -> t -> t option) -> t

filter_map_object obj f maps f over each field in obj.

If f key value is None then the key is removed from obj. If f key value is Some value' then the key is overwritten with value'.

raises Error
if obj is not an object.

val filter_object : t -> (string -> t -> bool) -> t

filter_object obj f filters the bindings in obj.

filter_object obj f removes each binding key, value in obj for which f key value is false.

raises Error
if obj is not an object.

val merge_objects : t -> t -> t

Non-recursively merges two objects.

merge_objects o1 o2 returns an object containing all fields of o1 and o2. If a key exists in both o1 and o2, then it will be bound to its value in o2.

raises Error
if o1 or o2 is not an object.

val is_null : t -> bool

Test whether a JSON value is `Null.

val as_opt : t -> t option

Return None if a JSON value is `Null, Some otherwise.

Example: JSON.(json |> as_opt |> Option.map read_record)

val as_bool : t -> bool

Get the value from a `Bool node.

raises Error
if the input is not a `Bool.

val as_bool_opt : t -> bool option

Same as as_bool, but return None instead of raising Error.

val is_bool : t -> bool

Test whether as_bool would succeed.

val as_int : t -> int

Get the integer value from a `Float or `String node.

raises Error
if:
- the input is not a `Float nor a `String;
- the input is a `Float but is not an integer;
- the input is a `String but does not denote a valid decimal integer.

val as_int_opt : t -> int option

Same as as_int, but return None instead of raising Error.

val is_int : t -> bool

Test whether as_int would succeed.

val as_int64 : t -> int64

Get the integer value from a `Float or `String node (64-bit version).

raises Error
if:
- the input is not a `Float nor a `String;
- the input is a `Float but is not an integer;
- the input is a `String but does not denote a valid decimal integer.

val as_int64_opt : t -> int64 option

Same as as_int64, but return None instead of raising Error.

val is_int64 : t -> bool

Test whether as_int64 would succeed.

val as_int32 : t -> int32

Get the integer value from a `Float or `String node (32-bit version).

raises Error
if:
- the input is not a `Float nor a `String;
- the input is a `Float but is not an integer;
- the input is a `String but does not denote a valid decimal integer.

val as_int32_opt : t -> int32 option

Same as as_int32, but return None instead of raising Error.

val is_int32 : t -> bool

Test whether as_int32 would succeed.

val as_float : t -> float

Get the float value from a `Float or `String node.

raises Error
if:
- the input is not a `Float nor a `String;
- the input is a `String but does not denote a valid decimal float.

val as_float_opt : t -> float option

Same as as_float, but return None instead of raising Error.

val is_float : t -> bool

Test whether as_float would succeed.

val as_string : t -> string

Get the value from a `String node.

raises Error
if the input is not a `String.

val as_string_opt : t -> string option

Same as as_string, but return None instead of raising Error.

val is_string : t -> bool

Test whether as_string would succeed.

val as_list : t -> t list

Get the list of items from an `Array node.

raises Error
if the input is not an `Array nor `Null. Return the empty list if the input is `Null.

val as_list_opt : t -> t list option

Same as as_list, but return None instead of raising Error.

val is_list : t -> bool

Test whether as_list would succeed.

val as_object : t -> (string * t) list

Get the list of fields from an `Object node.

raises Error
if the input is not an `Object nor `Null. Return the empty list if the input is `Null.

val as_object_opt : t -> (string * t) list option

Same as as_object, but return None instead of raising Error.

val is_object : t -> bool

Test whether as_object would succeed.

val equal_u : u -> u -> bool

Equality for JSON unannotated ASTs.

Objects are equal only when they have the exact same number of fields with the same contents (their order does not matter). Consequently, e.g. {"a": 1} is not equal to {"a": 1, "a": 1}.

Arrays are equal when they contain the same number of pair-wise equal elements.

val equal : t -> t -> bool

Equality for JSON annotated ASTs.

Annotations are stripped, then the unannotated AST is compared with equal_u.

package tezt

Encoding

Decoding