package tezt

  1. Overview
  2. Docs

Module Tezt.JSONSource

JSON decoding.

Sourcetype error

Errors that can happen when parsing or reading JSON.

Sourceval show_error : error -> string

Convert a JSON parse error to a string.

Sourceexception Error of error

Exception that can happen when parsing or reading JSON.

JSON unannotated ASTs.

Sourcetype 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).

Sourceval error : t -> ('a, unit, string, 'b) format4 -> 'a

Raise Error.

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

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

Annotate a JSON AST with its origin.

Sourceval unannotate : t -> u

Remove annotation from an annotated JSON AST.

Encoding

Sourceval encode : t -> string

Encode a JSON annotated AST into a string.

Sourceval encode_u : u -> string

Encode a JSON unannotated AST into a string.

Sourceval encode_to_file : string -> t -> unit

Encode a JSON annotated AST into a file.

Sourceval encode_to_file_u : string -> u -> unit

Encode a JSON unannotated AST into a file.

Decoding

Sourceval parse_file : string -> t

Parse a JSON file.

  • raises Error

    if the input is invalid JSON.

Sourceval parse : origin:string -> string -> t

Parse a JSON string.

  • raises Error

    if the input is invalid JSON.

Sourceval 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".

Sourceval 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.

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

Same as get, with the arguments reversed.

Sourceval 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.

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

Same as geti, with the arguments reversed.

Sourceval 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.

Sourceval 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.

Sourceval is_null : t -> bool

Test whether a JSON value is `Null.

Sourceval as_opt : t -> t option

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

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

Sourceval as_bool : t -> bool

Get the value from a `Bool node.

  • raises Error

    if the input is not a `Bool.

Sourceval as_bool_opt : t -> bool option

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

Sourceval is_bool : t -> bool

Test whether as_bool would succeed.

Sourceval 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.
Sourceval as_int_opt : t -> int option

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

Sourceval is_int : t -> bool

Test whether as_int would succeed.

Sourceval 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.
Sourceval as_int64_opt : t -> int64 option

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

Sourceval is_int64 : t -> bool

Test whether as_int64 would succeed.

Sourceval 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.
Sourceval as_float_opt : t -> float option

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

Sourceval is_float : t -> bool

Test whether as_float would succeed.

Sourceval as_string : t -> string

Get the value from a `String node.

  • raises Error

    if the input is not a `String.

Sourceval as_string_opt : t -> string option

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

Sourceval is_string : t -> bool

Test whether as_string would succeed.

Sourceval 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.

Sourceval as_list_opt : t -> t list option

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

Sourceval is_list : t -> bool

Test whether as_list would succeed.

Sourceval 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.

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

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

Sourceval is_object : t -> bool

Test whether as_object would succeed.