RE-Build reference
==================

# `RegExp` builders

The object obtained from building a regular expressions *builders*. Builders are augmented with members and methods to build the regex further, but they're basically immutable objects as every call to extend the builder returns a *new* builder instance.

## Properties

All the following properties are read-only.

Type    | Name         | Description
-------:|--------------|-------------
string  | `regex`      | The regular expression defined by the builder. It's compiled the first time the property is requested, then cached
string  | `source`     | The source of the underlying regular expression. Used to compile it
string  | `flags`      | A string comprising the regex' flags. It may include one or more of the letters `"g"`, `"m"`, `"i"`, `"u"` or `"y"`
boolean | `global`     | The regex' `global` flag
boolean | `ignoreCase` | The regex' `ignoreCase` flag
boolean | `multiline`  | The regex' `multiline` flag
boolean | `unicode`    | The regex' `unicode` flag
boolean | `sticky`     | The regex' `sticky` flag

## Methods

Returns  | Name             | Description
--------:|------------------|-------------------------
`RegExp` | `toRegExp()`     | Basically, returns the `regex` property
`RegExp` | `valueOf()`      | See above
string   | `toString()`     | Returns a string representation
boolean  | `test(string)`   | Uses the underlying regex to test a string. Short for `.regex.test(...)`
array    | `exec(string)`   | Executes the underlying regex on a string. Short for `.regex.exec(...)`
string   | `replace(string, string/function)` | Uses the underlying regex to perform a regex-based replacement. Short for `string.replace(regex, ...)`
array    | `split(string)`  | Uses the underlying regex to perform a regex-based string split. Short for `string.split(regex)`
number   | `search(string)` | Uses the underlying regex to perform a string search. Short for `string.search(regex)`

# Building a regex

Regex building begins from the he `RE` object returned by the module. You can obtain a *builder* every time you use "words" like `digit`, `then` and such. Some of these words act like functions (like `atLeast` and `codePoint`), some like properties (like `digit` and `theEnd`), some work as both.

In this last case, if the word is not used as a function, additional words are expected to obtain a builder:

```js
var foo = RE.matching.digit.then.alphaNumeric;
```

Many words that can (or must) be used as functions accept a variable number of arguments, that can be either strings, or regular expressions, or builders, which are all appended to the source. Strings are backslash-escaped, while in the other cases the `source` property is then added *unescaped*:

```js
var amount = RE.oneOrMore.digit.then(".").then.digit.then.digit,
    currency = /[$€£]/;

var builder = RE.matching.theStart
                .then("Total: ", amount, currency)
                .then.theEnd;
```

Other words that work as functions only usually accept other types of arguments.

## Flags

The flags of a builder (and its underlying regular expression) can be set using words starting from the `RE` object. After one of these words, another flag word or `matching` must follow, with the exception of `withFlags` that must be followed by `matching` only.

* **`globally`**

  Set the `global` flag on.

* **`anyCase`**

  Set the `ignoreCase` flag on.

* **`fullText`**

  Set the `multiline` flag on.

* **`stickily`**

  Set the `sticky` flag on.

* **`withUnicode`**

  Set the `unicode` flag on.

* **`withFlags(flags)`**

  Set multiple flags. `flags` is expected to be a string containing letters in the set `"g"`, `"m"`, `"i"` and `"y"`.

## Conjunctions

Conjunctions append additional blocks to the current source. They can follow any open or set block.

* **`then`**

  Appends a block to the current source.

* **`or`**

  Adds an alternative block (prefixed by the pipe `|` character in regular expressions).

## Open and set blocks

These words can be used in both "open" sequences or inside character sets. They can be used after conjunction words, or a quantifier, or the `matching` word, or the `RE` object itself, or the `and` word joining blocks in character sets.

* **`digit` / `not.digit`**

  A digit character (`\d`) or its negation (`\D`).

* **`alphaNumeric` / `not.alphaNumeric`**

  An alphanumeric character plus the undescore (`\w`) or its negation (`\W`).

* **`whiteSpace` / `not.whisteSpace`**

  A whitespace (`\s`) or its negation (`\W`).
* **`cReturn`** `\r`
* **`newLine`** `\n`
* **`tab`** `\t`
* **`vTab`** `\v`
* **`formFeed`** `\f`
* **`null`** `\0`
* **`slash`** `\/`
* **`backslash`** `\\`
* **`ascii(code)`**

  An ASCII escape sequence (`\xhh`). `code` must be an integer between 0 and 255. It it then converted as two hexadecimal digits in the sequence.

