Module `Serialk_json.Jsonq`

JSON value queries.

TODO maybe we could expose a bit more options for error reporting. In particular the internal path type and a combinator in the vein of loc to report back the path trace.

Queries

type 'a t: The type JSON value queries. A query either fails or succeeds against a JSON value returning a value of type 'a.

val query : 'a t -> Json.t -> ('a, string) Stdlib.result: query q j is Ok v if que query q succeeds on s and a (multiline) Error e otherwise.

Success and failure

val succeed : 'a -> 'a t: succeed v is a query that succeeds with value v on any JSON value.

val fail : string -> 'a t: fail msg is a query that fails on any JSON value with message msg. Do not include position information in msg, this is automatically handled by the module.

val failf : ('a, Stdlib.Format.formatter, unit, 'b t) Stdlib.format4 -> 'a: failf fmt ... is like fail but formats the message according to fmt.

Query combinators

val app : ('a -> 'b) t -> 'a t -> 'b t: app fq q queries a s-expression first with fq and then with q and applies the result of latter to the former.

val ($) : ('a -> 'b) t -> 'a t -> 'b t: f $ v is app f v.

val bind : 'a t -> ('a -> 'b t) -> 'b t: bind q f queries a s-expression with q, applies the result to f and re-queries the s-expression with the result.

val map : ('a -> 'b) -> 'a t -> 'b t: map f q is app (succeed f) q.

val some : 'a t -> 'a option t: some q is map Option.some q.

JSON queries

val fold : null:'a t -> bool:'a t -> float:'a t -> string:'a t -> array:'a t -> obj:'a t -> 'a t: fold queries JSON values according to their kind using the provided queries.

val json : Json.t t: json queries any JSON value and returns it.

val loc : Json.loc t: locis map Sexp.loc sexp.

val with_loc : 'a t -> ('a * Json.loc) t: with_loc q queries with q and returns the result with the location of the queried JSON value.

Nulls

val is_null : bool t: is_null tests for a JSON null value.

val null : unit t: null queries JSON null as unit and fails otherwise.

val nullable : 'a t -> 'a option t: nullable q queries either a JSON null value or with q.

Atomic values

val bool : bool t: bool queries JSON bool values as a bool value and fails otherwise.

val float : float t: float queries JSON number values as a float value and fails otherwise.

val string : string t: string queries JSON string values as a string value and fails otherwise.

val parsed_string : kind:string -> (string -> ('a, string) Stdlib.result) -> 'a t: parsed_string ~kind parse queries a JSON string and parses it with p. In case of Error m error fails with m. kind is the kind of value parsed, it is used if the value is not a JSON string.

val enum : kind:string -> Stdlib.Set.Make(Stdlib.String).t -> string t: enum ~kind ss queries a JSON string for one of the elements of ss and fails otherwise. kind is for the kind of elements in ss, it used for error reporting.

val enum_map : kind:string -> 'a Stdlib.Map.Make(Stdlib.String).t -> 'a t: enum_map ~kind sm queries a string for it's map in sm and fails if the string is not bound in sm. kind is for the kind elements in sm, it is used for error reporting.

Arrays

These queries only succeed on JSON array values.

val is_empty_array : bool t: is_empty_array queries an array for emptyness.

val hd : 'a t -> 'a t: hd q queries the first element of an array with q. Fails on empty arrays.

val tl : 'a t -> 'a t: tail q queries the tail of an array with q. Fails on empty arrays.

val nth : int -> 'a t -> 'a t: nth n q queries the nth element of an array with q. If n is negative counts from the end of the array, so -1 is the last list element.

val fold_array : ('a -> 'b -> 'b) -> 'a t -> 'b -> 'b t: fold_array f q acc queries the elements of an array from left to right with q and folds the result with f starting with acc.

val array : 'a t -> 'a list t: array q queries the elements of an array with q.

Objects

These queries only succeed on JSON object values.

val mem : string -> 'a t -> 'a t: mem n q queries the member n of a JSON object with q. The query fails if n is unbound in the object.

val opt_mem : string -> 'a t -> absent:'a -> 'a t: opt_mem n q ~absent queries the member n of a JSON object with q. absent is returned if n is unbound in the object.

val mem_dom : validate:Stdlib.Set.Make(Stdlib.String).t option -> Stdlib.Set.Make(Stdlib.String).t t: mem_dom ~validate queries the member domain of a JSON object. If validate is Some dom, the query fails if a member name is not in dom.