Skip to content
Lou's Code

Functional Expression Reference

Coverage License NPM Version Open Issues Size

🧙 Functional Regular expression builder.

Usage

📦 Node

Install functional-expression as a dependency:

Terminal window
1
pnpm add functional-expression
2
# or
3
npm install functional-expression
4
# or
5
yarn add functional-expression

Import it and use it:

1
import { build, group, or } from "functional-expression";
2


3
build("gu")(group(or("this", "that"))); // /(?:this|that)/gu

🦕 Deno

Import functional-expression using the npm: prefix, and use it directly:

1
import { build, group, or } from "npm:functional-expression";
2


3
build("gu")(group(or("this", "that"))); // /(?:this|that)/gu

🌎 Browser

Import functional-expression using esm.sh, and use it directly:

1
<script type="module">
2
	import { build, group, or } from "https://esm.sh/functional-expression";
3


4
	build("gu")(group(or("this", "that"))); // /(?:this|that)/gu
5
</script>

Anchors

END

1
const END: "$" = "$";

Matches the end of the string, or the end of a line if the multiline flag (m) is enabled. This matches a position, not a character.

View source

NOT_WORD_BOUNDARY

1
const NOT_WORD_BOUNDARY: "B";

Matches any position that is not a word boundary. This matches a position, not a character.

View source

START

1
const START: "^" = "^";

Matches the beginning of the string, or the beginning of a line if the multiline flag (m) is enabled. This matches a position, not a character.

View source

WORD_BOUNDARY

1
const WORD_BOUNDARY: "\b";

Matches a word boundary position between a word character and non-word character or position (start / end of string). See the word character class (w) for more info.

View source

Character classes

ALL

1
const ALL: "." = ".";

Matches any character except linebreaks. Equivalent to [^\n\r].

View source

DIGIT

1
const DIGIT: "d";

Matches any digit character (0-9). Equivalent to [0-9].

View source

NOT_DIGIT

1
const NOT_DIGIT: "D";

Matches any character that is not a digit character (0-9). Equivalent to [^0-9].

View source

NOT_WHITESPACE

1
const NOT_WHITESPACE: "S";

Matches any character that is not a whitespace character (spaces, tabs, line breaks).

View source

NOT_WORD

1
const NOT_WORD: "W";

Matches any character that is not a word character (alphanumeric & underscore). Equivalent to [^A-Za-z0-9_]

View source

WHITESPACE

1
const WHITESPACE: "s";

Matches any whitespace character (spaces, tabs, line breaks).

View source

WORD

1
const WORD: "w";

Matches any word character (alphanumeric & underscore). Only matches low-ascii characters (no accented or non-roman characters). Equivalent to [A-Za-z0-9_]

View source

notSet()

1
function notSet<Tokens>(
2
	...tokens: Tokens
3
): `[${StringJoin<["^", ...Tokens[]], "", "^", [0]>}]`;

Match any character that is not in the set.

Type parameters

Type parameter
Tokens extends ReadOnlyArray<Strigifiable>

Parameters

ParameterType
…tokensTokens

Returns

`[${StringJoin<[”^”, …Tokens[]], "", ”^”, [0]>}]`

View source

notUnicodeCharacterClassEscape()

1
function notUnicodeCharacterClassEscape<Category>(category: Category): P{${Category}}

Matches any character that is not in the specified unicode category.

Requires the u flag.

Type parameters

Type parameter
Category extends Strigifiable

Parameters

ParameterType
categoryCategory

Returns

\P{${Category}}

See

Unicode Character class escape

View source

range()

1
function range<From>(from: From): <To>(to: To) => `${From}-${To}`;

Matches a character having a character code between the two specified characters inclusive. Must be used with set.

Type parameters

Type parameter
From extends Strigifiable

Parameters

ParameterType
fromFrom

Returns

Function

Type parameters
Type parameter
To extends Strigifiable
Parameters
ParameterType
toTo
Returns

`${From}-${To}`

View source

set()

1
function set<Tokens>(
2
	...tokens: Tokens
3
): `[${StringJoin<[...Tokens[]], "", `${[...Tokens[]][0]}`, [0]>}]`;

Match any character in the set.

Type parameters

Type parameter
Tokens extends ReadOnlyArray<Strigifiable>

Parameters

ParameterType
…tokensTokens

Returns

`[${StringJoin<[…Tokens[]], "", `${[…Tokens[]][0]}`, [0]>}]`

View source

unicodeCharacterClassEscape()

1
function unicodeCharacterClassEscape<Category>(category: Category): p{${Category}}

Matches a character in the specified unicode category.

Requires the u flag.

Type parameters

Type parameter
Category extends Strigifiable

Parameters

ParameterType
categoryCategory

