tyre 0.1.1 · OCaml Package

Tyre

Typed regular expressions.

type 'a t

A typed regular expression.

The type variable is the type of the returned value when the typed regular expression (tyregex) is executed. tyregexs are bi-directional and can be used both for matching and evaluation. Multiple tyregexs can be combined in order to do routing in similar manner as switches/pattern matching.

Typed regular expressions are strictly as expressive as regular expressions from re (and are, as such, regular expressions, not PCREs). Performances should be exactly the same.

For example tyre : int t can be used to return an int. In the rest of the documentation, we will use tyre to designate a value of type t.

Combinators

val regex : Re.t -> string t

regex re is a tyregex that matches re and return the corresponding string. Groups inside re are erased.

val conv : name:string -> ('a -> 'b option) -> ('b -> 'a) -> 'a t -> 'b t

conv ~name to_ from_ tyre matches the same text as tyre, but converts back and forth to a different data type. For example, this is the implementation of pos_int:

let pos_int = Tyre.conv (try_ int_of_string) string_of_int (Tyre.regex (Re.rep1 Re.digit))

The to_ part of the converter is allowed to fail, by returning None. If it does, exec will return `ConverterFailure (name, s) with s the substring on which the converter was called.

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

opt tyre matches either tyre or the empty string. Similar to Re.opt.

val alt : 'a t -> 'b t -> [ `Left of 'a | `Right of 'b ] t

alt tyreL tyreR matches either tyreL (and will then return `Left v) or tyreR (and will then return `Right v).

Repetitions

type 'a gen = unit -> 'a option

A generator g will return a new value each time it's called, until it returns None. See gen.

val rep : 'a t -> 'a gen t

rep tyre matches tyre zero or more times. Similar to Re.rep.

For matching, rep tyre will matches the string a first time, then tyre will be used to walk the matched part to extract values.

val rep1 : 'a t -> ('a * 'a gen) t

rep1 tyre is seq tyre (rep tyre). Similar to Re.rep1.

Sequences

val seq : 'a t -> 'b t -> ('a * 'b) t

seq tyre1 tyre2 matches tyre1 then tyre2 and return both values.

val prefix : ('b t * 'b) -> 'a t -> 'a t

prefix (tyre_i, s) tyre matches tyre_i, ignores the result, and then matches tyre and returns its result.

s is the witness used for evaluation. It is assumed (but not checked) that tyre_i matches s.

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

prefixstr s tyre matches s then matches tyre and return its value.

It is equal to prefix (regex (Re.str s), s) tyre.

val suffix : 'a t -> ('b t * 'b) -> 'a t

Same as prefix, but reversed.

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

Same as prefixstr, but reversed.

Infix operators

The tyregexs are on sides with an arrow.

val (<?>) : 'a t -> 'b t -> [ `Left of 'a | `Right of 'b ] t

t <?> t' is alt t t'.

val (<*>) : 'a t -> 'b t -> ('a * 'b) t

t <*> t' is seq t t'.

val (*>) : string -> 'a t -> 'a t

s *> t is prefixstr s t.

val (<*) : 'a t -> string -> 'a t

t <* s is suffixstr s t.

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

(ti,s) **> t is prefix (ti,s) t.

val (<**) : 'a t -> ('b t * 'b) -> 'a t

t <** (ti,s) is suffix t (ti,s).

Useful combinators

val int : int t

int matches -?[0-9]+ and returns the matched integer.

Integers that do not fit in an int will fail.

val pos_int : int t

pos_int matches [0-9]+ and returns the matched positive integer.

Integers that do not fit in an int will fail.

val float : float t

float matches -?[0-9]+( .[0-9]* )? and returns the matched floating point number.

Floating point numbers that do not fit in a float returns infinity or neg_infinity.

val bool : bool t

bool matches true|false and returns the matched boolean.

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

list e is similar to rep e, but returns a list.

val terminated_list : sep:string -> 'a t -> 'a list t

terminated_list ~sep tyre is list (tyre <* sep) .

val separated_list : sep:string -> 'a t -> 'a list t

separated_list ~sep tyre is equivalent to opt (e <*> list (sep *> e)).

Other combinators

See Re for details on the semantics of those combinators.

val word : 'a t -> 'a t

val whole_string : 'a t -> 'a t

val longest : 'a t -> 'a t

val shortest : 'a t -> 'a t

val first : 'a t -> 'a t

val greedy : 'a t -> 'a t

val non_greedy : 'a t -> 'a t

val nest : 'a t -> 'a t

Matching

type 'a re

A compiled typed regular expression.

val compile : ?whole:bool -> 'a t -> 'a re

compile tyre is the compiled tyregex representing tyre. if whole is true (the default), the whole string is matched.

type 'a error = [

| `NoMatch of 'a re * string
| `ConverterFailure of string * string

]

val exec : 
  ?pos:int ->
  ?len:int ->
  'a re ->
  string ->
  ('a, 'a error) Result.result

exec ctyre s matches the string s using the compiled tyregex ctyre and returns the extracted value.

Returns Error (`NoMatch (tyre, s) if tyre doesn't match s. Returns Error (`ConverterFailure (name, s)) if the converter named name failed while trying to convert the substring s.

parameter pos
optional beginning of the string (default 0)

parameter len
length of the substring of str that can be matched (default to the end of the string)

val execp : ?pos:int -> ?len:int -> 'a re -> string -> bool

execp ctyre s returns true if ctyre matches s.

parameter pos
optional beginning of the string (default 0)

parameter len
length of the substring of str that can be matched (default to the end of the string)

since 0.1.1

Routing

type +'a route =

| Route : 'x t * ('x -> 'a) -> 'a route
(*
A route is a pair of a tyregex and a handler. When the tyregex is matched, the function is called with the result of the matching.
*)

val (-->) : 'x t -> ('x -> 'a) -> 'a route

tyre --> f is Route (tyre, f).

val route : ?whole:bool -> 'a route list -> 'a re

route [ tyre1 --> f1 ; tyre2 --> f2 ] produces a compiled tyregex such that, if tyre1 matches, f1 is called, and so on. if whole is true (the default), the whole string is matched.

The compiled tyregex shoud be used with exec.

Evaluating

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

eval tyre v returns a string s such that exec (compile tyre) s = v.

Note that such string s is not unique. eval will usually returns a very simple witness.

val evalpp : 'a t -> Stdlib.Format.formatter -> 'a -> unit

evalpp tyre ppf v is equivalent to Format.fprintf ppf "%s" (eval tyre v), but more efficient.

Is is generally used with "%a":

let my_pp = Tyre.evalpp tyre in
Format.printf "%a@." my_pp v

Pretty printing

val pp : Stdlib.Format.formatter -> 'a t -> unit

val pp_re : Stdlib.Format.formatter -> 'a re -> unit

module Internal : sig ... end

Internal types

package tyre