Module Json_type.Browse

module Browse: sig .. end

This submodule provides some simple functions for checking and reading the structure of JSON data.

Use open Json_type.Browse when you want to convert JSON data into another OCaml type.

val make_table : (string * Json_type.t) list -> (string, Json_type.t) Hashtbl.t

make_table creates a hash table from the contents of a JSON Object. For example, if x is a JSON Object, then the corresponding table can be created by let tbl = make_table (objekt x).

Hash tables are more efficient than lists if several fields must be extracted and converted into something like an OCaml record.

The key/value pairs are added from left to right. Therefore if there are several bindings for the same key, the latest to appear in the list will be the first in the list returned by Hashtbl.find_all.

val field : (string, Json_type.t) Hashtbl.t -> string -> Json_type.t

field tbl key looks for a unique field key in hash table tbl. It raises a Json_error if key is not found in the table or if it is present multiple times.

val fieldx : (string, Json_type.t) Hashtbl.t -> string -> Json_type.t

fieldx tbl key works like field tbl key, but returns Null if key is not found in the table. This function is convenient when assuming that a field which is set to Null is the same as if it were not defined.

For instance, optional int (fieldx tbl "year") looks in table tbl for a field "year". If this field is set to Null or if it is undefined, then None is returned, otherwise an Int is expected and returned, for example as Some 2006. If the value is of another JSON type than Int or Null, it causes an error.

val optfield : (string, Json_type.t) Hashtbl.t -> string -> Json_type.t option

optfield tbl key queries hash table tbl for zero or one field key. The result is returned as None or Some result. If there are several fields with the same key, then a Json_error is produced.

Null is returned as Some Null, not as None. For other behaviors see Json_type.Browse.fieldx and Json_type.Browse.optfieldx.

val optfieldx : (string, Json_type.t) Hashtbl.t -> string -> Json_type.t option

optfieldx is the same as optfield except that it will never return Some Null but None instead.

val describe : Json_type.t -> string

describe x returns a short description of the given JSON data. Its purpose is to help build error messages.

val type_mismatch : string -> Json_type.t -> 'a

type_mismatch expected x raises the Json_error msg exception, where msg is a message that describes the error as a type mismatch between the element x and what is expected.

val is_null : Json_type.t -> bool

tells whether the given JSON element is null

val is_defined : Json_type.t -> bool

tells whether the given JSON element is not null

val null : Json_type.t -> unit

raises a Json_error exception if the given JSON value is not Null.

val string : Json_type.t -> string

reads a JSON element as a string or raises a Json_error exception.

val bool : Json_type.t -> bool

reads a JSON element as a bool or raises a Json_error exception.

val number : Json_type.t -> float

reads a JSON element as an int or a float and returns a float or raises a Json_error exception.

val int : Json_type.t -> int

reads a JSON element as an int or raises a Json_error exception.

val float : Json_type.t -> float

reads a JSON element as a float or raises a Json_error exception.

val array : Json_type.t -> Json_type.t list

reads a JSON element as a JSON Array and returns an OCaml list, or raises a Json_error exception.

val objekt : Json_type.t -> (string * Json_type.t) list

reads a JSON element as a JSON Object and returns an OCaml list, or raises a Json_error exception.

Note the unusual spelling. object being a keyword in OCaml, we use objekt. Object with a capital is still spelled Object.

val list : (Json_type.t -> 'a) -> Json_type.t -> 'a list

list f x maps a JSON Array x to an OCaml list, converting each element of list x using f. A Json_error exception is raised if the given element is not a JSON Array.

For example, converting a JSON array that must contain only ints is performed using list int x. Similarly, a list of lists of ints can be obtained using list (list int) x.

val option : Json_type.t -> Json_type.t option

option x returns None is x is Null and Some x otherwise.

val optional : (Json_type.t -> 'a) -> Json_type.t -> 'a option

optional f x maps x using the given function f and returns Some result, unless x is Null in which case it returns None.

For example, optional int x may return something like Some 123 or None or raise a Json_error exception in case x is neither Null nor an Int.