* **`codePoint(code, ...)`**

  An Unicode escape sequence (`\uhhhh`, or `\u{hhhhh}` with the `unicode` flag set and with a code not from the [Basic Multilingual Plane](https://en.wikipedia.org/wiki/Plane_(Unicode))). `code` must be an integer between 0 and 1114111 (`0x10ffff`) or a `RangeError` will be thrown; or it can be a string, whose code points will be converted in the corresponding Unicode escape sequence. Keep in mind that code points from astral planes, when the `unicode` flag is *not* set, are encoded in the corresponding surrogate code point pairs (e.g.: `"🍰"` will become `"\ud83c\udf70"`): *it is your duty* to wrap the pairs in a group if needed or, when it's not possible (for example, in a character range) using an adequate regex structure.

* **`control(letter)`**

  A control sequence (`\cx`). `letter` must be a string of a single letter. It is then converted to uppercase in the sequence.

## Open-only blocks

These words can be used in open block sequences only (which means, not inside character sets). They can be used after conjunction words, or a quantifier, or the `matching` word, or the `RE` object itself.

* **`anyChar`**

  The universal character (`.`).

* **`theStart` / `theEnd`**

  The string-start and string-end boundaries (`^` and `$`, respectively).

* **`wordBoundary` / `not.wordBoundary`**

  A word boundary (`\b`) or its negation (`\B`).

* **`oneOf` / `not.oneOf`**

  Appends a character set (`[...]` or `[^...]`, respectively). See the paragraph about [character sets](#character-sets).

* **`group(...)`**

  Non-capturing group - `(?:...)`. Used as functions only. Arguments can be strings, regexes or builders.

* **`capture(...)`**

  Capturing group - `(...)`. Used as functions only. Arguments can be strings, regexes or builders.

* **`reference(number)`**

  Group backreference (`\number`). `number` should be a positive integer.

## Character sets

Character sets are introduced by the `oneOf` word, and may include one or more blocks separated by the `and` word (e.g.: `RE.oneOf.digit.and("abcdef")`).

These words can be used in character sets only:

* **`range(start, end)`**

  Adds a character interval into the character set (`[...start-end...]`). `start` and `end` are supposed to be strings of single characters defining the boundaries of the character range; or they can be builders that define one single character, or character class usable in character ranges (which include: `ascii`, `unicode`, `control`, `newLine`, `cReturn`, `tab`, `vTab`, `formFeed`, `null`).

* **`backspace`**

  The backspace character, `\b` (U+0008). Not to be confused with the word boundary, which can be used as an "open" block only.

## Quantifiers

Quantifiers can follow conjunction words, or the `matching` word, or the `RE` object itself, and can precede any "open" block, with the exception of `wordBoundary`, `not.wordBoundary`, `theStart` and `theEnd`.

They can be prefixed by `lazily` to define a lazy quantifier, instead of a greedy one.

Quantifiers can be used as functions, and accept strings, regexes or builders as arguments. A convenient group wrap will be used if necessary:

```js
var foo = RE.oneOrMore("a");   // /a+/
var bar = RE.oneOrMore("abc"); // /(?:abc)+/
```

* **`anyAmountOf`** `*`
* **`oneOrMore`** `+`
* **`noneOrOne`** `?`
* **`atLeast(n)`**

  `n` must be a non-negative integer. If `n` is 0, a `*` is produced; if `n` is 1, then `+` is produced; else, the quantifier is `{n,}`.

* **`atMost(n)`**

  `n` must be a non-negative integer. If `n` is 1, then `?` is produced; else, the quantifier is `{,n}`.

* **`exactly(n)`**

  `n` must be a non-negative integer. If `n` is 1, then no quantifier is defined; else, the quantifier is `{n}`.

* **`between(n, m)`**

  `n` and `m` must be non-negative integers. If the the values are adequate, the produced quantifier can be one of the above; otherwise, the quantifier is `{n,m}`.


## Look-aheads

* **`followedBy(...)` / `not.followedBy(...)`**

  Appends a look-ahead (`(?=...)` or `(?!...)`, respectively). Used as functions only. Arguments can be strings, regexes or builders.

  Can follow any open block, or the `matching` word, or the `RE` object itself, or the `or` conjunction.