Module Bos.Pat

module Pat: sig .. end
Named string patterns.

Named string patterns are strings with variables of the form "$(VAR)" where VAR is any (possibly empty) sequence of bytes except ')' or ','. In a named string pattern a "$" literal must be escaped by "$$".

Named string patterns can be used to format strings or to match data.


type t 
The type for patterns.
val v : string -> t
v s is a pattern from the string s.
Raises Invalid_argument if s is not a valid pattern. Use Bos.Pat.of_string to deal with errors.
val empty : t
empty is an empty pattern.
val dom : t -> Astring.String.Set.t
dom p is the set of variables in p.
val equal : t -> t -> bool
equal p p' is p = p'.
val compare : t -> t -> int
compare p p' is p p'.
val of_string : string -> (t, [> Rresult.R.msg ]) Result.result
of_string s parses s according to the pattern syntax (i.e. a literal '$' must be represented by "$$" in s).
val to_string : t -> string
to_string p converts p to a string according to the pattern syntax (i.e. a literal '$' will be represented by "$$").
val pp : Format.formatter -> t -> unit
pp ppf p prints p on ppf according to the pattern syntax.
val dump : Format.formatter -> t -> unit
dump ppf p prints p as a syntactically valid OCaml string on ppf.


Note. Substitution replaces variables with data, i.e. strings. It cannot substitute variables with variables.

type defs = string Astring.String.Map.t 
Type type for variable definitions. Maps pattern variable names to strings.
val subst : ?undef:(string -> string option) -> defs -> t -> t
subst ~undef defs p tries to substitute variables in p by their value. First a value is looked up in defs and if not found in undef. undef defaults to (fun _ -> None).
val format : ?undef:(string -> string) -> defs -> t -> string
format ~undef defs p substitutes all variables in p with data. First a value is looked up in defs and if not found in undef (defaults to fun _ -> ""). The resulting string is not in pattern syntax (i.e. a literal '$' is represented by '$' in the result).


Pattern variables greedily match from zero to more bytes from left to right. This is .* in regexp speak.

val matches : t -> string -> bool
matches p s is true iff the string s matches p. Here are a few examples:
val query : ?init:defs -> t -> string -> defs option
query ~init p s is like Bos.Pat.matches except that a matching string returns a map from each pattern variable to its matched part in the string (mappings are added to init, defaults to String.Map.empty) or None if s doesn't match p. If a variable appears more than once in pat the first match is returned in the map.