.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "elvish-re" "7" "Dec 07, 2021" "Elvish 0.17.0~rc4" "Miscellaneous Information Manual"
.hy
.PP
.SH Introduction
.PP
The \f[C]re:\f[R] module wraps Go\[cq]s \f[C]regexp\f[R] package.
See the Go\[cq]s doc for supported regular expression
syntax (https://godoc.org/regexp/syntax).
.PP
Function usages notations follow the same convention as the builtin
module doc.
.PP
The following options are supported by multiple functions in this
module:
.IP \[bu] 2
\f[C]&posix=$false\f[R]: Use POSIX ERE syntax.
See also doc (http://godoc.org/regexp#CompilePOSIX) in Go package.
.IP \[bu] 2
\f[C]&longest=$false\f[R]: Prefer leftmost-longest match.
See also doc (http://godoc.org/regexp#Regexp.Longest) in Go package.
.IP \[bu] 2
\f[C]&max=-1\f[R]: If non-negative, limits the maximum number of
results.
.SH Functions
.PP
.SS re:find {#re:find}
.IP
.nf
\f[C]
re:find &posix=$false &longest=$false &max=-1 $pattern $source
\f[R]
.fi
.PP
Find all matches of \f[C]$pattern\f[R] in \f[C]$source\f[R].
.PP
Each match is represented by a map-like value \f[C]$m\f[R];
\f[C]$m[text]\f[R], \f[C]$m[start]\f[R] and \f[C]$m[end]\f[R] are the
text, start and end positions (as byte indices into \f[C]$source\f[R])
of the match; \f[C]$m[groups]\f[R] 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[R] key.
The entire pattern is an implicit capture group, and it always appears
first.
.PP
Examples:
.IP
.nf
\f[C]
\[ti]> re:find . ab
\[u25B6] [&text=a &start=0 &end=1 &groups=[[&text=a &start=0 &end=1]]]
\[u25B6] [&text=b &start=1 &end=2 &groups=[[&text=b &start=1 &end=2]]]
\[ti]> re:find \[aq][A-Z]([0-9])\[aq] \[aq]A1 B2\[aq]
\[u25B6] [&text=A1 &start=0 &end=2 &groups=[[&text=A1 &start=0 &end=2] [&text=1 &start=1 &end=2]]]
\[u25B6] [&text=B2 &start=3 &end=5 &groups=[[&text=B2 &start=3 &end=5] [&text=2 &start=4 &end=5]]]
\f[R]
.fi
.PP
.SS re:match {#re:match}
.IP
.nf
\f[C]
re:match &posix=$false $pattern $source
\f[R]
.fi
.PP
Determine whether \f[C]$pattern\f[R] matches \f[C]$source\f[R].
The pattern is not anchored.
Examples:
.IP
.nf
\f[C]
\[ti]> re:match . xyz
\[u25B6] $true
\[ti]> re:match . \[aq]\[aq]
\[u25B6] $false
\[ti]> re:match \[aq][a-z]\[aq] A
\[u25B6] $false
\f[R]
.fi
.PP
.SS re:quote {#re:quote}
.IP
.nf
\f[C]
re:quote $string
\f[R]
.fi
.PP
Quote \f[C]$string\f[R] for use in a pattern.
Examples:
.IP
.nf
\f[C]
\[ti]> re:quote a.txt
\[u25B6] a\[rs].txt
\[ti]> re:quote \[aq](*)\[aq]
\[u25B6] \[aq]\[rs](\[rs]*\[rs])\[aq]
\f[R]
.fi
.PP
.SS re:replace {#re:replace}
.IP
.nf
\f[C]
re:replace &posix=$false &longest=$false &literal=$false $pattern $repl $source
\f[R]
.fi
.PP
Replace all occurrences of \f[C]$pattern\f[R] in \f[C]$source\f[R] with
\f[C]$repl\f[R].
.PP
The replacement \f[C]$repl\f[R] can be any of the following:
.IP \[bu] 2
A string-typed replacement template.
The template can use \f[C]$name\f[R] or \f[C]${name}\f[R] patterns to
refer to capture groups, where \f[C]name\f[R] consists of letters,
digits and underscores.
A purely numeric patterns like \f[C]$1\f[R] refers to the capture group
with the corresponding index; other names refer to capture groups named
with the \f[C](?P<name>...)\f[R]) syntax.
.RS 2
.PP
In the \f[C]$name\f[R] form, the name is taken to be as long as
possible; \f[C]$1\f[R] is equivalent to \f[C]${1x}\f[R], not
\f[C]${1}x\f[R]; \f[C]$10\f[R] is equivalent to \f[C]${10}\f[R], not
\f[C]${1}0\f[R].
.PP
To insert a literal \f[C]$\f[R], use \f[C]$$\f[R].
.RE
.IP \[bu] 2
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[R] is true, \f[C]$repl\f[R] must be a string and is
treated literally instead of as a pattern.
.PP
Example:
.IP
.nf
\f[C]
\[ti]> re:replace \[aq](ba|z)sh\[aq] \[aq]${1}SH\[aq] \[aq]bash and zsh\[aq]
\[u25B6] \[aq]baSH and zSH\[aq]
\[ti]> re:replace \[aq](ba|z)sh\[aq] elvish \[aq]bash and zsh rock\[aq]
\[u25B6] \[aq]elvish and elvish rock\[aq]
\[ti]> re:replace \[aq](ba|z)sh\[aq] {|x| put [&bash=BaSh &zsh=ZsH][$x] } \[aq]bash and zsh\[aq]
\[u25B6] \[aq]BaSh and ZsH\[aq]
\f[R]
.fi
.PP
.SS re:split {#re:split}
.IP
.nf
\f[C]
re:split &posix=$false &longest=$false &max=-1 $pattern $source
\f[R]
.fi
.PP
Split \f[C]$source\f[R], using \f[C]$pattern\f[R] as separators.
Examples:
.IP
.nf
\f[C]
\[ti]> re:split : /usr/sbin:/usr/bin:/bin
\[u25B6] /usr/sbin
\[u25B6] /usr/bin
\[u25B6] /bin
\[ti]> re:split &max=2 : /usr/sbin:/usr/bin:/bin
\[u25B6] /usr/sbin
\[u25B6] /usr/bin:/bin
\f[R]
.fi