Module B0_serialk_sexp.Sexpq

S-expression queries.

Result paths

type path = (Sexp.index * Sexp.loc) list

The type for result paths. This is a sequence of indexing operations tupled with the source text location of the indexed in reverse order.

val pp_path : ?⁠pp_key:(Stdlib.Format.formatter -> string -> unit) -> Stdlib.Format.formatter -> path -> unit

pp_path ~pp_key formats path using pp_key to format the keys.

Queries

type 'a t

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

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 with location information otherwise.

val query' : 'a t -> Sexp.t -> ('apath * Sexp.loc * string) Stdlib.result

query' q s is like query except in the error case it returns Error (p, l, e) with p the query path that leads to the error, l the location of the error and e the error message.

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

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

with_path q queries with q an returns the result with the query path and source text location to the queried s-expression.

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 its generic representation.

Atom queries

All these queries fail on lists.

val atom : string t

atom queries an atom as a string.

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 enum : kind:string -> Stdlib.Set.Make(Stdlib.String).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 Stdlib.Map.Make(Stdlib.String).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 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.

List queries

All 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. Fails on empty lists.

val tl : 'a t -> 'a t

tail q queries the tail of a list with q. Fails on empty lists.

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.

List index queries

val nth : ?⁠absent:'a -> int -> 'a t -> 'a t

nth ?absent n q queries the nth index of a list with q. If n is negative counts from the end of the list, so -1 is the last list element. If the element does not exist this fails if absent is None and succeeds with v if absent is Some v.

val delete_nth : must_exist:bool -> int -> Sexp.t t

delete_nth ~must_exist n deletes the nth element of the list. If the element does not exist this fails when must_exist is true or returns the list unchanged when must_exist is false.

Dictionary queries

Queries for s-expression dictionaries. These queries fail on atoms.

val key : ?⁠absent:'a -> string -> 'a t -> 'a t

key ?absent k q queries the value of key k of a dictionary with q. If k is not bound this fails if absent is None and succeeds with v if absent is Some v.

val delete_key : must_exist:bool -> string -> Sexp.t t

delete_key ~must_exist k deletes key k from the dictionary. If k is not bound this fails when must_exist is true or returns the dictionary unchanged when must_exist is false.

val key_dom : validate:Stdlib.Set.Make(Stdlib.String).t option -> Stdlib.Set.Make(Stdlib.String).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 lone_atom : 'a t -> 'a t

lone_atom q queries an atom or the atom of a singleton list with q. It fails on empty lists or non-singleton lists.

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

Index queries

val index : ?⁠absent:'a -> Sexp.index -> 'a t -> 'a t

index ?absent i q queries the s-expression index i with q using nth or key according to i. Fails on atoms.

val delete_index : must_exist:bool -> Sexp.index -> Sexp.t t

delete_index ~must_exist i deletes the s-expression index i using delete_nth or delete_key according to i.

Path and caret queries

These queries fail on indexing errors, that is if an atom gets indexed.

val path : ?⁠absent:'a -> Sexp.path -> 'a t -> 'a t

path p q queries the s-expression found by p using q. If p can't be found this fails if absent is None and succeeds with v if absent is Some v.

val probe_path : Sexp.path -> (path * Sexp.t * Sexp.path) t

probe_path p is a query that probes for p's existence. Except for indexing errors it always succeeds with (sp, s, rem):

  • If p is found, this is the path to sp to the found expression s and rem is empty.
  • If p is not found, this is the path sp that leads to the s-expression s that could not be indexed and rem has the indexes that could not be performed.
val delete_at_path : must_exist:bool -> Sexp.path -> Sexp.t t

delete_at_path ~must_exist p deletes the s-expression found by p from the queried s-expression. If the path does not exist this fails if must_exist is true and returns the s-expression itself if must_exist is false.

val splice_at_path : ?⁠stub:Sexp.t -> must_exist:bool -> Sexp.path -> rep:Sexp.t -> Sexp.t t

splice_at_path ?stub ~must_exist p ~rep replaces the s-expression found at p by splicing rep. If the path does not exist this fails if must_exist is true and the non-existing part of the path is created if must_exist is false. If elements need to be created stub (defaults to Sexp.atom "" is used.

val splice_at_caret : ?⁠stub:Sexp.t -> must_exist:bool -> Sexp.caret -> rep:Sexp.t -> Sexp.t t

splice_caret ?stub ~must_exist p rep splices the s-expression rep at the caret p of the s-expression. If path of the caret does not exist this fails if must_exist is true and the non-existing part of the path is created if must_exist is false. If elements need to be create stub (defaults to Sexp.atom "" is used.

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.