.TH RE2 2
.SH NAME
re2: compile, execute, re, match, matchnext, replace, replaceall, quotemeta, StrPos \- access to regular expression library re2
.SH SYNOPSIS
.EX
include "re2.m";
re2 = load Re2 Re2->PATH;

compile:    fn(e: string, flag: int): (Re, string);
execute:    fn(x: Re, s: string): array of (int,int);

re:         fn(re: string): ref RE;
match:      fn(s: string, re: ref RE): array of string;
matchnext:  fn(sp: ref StrPos, re: ref RE): array of string;
replace:    fn(s: string, re: ref RE, rewrite: string): (string, int);
replaceall: fn(s: string, re: ref RE, rewrite: string): (string, int);
quotemeta:  fn(s: string): string;

StrPos: adt
{
        str: string;
        pos: int;
};

.EE
.SH DESCRIPTION
.PP
Regular expressions are defined by re library
(see 
.BR https://code.google.com/p/re2/wiki/Syntax ).
.PP
.IR regex (2)
compatible interface partially implemented.
You can found documentation for 
.B compile
and 
.B execute
in 
.IR regex (2).
If regular expression compiled by 
.BI compile( re , flag )
will be used in
.B match
or 
.BR matchnext ,
.I flag
will have no effect - capturing parens
substrings always will be returned to user.
.PP
.B re
returns a compiled form of the regular expression given in string
.I re
or raise if there are syntax error in regular expression.
If regular expression compiled by 
.B re
will be used in 
.BR execute ,
it will
work like it was compiled by 
.B compile
with 
.I flag
set to 1.
.PP
.B match
matches the compiled regular expression 
.I re
against
string 
.IR s .
It returns 
.B nil
on no match, otherwise it returns an array of
string with substrings for all capturing parens. If regular expression
contains no capturing parens it returns array with 0 elements. If some
capturing parens match empty string or doesn't match at all (if they are
optional) corresponding array element will be 
.BR nil .
If you need to
distinguish between optional not matching parens and parens matched empty
string you should use 
.BR execute .
Unlike 
.BR execute ,
.B match
doesn't
automatically include substring for overall 
.I re
match in 0 element of
array - if you want this behaviour just add capturing parens around all
regular expression. 
.B match
should be faster than 
.B execute
in case there
no capturing parens in 
.IR re .
.PP
.B matchnext
works in same way as 
.BR match ,
except it start matching regular
expression from position 
.IR se.pos .
On successful match it will advance
.I se.pos
value to the first character beyond the match, otherwise it will
not change 
.I se.pos
- this make it ease to use 
.B matchnext
in while loop
and for trying several regular expression from same position until one of
them match. 
.B WARNING!
Currently 
.I se.pos
contain offset in UTF-8
representation of 
.IR se.str ,
not character number, so only safe values to
initialize 
.B StrPos
or to change it is 0 or any values set by previous
.B matchnext
call - this may change in future.
.PP
.B replace
will replace first match of 
.I re
with 
.I rewrite
and return tuple
.BI ( s1 , is_replaced )
where 
.I s1
modified string, and 
.I is_replaced
true if
.I re
matched and replacement was done. If 
.I re
not match returned 
.I s1
will be same as 
.IR s .
String 
.I rewrite
may contain references to capturing
parens values using \\1, \\2, etc. 
.B replace
will raise if 
.I rewrite
contain \\n but 
.I re
has less capturing parens than n or if there syntax
error in 
.I rewrite
(only numbers and \\ are legal after \\).
.PP
.B replaceall
works in same way as 
.B replace
except it replace all matches
and return tuple 
.BI ( s1 , how_many_replaced ) .
.PP
.B quotemeta
escapes all potentially meaningful regexp characters in 
.I s
and return string which can be safely used inside regexp to match exactly
that string.
.SH EXAMPLES
.EX
match := re2->match("Hello World", re("(?i)hello\\s+(\\w+)"));
if(match != nil)
    sys->print("captured in first parens: %s\n", match[0]);

compiled := re("\\b(\\w+)\\b");
sp := ref StrPos("some text here",0);
while((match = re2->matchnext(sp, compiled)) != nil){
    sys->print("found next word: %s\n", match[0]);
}

.EE
.SH SOURCE
.PP
.B /libinterp/re2.c
.br
.B /libre2wrap/re2wrap.cc
.br
.SH SEE ALSO
.PP
.IR regex (2),
.IR regexp (6)