Returns

\p{${Category}}

See

Unicode Character class escape

View source

Escaped Characters

HexadecimalDigit

1
type HexadecimalDigit: `${Digit | "A" | "B" | "C" | "D" | "E" | "F"}`;

Possible digits for an hexadecimal number.

View source

UppercaseLetters

1
type UppercaseLetters:
2
  | "A"
3
  | "B"
4
  | "C"
5
  | "D"
6
  | "E"
7
  | "F"
8
  | "G"
9
  | "H"
10
  | "I"
11
  | "J"
12
  | "K"
13
  | "L"
14
  | "M"
15
  | "N"
16
  | "O"
17
  | "P"
18
  | "Q"
19
  | "R"
20
  | "S"
21
  | "T"
22
  | "U"
23
  | "V"
24
  | "W"
25
  | "X"
26
  | "Y"
27
  | "Z";

Uppercase letter values.

View source

CARRIAGE_RETURN

1
const CARRIAGE_RETURN: "\r";

Matches a CARRIAGE RETURN character (char code 13).

View source

FORM_FEED

1
const FORM_FEED: "\f";

Matches a FORM FEED character (char code 12).

View source

LINE_FEED

1
const LINE_FEED: "\n";

Matches a LINE FEED character (char code 10).

View source

NULL

1
const NULL: "\0";

Matches a NULL character (char code 0).

View source

TAB

1
const TAB: "\t";

Matches a TAB character (char code 9).

View source

VERTICAL_TAB

1
const VERTICAL_TAB: "\v";

Matches a VERTICAL TAB character (char code 11).

View source

controlCharacter()

1
function controlCharacter<Character>(character: Character): c$ {
2
	Character;
3
}

Escaped control character in the form \cZ. This can range from \cA (SOH, char code 1) to \cZ (SUB, char code 26).

Type parameters

Type parameter
Character extends UppercaseLetters

Parameters

ParameterType
characterCharacter

Returns

\c${Character}

View source

hexadecimal()

1
function hexadecimal<HexadecimalValue>(hexadecimalValue: HexadecimalValue): x$ {
2
	HexadecimalValue;
3
}

Hexadecimal escaped character in the form \xFF.

Type parameters

Type parameter

| HexadecimalValue extends | "AA" | "AB" | "AC" | "AD" | "AE" | "AF" | "A0" | "A9" | "A1" | "A2" | "A3" | "A4" | "A5" | "A6" | "A7" | "A8" | "BA" | "BB" | "BC" | "BD" | "BE" | "BF" | "B0" | "B9" | "B1" | "B2" | "B3" | "B4" | "B5" | "B6" | "B7" | "B8" | "CA" | "CB" | "CC" | "CD" | "CE" | "CF" | "C0" | "C9" | "C1" | "C2" | "C3" | "C4" | "C5" | "C6" | "C7" | "C8" | "DA" | "DB" | "DC" | "DD" | "DE" | "DF" | "D0" | "D9" | "D1" | "D2" | "D3" | "D4" | "D5" | "D6" | "D7" | "D8" | "EA" | "EB" | "EC" | "ED" | "EE" | "EF" | "E0" | "E9" | "E1" | "E2" | "E3" | "E4" | "E5" | "E6" | "E7" | "E8" | "FA" | "FB" | "FC" | "FD" | "FE" | "FF" | "F0" | "F9" | "F1" | "F2" | "F3" | "F4" | "F5" | "F6" | "F7" | "F8" | "0A" | "0B" | "0C" | "0D" | "0E" | "0F" | "00" | "09" | "01" | "02" | "03" | "04" | "05" | "06" | "07" | "08" | "9A" | "9B" | "9C" | "9D" | "9E" | "9F" | "90" | "99" | "91" | "92" | "93" | "94" | "95" | "96" | "97" | "98" | "1A" | "1B" | "1C" | "1D" | "1E" | "1F" | "10" | "19" | "11" | "12" | "13" | "14" | "15" | "16" | "17" | "18" | "2A" | "2B" | "2C" | "2D" | "2E" | "2F" | "20" | "29" | "21" | "22" | "23" | "24" | "25" | "26" | "27" | "28" | "3A" | "3B" | "3C" | "3D" | "3E" | "3F" | "30" | "39" | "31" | "32" | "33" | "34" | "35" | "36" | "37" | "38" | "4A" | "4B" | "4C" | "4D" | "4E" | "4F" | "40" | "49" | "41" | "42" | "43" | "44" | "45" | "46" | "47" | "48" | "5A" | "5B" | "5C" | "5D" | "5E" | "5F" | "50" | "59" | "51" | "52" | "53" | "54" | "55" | "56" | "57" | "58" | "6A" | "6B" | "6C" | "6D" | "6E" | "6F" | "60" | "69" | "61" | "62" | "63" | "64" | "65" | "66" | "67" | "68" | "7A" | "7B" | "7C" | "7D" | "7E" | "7F" | "70" | "79" | "71" | "72" | "73" | "74" | "75" | "76" | "77" | "78" | "8A" | "8B" | "8C" | "8D" | "8E" | "8F" | "80" | "89" | "81" | "82" | "83" | "84" | "85" | "86" | "87" | "88" |

