# 1 Regular Expressions

The `regex` module implements an interface to the POSIX regex library and builds some higher level facilities on top of it. The module may be imported as follows:

> `import Regex at 'x-oz://contrib/regex'`

`Regex.is`

  > `{Regex.is` `+X``` `?B``}`

  Returns `true` iff `X` is a regex object.

`Regex.make`

  > `{Regex.make` `+PAT``` `?RE``}`

  Creates regex object `RE` from virtual string pattern `PAT`. Note that `Regex.make` cannot be used in (subordinated) spaces.

`Regex.search`

  > `{Regex.search` `+RE``` `+TXT``` `?MATCH``}`

  Returns the next `MATCH` of regex `RE` in virtual string `TXT`, or `false` if there is no such match. `RE` is also permitted to be a virtual string pattern, in which case it is automatically compiled into a regex object.

  A match is a record with integer features: one for each group in the pattern and also feature 0 for the whole match. The value on each feature is a pair `I#J` of start and end indices into `TXT`. If `TXT` is a byte string, you can simply invoke `{ByteString.slice TXT I J}` to extract the match.

`Regex.group`

  > `{Regex.group` `+N``` `+MATCH``` `+TXT``` `?GROUP``}`

  Return the substring `GROUP` matched by the `N` group of `MATCH` in virtual string `TXT`. `MATCH` should be the result of calling `Regex.search` on `TXT`.

`Regex.groups`

  > `{Regex.groups` `+MATCH``` `+TXT``` `?GROUPS``}`

  Returns the record `GROUPS`, with label `group`, of substrings of `TXT` corresponding to the groups of `MATCH`. Group 0 (the whole match) is not included.

`Regex.allMatches`

  > `{Regex.allMatches` `+RE``` `+TXT``` `?MATCHES``}`

  Returns the list of all `MATCHES` of regular expression `RE` in virtual string `TXT`. `RE` should not be anchored.

`Regex.forAll`

  > `{Regex.forAll` `+RE``` `+TXT``` `+P``}`

  Applies the 1 argument procedure `P` to every match of `RE` in `TXT`.

`Regex.map`

  > `{Regex.map` `+RE``` `+TXT``` `+F``` `?RESULTS``}`

  Applies the 1 argument function `F` to every match of `RE` in `TXT` and returns the corresponding list of `RESULTS`.

`Regex.foldR`

  > `{Regex.foldR` `+RE``` `+TXT``` `+F``` `INIT``` `?RESULT``}`

`Regex.foldL`

  > `{Regex.foldL` `+RE``` `+TXT``` `+F``` `INIT``` `?RESULT``}`

  The usual reduction procedure (see List module).

`Regex.split`

  > `{Regex.split` `+RE``` `+TXT``` `?STRINGS``}`

  Splits the input `TXT` at every match of separator `RE`, and returns the resulting list of strings.

`Regex.compile`

  > `{Regex.compile` `+PAT``` `+CFLAGS``` `?RE``}`

  This is the more complicated version of `Regex.make`. The additional `CFLAGS` argument further parametrizes the regex compilation process. It is either an atom or a list of atoms, from the set: `extended`, `icase`, `nosub`, `newline`. The default is `[extended newline]`. See the man page for `regcomp` for further details.

`Regex.execute`

  > `{Regex.execute` `+RE``` `+TXT``` `+IDX``` `+EFLAGS``` `?MATCH``}`

  This is the more complicated version of `Regex.search`. Integer `IDX` is the offset at which to start the search in `+TXT`. `EFLAGS` further specify how to search: it is an atom or list of atoms, from the set: `notbol`, `noteol`. The default is `nil`. See the man page for `regexec` for further details.

`Regex.cflags.set`
`Regex.cflags.get`

  > `{Regex.cflags.set` `+SPEC``}`

  > `{Regex.cflags.get` `?SPEC``}`

  Set or get the current `CFLAGS` defaults, e. g. used by `Regex.make`.

`Regex.eflags.set`
`Regex.eflags.get`

  > `{Regex.eflags.set` `+SPEC``}`

  > `{Regex.eflags.get` `?SPEC``}`

  Set or get the current `EFLAGS` defaults, e. g. used by `Regex.search`.

`Regex.replace`

  > `{Regex.replace` `+TXT``` `+RE``` `+FUN``` `?RES``}`

  Replace every occurrence of `RE` in `TXT` with the result of applying `FUN` to the current `TXT` and the current match.

`Regex.replaceRegion`

  > `{Regex.replaceRegion` `+TXT``` `+LO``` `+HI``` `+RE``` `+FUN``` `?RES``}`

  Same as above, but only operate on the region starting at `LO` inclusive and ending at `HI` exclusive.