github.com/elves/elvish@v0.15.0/website/ref/re.md (about)

     1  <!-- toc -->
     2  
     3  # Introduction
     4  
     5  The `re:` module wraps Go's `regexp` package. See the Go's doc for supported
     6  [regular expression syntax](https://godoc.org/regexp/syntax).
     7  
     8  # Functions
     9  
    10  Function usages notations follow the same convention as the
    11  [builtin module doc](builtin.html).
    12  
    13  The following options are supported by multiple functions in this module:
    14  
    15  -   `&posix` (defaults to `$false`): Use POSIX ERE syntax. See also
    16      [doc](http://godoc.org/regexp#CompilePOSIX) in Go package.
    17  
    18  -   `&longest` (defaults to `$false`): Prefer leftmost-longest match. See also
    19      [doc](http://godoc.org/regexp#Regexp.Longest) in Go package.
    20  
    21  -   `&max` (defaults to -1): If non-negative, maximum number of results.
    22  
    23  ## find
    24  
    25  ```elvish
    26  re:find &posix=$false &longest=$false &max=-1 $pattern $source
    27  ```
    28  
    29  Find all matches of `$pattern` in `$source`.
    30  
    31  Each match is represented by a map-like value `$m`; `$m[text]`, `$m[start]` and
    32  `$m[end]` are the text, start and end positions (as byte indices into `$source`)
    33  of the match; `$m[groups]` is a list of submatches for capture groups in the
    34  pattern. A submatch has a similar structure to a match, except that it does not
    35  have a `group` key. The entire pattern is an implicit capture group, and it
    36  always appears first.
    37  
    38  Examples:
    39  
    40  ```elvish-transcript
    41  ~> re:find . ab
    42  ▶ [&text=a &start=0 &end=1 &groups=[[&text=a &start=0 &end=1]]]
    43  ▶ [&text=b &start=1 &end=2 &groups=[[&text=b &start=1 &end=2]]]
    44  ~> re:find '[A-Z]([0-9])' 'A1 B2'
    45  ▶ [&text=A1 &start=0 &end=2 &groups=[[&text=A1 &start=0 &end=2] [&text=1 &start=1 &end=2]]]
    46  ▶ [&text=B2 &start=3 &end=5 &groups=[[&text=B2 &start=3 &end=5] [&text=2 &start=4 &end=5]]]
    47  ```
    48  
    49  ## match
    50  
    51  ```elvish
    52  re:match &posix=$false $pattern $source
    53  ```
    54  
    55  Determine whether `$pattern` matches `$source`. The pattern is not anchored.
    56  Examples:
    57  
    58  ```elvish-transcript
    59  ~> re:match . xyz
    60  ▶ $true
    61  ~> re:match . ''
    62  ▶ $false
    63  ~> re:match '[a-z]' A
    64  ▶ $false
    65  ```
    66  
    67  ## replace
    68  
    69  ```elvish
    70  re:replace &posix=$false &longest=$false &literal=$false $pattern $repl $source
    71  ```
    72  
    73  Replace all occurrences of `$pattern` in `$source` with `$repl`.
    74  
    75  The replacement `$repl` can be either
    76  
    77  1.  A string-typed replacement template. The template can use `$name` or
    78      `${name}` patterns to refer to capture groups, where `name` consists of
    79      letters, digits and underscores. Numbered patterns like `$1` refer to
    80      capture groups by their order, while named patterns like `$stem` refer to
    81      capture groups by their names (specified using the syntax `(?P<name>...)`).
    82      Use `$$` for a literal dollar sign. The name is taken as long as possible;
    83      for instance, `$1a` is the same as `${1a}`.
    84  
    85      See also doc of Go's regexp package on the
    86      [template syntax](https://godoc.org/regexp#Regexp.Expand).
    87  
    88  2.  A function that takes a string argument and outputs a string. For each
    89      match, the function is called with the content of the match, and its output
    90      is used as the replacement.
    91  
    92  If `$literal` is true, `$repl` must be a string and is treated literally instead
    93  of as a pattern.
    94  
    95  Example:
    96  
    97  ```elvish-transcript
    98  ~> re:replace '(ba|z)sh' '${1}SH' 'bash and zsh'
    99  ▶ 'baSH and zSH'
   100  ~> re:replace '(ba|z)sh' elvish 'bash and zsh rock'
   101  ▶ 'elvish and elvish rock'
   102  ~> re:replace '(ba|z)sh' [x]{ put [&bash=BaSh &zsh=ZsH][$x] } 'bash and zsh'
   103  ▶ 'BaSh and ZsH'
   104  ```
   105  
   106  ## split
   107  
   108  ```elvish
   109  re:split &posix=$false &longest=$false &max=-1 $pattern $source
   110  ```
   111  
   112  Split `$source`, using `$pattern` as separators. Examples:
   113  
   114  ```elvish-transcript
   115  ~> re:split : /usr/sbin:/usr/bin:/bin
   116  ▶ /usr/sbin
   117  ▶ /usr/bin
   118  ▶ /bin
   119  ~> re:split &max=2 : /usr/sbin:/usr/bin:/bin
   120  ▶ /usr/sbin
   121  ▶ /usr/bin:/bin
   122  ```
   123  
   124  ## quote
   125  
   126  ```elvish
   127  re:quote $string
   128  ```
   129  
   130  Quote `$string`. Examples:
   131  
   132  ```elvish-transcript
   133  ~> re:quote a.txt
   134  ▶ a\.txt
   135  ~> re:quote '(*)'
   136  ▶ '\(\*\)'
   137  ```