github.com/xiaq/elvish@v0.12.0/website/src/ref/re.md (about)

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