Module Regex

module Regex: sig .. end

> RE2 is a fast, safe, thread-friendly alternative to backtracking regular expression > engines like those used in PCRE, Perl, and Python. It is a C++ library.

> Unlike most automata-based engines, RE2 implements almost all the common Perl and > PCRE features and syntactic sugars. It also finds the leftmost-first match, the same > match that Perl would, and can return submatch information. The one significant > exception is that RE2 drops support for backreferences¹ and generalized zero-width > assertions, because they cannot be implemented efficiently. The syntax page gives > full details.

Syntax reference: http://code.google.com/p/re2/wiki/Syntax *

Although OCaml strings may legally have internal null bytes, it is expensive to check for them, so this library just assumes that it will never see such a string. The failure mode is the search stops early, which isn't bad considering how rare internal null bytes are in practice.

Basic Types

type t 

type regex = t 

type id_t = [ `Index of int | `Name of string ] 

val index_of_id_exn : t -> id_t -> int

Subpatterns are indexed by the number of opening parentheses preceding them:

~sub:(`Index 0) : only the whole match ~sub:(`Index 1) : the whole match and the first submatch, etc.

If you only care whether the pattern does match, you can request no location information at all by passing ~sub:(`Index -1).

With one exception, I quote from re2.h:443,

> Don't ask for more match information than you will use: > runs much faster with nmatch == 1 than nmatch > 1, and > runs even faster if nmatch == 0.

For sub > 1, re2 executes in three steps: 1. run a DFA over the entire input to get the end of the whole match 2. run a DFA backward from the end position to get the start position 3. run an NFA from the match start to match end to extract submatches sub == 1 lets it stop after (2) and sub == 0 lets it stop after (1). (See re2.cc:692 or so.)

The one exception is for the functions get_matches, replace, and Iterator.next: Since they must iterate correctly through the whole string, they need at least the whole match (subpattern 0). These functions will silently rewrite ~sub to be non-negative.

module Options: Options.S 

val create : ?options:Options.t list -> string -> t Core.Std.Or_error.t

val create_exn : ?options:Options.t list -> string -> t

include Stringable

val num_submatches : t -> int

val pattern : t -> string

val find_all : ?sub:id_t -> t -> string -> string list Core.Std.Or_error.t

val find_all_exn : ?sub:id_t -> t -> string -> string list

val find_first : ?sub:id_t -> t -> string -> string Core.Std.Or_error.t

val find_first_exn : ?sub:id_t -> t -> string -> string

val find_submatches : t -> string -> string option array Core.Std.Or_error.t

val find_submatches_exn : t -> string -> string option array

val matches : t -> string -> bool

val split : ?max:int -> ?include_matches:bool -> t -> string -> string list

val rewrite : t -> template:string -> string -> string Core.Std.Or_error.t

val rewrite_exn : t -> template:string -> string -> string

val valid_rewrite_template : t -> template:string -> bool

val escape : string -> string

Infix Operators

module Infix: sig .. end

Complicated Interface

module Match: sig .. end

val get_matches : ?sub:id_t ->
       ?max:int -> t -> string -> Match.t list Core.Std.Or_error.t

val get_matches_exn : ?sub:id_t -> ?max:int -> t -> string -> Match.t list

val replace : ?sub:id_t ->
       ?only:int ->
       f:(Match.t -> string) ->
       t -> string -> string Core.Std.Or_error.t

val replace_exn : ?sub:id_t ->
       ?only:int -> f:(Match.t -> string) -> t -> string -> string

module Exceptions: sig .. end

val t_of_sexp : Sexplib.Sexp.t -> t

val sexp_of_t : t -> Sexplib.Sexp.t

val compare : t -> t -> int

val bin_t : t Bin_prot.Type_class.t

val bin_read_t : t Bin_prot.Read_ml.reader

val bin_read_t_ : t Bin_prot.Unsafe_read_c.reader

val bin_read_t__ : (int -> t) Bin_prot.Unsafe_read_c.reader

val bin_reader_t : t Bin_prot.Type_class.reader

val bin_size_t : t Bin_prot.Size.sizer

val bin_write_t : t Bin_prot.Write_ml.writer

val bin_write_t_ : t Bin_prot.Unsafe_write_c.writer

val bin_writer_t : t Bin_prot.Type_class.writer

Subpatterns are indexed by the number of opening parentheses preceding them:

~sub:(`Index 0) : only the whole match ~sub:(`Index 1) : the whole match and the first submatch, etc.

If you only care whether the pattern does match, you can request no location information at all by passing ~sub:(`Index -1).

With one exception, I quote from re2.h:443,

> Don't ask for more match information than you will use: > runs much faster with nmatch == 1 than nmatch > 1, and > runs even faster if nmatch == 0.

For sub > 1, re2 executes in three steps: 1. run a DFA over the entire input to get the end of the whole match 2. run a DFA backward from the end position to get the start position 3. run an NFA from the match start to match end to extract submatches sub == 1 lets it stop after (2) and sub == 0 lets it stop after (1). (See re2.cc:692 or so.)

The one exception is for the functions get_matches, replace, and Iterator.next: Since they must iterate correctly through the whole string, they need at least the whole match (subpattern 0). These functions will silently rewrite ~sub to be non-negative.

num_submatches t returns 1 + the number of open-parens in the pattern.

N.B. num_submatches t == 1 + RE2::NumberOfCapturingGroups() because RE2::NumberOfCapturingGroups() ignores the whole match ("subpattern zero").

pattern t returns the pattern from which the regex was constructed. *

find_all t input a convenience function that returns all non-overlapping matches of t against input, in left-to-right order.

If sub is given, and the requested subpattern did not capture, then no match is returned at that position even if other parts of the regex did match.

find_first ?sub pattern input a convenience function around find_all that returns the first match only

find_submatches t input finds the first match and returns all submatches. Element 0 is the whole match and element 1 is the first parenthesized submatch, etc.

matches pattern input

split pattern input

rewrite pattern ~template input is a convenience function for replace: Instead of requiring an arbitrary transformation as a function, it accepts a template string with zero or more substrings of the form "\\n", each of which will be replaced by submatch n. For every match of pattern against input, the template will be specialized and then substituted for the matched substring.

valid_rewrite_template pattern ~template

escape nonregex

Infix Operators

Complicated Interface