Module B0_sexp.Sexpq

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


type 'a t

The type for s-expression queries. A query either fails or succeeds against a s-expression with a value of type 'a.

val query : 'a t -> Sexp.t -> ('a, string) Stdlib.result

query q s is Ok v if the 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 s-expression.

val fail : string -> 'a t

fail msg is a query that fails on any s-expression 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.

S-expression queries

val fold : atom:'a t -> list:'a t -> 'a t

fold ~atom ~list queries atoms with atom and lists with list.

val sexp : Sexp.t t

sexp queries any s-expression and returns it.

val loc : Sexp.loc t

loc is map Sexp.loc sexp.

val with_loc : 'a t -> ('a * Sexp.loc) t

with_loc q queries with q an returns the result with the location of the s-expression.

Atom queries

These queries fail on lists.

val atom : string t

atom queries an atom as a string.

val enum : kind:string -> B0_std.String.Set.t -> string t

enum ~kind ss queries an atom for one of the element 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 B0_std.String.Map.t -> 'a t

enum_map ~kind sm queries an atom for it's map in sm and fails if the atom is not bound in sm. kind is for the kind of elements in sm, it used for error reporting.

val parsed_atom : kind:string -> (string -> ('a, string) Stdlib.result) -> 'a t

parsed_atom ~kind p queries and atom and parses it with p. In case of Error m fails with message m. kind is the kind of value parsed, used for the error in case a list is found.

val bool : bool t

bool queries an atom for one of true or false.

val int : int t

int queries an atom for an integer value parsed with int_of_string.

val int32 : int32 t

int32 queries an atom for an integer value parsed with Int32.of_string.

val int64 : int64 t

int64 queries an atom for an integer value parsed with Int64.of_string.

val float : float t

float queries an atom for a float value parsed with float_of_string.

val fpath : B0_std.Fpath.t t

fpath queries an atom for a file path value parsed with Fpath.of_string.

List queries

These queries fail on atoms.

val is_empty : bool t

is_empty queries a list for emptyness.

val hd : 'a t -> 'a t

hd q queries the head of a list with q.

val tl : 'a t -> 'a t

tail q queries the tail of a list with q.

val nth : int -> 'a t -> 'a t

nth n q queries the nth element of a list with q. If n is negative counts from the end of the list, so -1 is the last list element.

val fold_list : ('a -> 'b -> 'b) -> 'a t -> 'b -> 'b t

fold_list f q acc queries the elements of a list from left to right with q and folds the result with f starting with acc.

val list : 'a t -> 'a list t

list q queries the elements of a list with q.

Dictionary queries

Queries for s-expression dictionaries. A dictionary is a list of bindings. A binding is a list that starts with an atom key, the remaing elements are the binding's value. For example in this binding:

(key v0 v1 ...)

The key is key and the value the possibly empty list v0, v1, ... of s-expressions. The value is always represented by a fake (doesn't exist syntactically) s-expression list whose location spans the whole binding expression.

val key : string -> 'a t -> 'a t

key k q queries the value of key k of a dictionary with q. The query fails if k is not bound or on atoms.

val opt_key : string -> 'a t -> absent:'a -> 'a t

opt_key k q ~absent queries the value of the optional key k of a dictionary with q and uses absent if k is not bound. The query fails on atoms.

val key_dom : validate:B0_std.String.Set.t option -> B0_std.String.Set.t t

key_dom validate queries the key domain of a list of bindings. If validate is Some dom, the query fails if a key is not in dom. The query also fails if a binding is not well-formed.

XXX Would be nice to provide support for deprecation.

val batom : 'a t -> 'a t

batom q queries a singleton atom list with an atom query q. Useful for singleton dictionary bindings. In error reporting treats the list as if it doesn't exist syntactically which is the case in dictionary bindings.

OCaml datatype encoding queries

val option : 'a t -> 'a option t

option q queries with q the value of an option represented according the encoding of Sexpg.option.