Parameters

ParameterType
hexadecimalValueHexadecimalValue

Returns

\x${HexadecimalValue}

View source

unicode()

1
function unicode<HexadecimalValue>(hexadecimalValue: HexadecimalValue): u{${HexadecimalValue}}

Unicode escaped character in the form \u{FFFF}. Supports a full range of unicode point escapes with any number of hex digits.

Requires the unicode flag (u).

Type parameters

Type parameter
HexadecimalValue extends Strigifiable

Parameters

ParameterType
hexadecimalValueHexadecimalValue

Returns

\u{${HexadecimalValue}}

View source

Groups & References

capture()

1
function capture<Captured>(
2
	...captured: Captured
3
): `(${StringJoin<[...Captured[]], "", `${[...Captured[]][0]}`, [0]>})`;

Groups multiple tokens together and creates a capture group for extracting a substring or using a backreference.

Type parameters

Type parameter
Captured extends ReadOnlyArray<Strigifiable>

Parameters

ParameterType
…capturedCaptured

Returns

`(${StringJoin<[…Captured[]], "", `${[…Captured[]][0]}`, [0]>})`

View source

captureNamed()

1
function captureNamed<Name>(
2
	name: Name,
3
): <Captured>(
4
	...captured: Captured
5
) => `(?<${Name}>${StringJoin<[...Captured[]], "", `${[...Captured[]][0]}`, [0]>})`;

Creates a capturing group that can be referenced via the specified name.

Type parameters

Type parameter
Name extends Strigifiable

Parameters

ParameterType
nameName

Returns

Function

Type parameters
Type parameter
Captured extends ReadOnlyArray<Strigifiable>
Parameters
ParameterType
…capturedCaptured
Returns

`(?<${Name}>${StringJoin<[…Captured[]], "", `${[…Captured[]][0]}`, [0]>})`

View source

captureType()

1
function captureType<Type>(
2
	type: Type,
3
): <Captured>(
4
	...captured: Captured
5
) => `(?${Type}${StringJoin<[...Captured[]], "", `${[...Captured[]][0]}`, [0]>})`;

Helper for all groups that start with ?.

Type parameters

Type parameter
Type extends Strigifiable

Parameters

ParameterType
typeType

Returns

Function

Type parameters
Type parameter
Captured extends ReadOnlyArray<Strigifiable>
Parameters
ParameterType
…capturedCaptured
Returns

`(?${Type}${StringJoin<[…Captured[]], "", `${[…Captured[]][0]}`, [0]>})`

View source

capturedNumber()

1
function capturedNumber<GroupNumber>(groupNumber: GroupNumber): $ {
2
	GroupNumber;
3
}

Matches the results of a capture group. For example \1 matches the results of the first capture group & \3 matches the third.

Type parameters

Type parameter
GroupNumber extends number

Parameters

ParameterType
groupNumberGroupNumber

Returns

\${GroupNumber}

View source

group()

1
function group<Captured>(
2
	...captured: Captured
3
): `(?:${StringJoin<[...Captured[]], "", `${[...Captured[]][0]}`, [0]>})`;

Groups multiple tokens together without creating a capture group.

Type parameters

Type parameter
Captured extends ReadOnlyArray<Strigifiable>

Parameters

ParameterType
…capturedCaptured

Returns

`(?:${StringJoin<[…Captured[]], "", `${[…Captured[]][0]}`, [0]>})`

View source

Look around

captureNext()

1
function captureNext<Captured>(
2
	...captured: Captured
3
): `(?=${StringJoin<[...Captured[]], "", `${[...Captured[]][0]}`, [0]>})`;

Matches a group after the main expression without including it in the result.

Type parameters

Type parameter
Captured extends ReadOnlyArray<Strigifiable>

Parameters

ParameterType
…capturedCaptured

Returns

`(?=${StringJoin<[…Captured[]], "", `${[…Captured[]][0]}`, [0]>})`

View source

capturePrevious()

1
function capturePrevious<Captured>(
2
	...captured: Captured
3
): `(?<=${StringJoin<[...Captured[]], "", `${[...Captured[]][0]}`, [0]>})`;

Matches a group before the main expression without including it in the
result.

Type parameters

