.\" Automatically generated by Pandoc 2.2.1
.\"
.TH "elvish\-re" "7" "Feb 08, 2019" "Elvish 0.12" "Miscellaneous Information Manual"
.hy
.SH Introduction
.PP
The \f[C]re:\f[] module wraps Go\[aq]s \f[C]regexp\f[] package.
See the doc (http://godoc.org/regexp) for the Go package for syntax of
regular expressions and replacement patterns.
.SH Functions
.PP
Function usages notations follow the same convention as the builtin
module doc (/ref/builtin.html).
.PP
The following options are supported by multiple functions in this
module:
.IP \[bu] 2
\f[C]&posix\f[] (defaults to \f[C]$false\f[]): Use POSIX ERE syntax.
See also doc (http://godoc.org/regexp#CompilePOSIX) in Go package.
.IP \[bu] 2
\f[C]&longest\f[] (defaults to \f[C]$false\f[]): Prefer
leftmost\-longest match.
See also doc (http://godoc.org/regexp#Regexp.Longest) in Go package.
.IP \[bu] 2
\f[C]&max\f[] (defaults to \-1): If non\-negative, maximum number of
results.
.SS find
.IP
.nf
\f[C]
re:find\ &posix=$false\ &longest=$false\ &max=\-1\ $pattern\ $source
\f[]
.fi
.PP
Find all matches of \f[C]$pattern\f[] in \f[C]$source\f[].
.PP
Each match is represented by a map\-like value \f[C]$m\f[];
\f[C]$m[text]\f[], \f[C]$m[start]\f[] and \f[C]$m[end]\f[] are the text,
start and end positions (as byte indicies into \f[C]$source\f[]) of the
match; \f[C]$m[groups]\f[] is a list of submatches for capture groups in
the pattern.
A submatch has a similar structure to a match, except that it does not
have a \f[C]group\f[] key.
The entire pattern is an implicit capture group, and it always appears
first.
.PP
Examples:
.IP
.nf
\f[C]
~>\ re:find\ .\ ab
▶\ [&text=a\ &start=0\ &end=1\ &groups=[[&text=a\ &start=0\ &end=1]]]
▶\ [&text=b\ &start=1\ &end=2\ &groups=[[&text=b\ &start=1\ &end=2]]]
~>\ re:find\ \[aq][A\-Z]([0\-9])\[aq]\ \[aq]A1\ B2\[aq]
▶\ [&text=A1\ &start=0\ &end=2\ &groups=[[&text=A1\ &start=0\ &end=2]\ [&text=1\ &start=1\ &end=2]]]
▶\ [&text=B2\ &start=3\ &end=5\ &groups=[[&text=B2\ &start=3\ &end=5]\ [&text=2\ &start=4\ &end=5]]]
\f[]
.fi
.SS match
.IP
.nf
\f[C]
re:match\ &posix=$false\ $pattern\ $source
\f[]
.fi
.PP
Determine whether \f[C]$pattern\f[] matches \f[C]$source\f[].
The pattern is not anchored.
Examples:
.IP
.nf
\f[C]
~>\ re:match\ .\ xyz
▶\ $true
~>\ re:match\ .\ \[aq]\[aq]
▶\ $false
~>\ re:match\ \[aq][a\-z]\[aq]\ A
▶\ $false
\f[]
.fi
.SS replace
.IP
.nf
\f[C]
re:replace\ &posix=$false\ &longest=$false\ &literal=$false\ $pattern\ $repl\ $source
\f[]
.fi
.PP
Replace all occurrences of \f[C]$pattern\f[] in \f[C]$source\f[] with
\f[C]$repl\f[].
.PP
The replacement \f[C]$repl\f[] can be either
.IP "1." 3
A string\-typed replacement template.
The template can use \f[C]$name\f[] or \f[C]${name}\f[] patterns to
refer to capture groups, where \f[C]name\f[] consists of letters, digits
and underscores.
Numbered patterns like \f[C]$1\f[] refer to capture groups by their
order, while named patterns like \f[C]$stem\f[] refer to capture groups
by their names (specified using the syntax \f[C](?P<name>...)\f[]).
Use \f[C]$$\f[] for a literal dollar sign.
The name is taken as long as possible; for instance, \f[C]$1a\f[] is the
same as \f[C]${1a}\f[].
.RS 4
.PP
See also doc of Go\[aq]s regexp package on the template
syntax (https://godoc.org/regexp#Regexp.Expand).
.RE
.IP "2." 3
A function that takes a string argument and outputs a string.
For each match, the function is called with the content of the match,
and its output is used as the replacement.
.PP
If \f[C]$literal\f[] is true, \f[C]$repl\f[] must be a string and is
treated literally instead of as a pattern.
.PP
Example:
.IP
.nf
\f[C]
~>\ re:replace\ \[aq](ba|z)sh\[aq]\ \[aq]${1}SH\[aq]\ \[aq]bash\ and\ zsh\[aq]
▶\ \[aq]baSH\ and\ zSH\[aq]
~>\ re:replace\ \[aq](ba|z)sh\[aq]\ elvish\ \[aq]bash\ and\ zsh\ rock\[aq]
▶\ \[aq]elvish\ and\ elvish\ rock\[aq]
~>\ re:replace\ \[aq](ba|z)sh\[aq]\ [x]{\ put\ [&bash=BaSh\ &zsh=ZsH][$x]\ }\ \[aq]bash\ and\ zsh\[aq]
▶\ \[aq]BaSh\ and\ ZsH\[aq]
\f[]
.fi
.SS split
.IP
.nf
\f[C]
re:split\ &posix=$false\ &longest=$false\ &max=\-1\ $pattern\ $source
\f[]
.fi
.PP
Split \f[C]$source\f[], using \f[C]$pattern\f[] as separators.
Examples:
.IP
.nf
\f[C]
~>\ re:split\ :\ /usr/sbin:/usr/bin:/bin
▶\ /usr/sbin
▶\ /usr/bin
▶\ /bin
~>\ re:split\ &max=2\ :\ /usr/sbin:/usr/bin:/bin
▶\ /usr/sbin
▶\ /usr/bin:/bin
\f[]
.fi
.SS quote
.IP
.nf
\f[C]
re:quote\ $string
\f[]
.fi
.PP
Quote \f[C]$string\f[].
Examples:
.IP
.nf
\f[C]
~>\ re:quote\ a.txt
▶\ a\\.txt
~>\ re:quote\ \[aq](*)\[aq]
▶\ \[aq]\\(\\*\\)\[aq]
\f[]
.fi