Module Bos.Pat

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.

Patterns

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 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 Stdlib.compare p p'.

val of_string : string -> (t, [> Rresult.R.msg ]) Rresult.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 : Stdlib.Format.formatter -> t -> unit

pp ppf p prints p on ppf according to the pattern syntax.

val dump : Stdlib.Format.formatter -> t -> unit

dump ppf p prints p as a syntactically valid OCaml string on ppf.

Substitution

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

Matching

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:

  • matches (v "$(mod).mli") "string.mli" is true.
  • matches (v "$(mod).mli") "string.mli " is false.
  • matches (v "$(mod).mli") ".mli" is true.
  • matches (v "$(mod).$(suff)") "string.mli" is true.
  • matches (v "$(mod).$(suff)") "string.mli " is true.
val query : ?init:defs -> t -> string -> defs option

query ~init p s is like 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.