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. Basically see Serialk_sexp.

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 pair : 'a t -> 'b t -> ('a * 'b) t: pair q0 q1 queries first with q0 and then with q1 and returns the pair of their result.

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 partial_fold : ?⁠null:'a t -> ?⁠bool:'a t -> ?⁠float:'a t -> ?⁠string:'a t -> ?⁠array:'a t -> ?⁠obj:'a t -> unit -> 'a t: partial_fold is like fold but only queries the kinds that are explicitely specified. It errors on other kinds.

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 is None on JSON null and otherwise queries the value 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 int : int t: int is map truncate float.

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

val string_to : kind:string -> (string -> ('a, string) Stdlib.result) -> 'a t: string_to ~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 for the error in case no JSON string is found.

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

Array index queries

val nth : ?⁠absent:'a -> int -> 'a t -> 'a t: nth ?absent 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 array element. If the element does not exist this fails if absent is None and succeeds with v if absent is Some v.

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.