Type parameter
Captured extends ReadOnlyArray<Strigifiable>

Parameters

ParameterType
…capturedCaptured

Returns

`(?<=${StringJoin<[…Captured[]], "", `${[…Captured[]][0]}`, [0]>})`

View source

notCaptureNext()

1
function notCaptureNext<Captured>(
2
	...captured: Captured
3
): `(?!${StringJoin<[...Captured[]], "", `${[...Captured[]][0]}`, [0]>})`;

Specifies a group that can not match after the main expression (if it matches, the result is discarded).

Type parameters

Type parameter
Captured extends ReadOnlyArray<Strigifiable>

Parameters

ParameterType
…capturedCaptured

Returns

`(?!${StringJoin<[…Captured[]], "", `${[…Captured[]][0]}`, [0]>})`

View source

notCapturePrevious()

1
function notCapturePrevious<Captured>(
2
	...captured: Captured
3
): `(?<!${StringJoin<[...Captured[]], "", `${[...Captured[]][0]}`, [0]>})`;

Specifies a group that can not match before the main expression (if it matches, the result is discarded).

Type parameters

Type parameter
Captured extends ReadOnlyArray<Strigifiable>

Parameters

ParameterType
…capturedCaptured

Returns

`(?<!${StringJoin<[…Captured[]], "", `${[…Captured[]][0]}`, [0]>})`

View source

Quantifiers & Alternation

allow()

1
function allow<Token>(token: Token): `${Token}*`;

Matches 0 or more of the preceding token.

Type parameters

Type parameter
Token extends Strigifiable

Parameters

ParameterType
tokenToken

Returns

`${Token}*`

View source

exists()

1
function exists<Token>(token: Token): `${Token}+`;

Matches 1 or more of the preceding token.

Type parameters

Type parameter
Token extends Strigifiable

Parameters

ParameterType
tokenToken

Returns

`${Token}+`

View source

optional()

1
function optional<Token>(token: Token): `${Token}?`;

Matches 0 or 1 of the preceding token, effectively making it optional. Also makes the preceding quantifier lazy, causing it to match as few characters as possible. By default, quantifiers are greedy, and will match as many characters as possible.

Type parameters

Type parameter
Token extends Strigifiable

Parameters

ParameterType
tokenToken

Returns

`${Token}?`

View source

or()

1
function or<Tokens>(...tokens: Tokens): StringJoin<Tokens, "|">;

Acts like a boolean OR. Matches the expression before or after the |. It can operate within a group, or on a whole expression. The patterns will be tested in order.

Type parameters

Type parameter
Tokens extends ReadOnlyArray<Strigifiable>

Parameters

ParameterType
…tokensTokens

Returns

StringJoin<Tokens, ”|“>

View source

quantity()

1
function quantity<Quantities>(
2
	quantities: Quantities,
3
): <Token>(token: Token) => `${Token}{${Quantities}}`;

Matches the specified quantity of the previous token. {1,3} will match 1 to 3. {3} will match exactly 3. {3,} will match 3 or more.

Type parameters

Type parameter
Quantities extends Strigifiable

Parameters

ParameterType
quantitiesQuantities

Returns

Function

Type parameters
Type parameter
Token extends string
Parameters
ParameterType
tokenToken
Returns

`${Token}{${Quantities}}`

View source

Util

build()

1
function build<Flags>(
2
	flags: Flags | "u",
3
): <Tokens>(...tokens: Tokens) => RegExp & object;

Builds a RegExp with required u flag and strongly typed source (using join).

Type parameters

Type parameterValue

| Flags extends | "u" | "su" | "mu" | "msu" | "iu" | "isu" | "imu" | "imsu" | "gu" | "gsu" | "gmu" | "gmsu" | "giu" | "gisu" | "gimu" | "gimsu" | "u" |

Parameters

ParameterTypeDefault value
flagsFlags | "u""u"

Returns

Function

Type parameters
Type parameter
Tokens extends ReadOnlyArray<Strigifiable>
Parameters
ParameterType
…tokensTokens
Returns

RegExp & object

View source

escape()

1
function escape<Escaped>(escaped: Escaped): $ {
2
	Escaped;
3
}

Escape given string with a “.

Type parameters

Type parameter
Escaped extends Strigifiable

Parameters

ParameterTypeDescription
escapedEscapedValue to escape.

Returns

\${Escaped}

Escaped value.

Example

1
escape("n"); // "\\n"

View source

join()

1
function join<Tokens>(...tokens: Tokens): StringJoin<Tokens, "">;

Util to join strings.

Type parameters

Type parameter
Tokens extends ReadOnlyArray<Strigifiable>

Parameters

ParameterType
…tokensTokens

Returns

StringJoin<Tokens, "">

View source