A JS library for building regular expressions in (almost) natural language

Super Expressive

Super Expressiveis a JavaScript library that allows you to build regular expressions in almost natural language - with no extra dependencies, and a lightweight code footprint (less than 3kb with minification + gzip!).

• Installation and Usage

• Click to expand

  • .allowMultipleMatches
  • .backreference(index)
  • .namedBackreference(index)
  • .anythingButChars(chars)
  • .anythingButString(str)
  • .anythingButRange(a, b)

Why?

Regex is a very powerful tool, but its terse and cryptic vocabulary can make constructing and communicating them with others a challenge. Even developers who understand them well can have trouble reading their own back just a few months later! In addition, they can't be easily created and manipulated in a programmatic way - closing off an entire avenue of dynamic text processing.

That's where Super Expressive comes in. It provides a programmatic and human readable way to create regular expressions. It's API uses the fluent builder pattern , and is completely immutable. It's built to be discoverable and predictable:

SuperExpressive().exactly(5).digit

SuperExpressive turns those complex and unweildy regexes that appear in code reviews into something that can be read, understood, and properly reviewed by your peers - and maintained by anyone!

Installation and Usage

npm i super-expressive

const SuperExpressive = require('super-expressive');

Example

The following example recognises and captures the value of a 16-bit hexadecmal number like 0xC0D3 .

const SuperExpressive = require('super-expressive');

const myRegex = SuperExpressive()
  .startOfInput
  .optional.string('0x')
  .capture
    .exactly(4).anyOf
      .range('A', 'F')
      .range('a', 'f')
      .range('0', '9')
    .end()
  .end()
  .endOfInput
  .toRegex();

// Produces the following regular expression:
/^(?:0x)?([A-Fa-f0-9]{4})$/

API

SuperExpressive()

SuperExpressive()

Creates an instance of SuperExpressive .

.allowMultipleMatches

Uses the g flag on the regular expression, which indicates that it should match multiple values when run on a string.

Example

SuperExpressive()
  .allowMultipleMatches
  .string('hello')
  .toRegex();
// ->
/hello/g

.lineByLine

Uses the m flag on the regular expression, which indicates that it should treat theandmarkers as the start and end of lines.

Example

SuperExpressive()
  .lineByLine
  .string('^hello$')
  .toRegex();
// ->
/\^hello\$/m

.caseInsensitive

Uses the i flag on the regular expression, which indicates that it should treat ignore the uppercase/lowercase distinction when matching.

Example

SuperExpressive()
  .caseInsensitive
  .string('HELLO')
  .toRegex();
// ->
/HELLO/i

.sticky

Uses the y flag on the regular expression, which indicates that it should create a stateful regular expression that can be resumed from the last match.

Example

SuperExpressive()
  .sticky
  .string('hello')
  .toRegex();
// ->
/hello/y

.unicode

Uses the u flag on the regular expression, which indicates that it should use full unicode matching.

Example

SuperExpressive()
  .unicode
  .string('héllo')
  .toRegex();
// ->
/héllo/u

.singleLine

Uses the s flag on the regular expression, which indicates that the input should be treated as a single line, where theandmarkers explicitly mark the start and end of input, andalso matches newlines.

Example

SuperExpressive()
  .singleLine
  .string('hello')
  .anyChar
  .string('world')
  .toRegex();
// ->
/hello.world/s

.anyChar

Matches any single character. When combined with, it also matches newlines.

Example

SuperExpressive()
  .anyChar
  .toRegex();
// ->
/./

.whitespaceChar

Matches any whitespace character, including the special whitespace characters: \r\n\t\f\v .

Example

SuperExpressive()
  .whitespaceChar
  .toRegex();
// ->
/\s/

.nonWhitespaceChar

Matches any non-whitespace character, excluding also the special whitespace characters: \r\n\t\f\v .

Example

SuperExpressive()
  .nonWhitespaceChar
  .toRegex();
// ->
/\S/

.digit

Matches any digit from 0-9 .

Example

SuperExpressive()
  .digit
  .toRegex();
// ->
/\d/

.nonDigit

Matches any non-digit.

Example

SuperExpressive()
  .nonDigit
  .toRegex();
// ->
/\D/

.word

Matches any alpha-numeric ( a-z, A-Z, 0-9 ) characters, as well as _ .

Example

SuperExpressive()
  .word
  .toRegex();
// ->
/\w/

.nonWord

Matches any non alpha-numeric ( a-z, A-Z, 0-9 ) characters, excluding _ as well.

Example

SuperExpressive()
  .nonWord
  .toRegex();
// ->
/\W/

.wordBoundary

Matches (without consuming any characters) immediately between a character matched byand a character not matched by(in either order).

Example

SuperExpressive()
  .digit
  .wordBoundary
  .toRegex();
// ->
/\d\b/

.nonWordBoundary

Matches (without consuming any characters) at the position between two characters matched by.

Example

SuperExpressive()
  .digit
  .nonWordBoundary
  .toRegex();
// ->
/\d\B/

.newline

Matches a \n character.

Example

SuperExpressive()
  .newline
  .toRegex();
// ->
/\n/

.carriageReturn

Matches a \r character.

Example

SuperExpressive()
  .carriageReturn
  .toRegex();
// ->
/\r/

.tab

Matches a \t character.

Example

SuperExpressive()
  .tab
  .toRegex();
// ->
/\t/

.nullByte

Matches a \u0000 character (ASCII 0 ).

Example

SuperExpressive()
  .nullByte
  .toRegex();
// ->
/\0/

.anyOf

Matches a choice between specified elements. Needs to be finalised with .end() .

Example

SuperExpressive()
  .anyOf
    .range('a', 'f')
    .range('0', '9')
    .string('XXX')
  .end()
  .toRegex();
// ->
/(?:XXX|[a-f0-9])/

.capture

Creates a capture group for the proceeding elements. Needs to be finalised with .end() . Can be later referenced with.

Example

SuperExpressive()
  .capture
    .range('a', 'f')
    .range('0', '9')
    .string('XXX')
  .end()
  .toRegex();
// ->
/([a-f][0-9]XXX)/

.namedCapture(name)

Creates a named capture group for the proceeding elements. Needs to be finalised with .end() . Can be later referenced withnamedBackreference(name)or.

Example

SuperExpressive()
  .namedCapture('interestingStuff')
    .range('a', 'f')
    .range('0', '9')
    .string('XXX')
  .end()
  .toRegex();
// ->
/(?<interestingStuff>[a-f][0-9]XXX)/

.namedBackreference(name)

Matches exactly what was previously matched by a.

Example

SuperExpressive()
  .namedCapture('interestingStuff')
    .range('a', 'f')
    .range('0', '9')
    .string('XXX')
  .end()
  .string('something else')
  .namedBackreference('interestingStuff')
  .toRegex();
// ->
/(?<interestingStuff>[a-f][0-9]XXX)something else\k<interestingStuff>/

.backreference(index)

Matches exactly what was previously matched by aorusing a positional index. Note regex indexes start at 1, so the first capture group has index 1.

Example

SuperExpressive()
  .capture
    .range('a', 'f')
    .range('0', '9')
    .string('XXX')
  .end()
  .string('something else')
  .backreference(1)
  .toRegex();
// ->
/([a-f][0-9]XXX)something else\1/

.group

Creates a non-capturing group of the proceeding elements. Needs to be finalised with .end() .

Example

SuperExpressive()
  .optional.group
    .range('a', 'f')
    .range('0', '9')
    .string('XXX')
  .end()
  .toRegex();
// ->
/(?:[a-f][0-9]XXX)?/

.end()

Signifies the end of a SuperExpressive grouping, such as,, or.

Example

SuperExpressive()
  .capture
    .anyOf
      .range('a', 'f')
      .range('0', '9')
      .string('XXX')
    .end()
  .end()
  .toRegex();
// ->
/((?:XXX|[a-f0-9]))/

.assertAhead

Assert that the proceeding elements are found without consuming them. Needs to be finalised with .end() .

Example

SuperExpressive()
  .assertAhead
    .range('a', 'f')
  .end()
  .range('a', 'z')
  .toRegex();
// ->
/(?=[a-f])[a-z]/

.assertNotAhead

Assert that the proceeding elements are not found without consuming them. Needs to be finalised with .end() .

Example

SuperExpressive()
  .assertNotAhead
    .range('a', 'f')
  .end()
  .range('g', 'z')
  .toRegex();
// ->
/(?![a-f])[g-z]/

.optional

Assert that the proceeding element may or may not be matched.

Example

SuperExpressive()
  .optional.digit
  .toRegex();
// ->
/\d?/

.zeroOrMore

Assert that the proceeding element may not be matched, or may be matched multiple times.

Example

SuperExpressive()
  .zeroOrMore.digit
  .toRegex();
// ->
/\d*/

.zeroOrMoreLazy

Assert that the proceeding element may not be matched, or may be matched multiple times, but as few times as possible.

Example

SuperExpressive()
  .zeroOrMoreLazy.digit
  .toRegex();
// ->
/\d*?/

.oneOrMore

Assert that the proceeding element may be matched once, or may be matched multiple times.

Example

SuperExpressive()
  .oneOrMore.digit
  .toRegex();
// ->
/\d+/

.oneOrMoreLazy

Assert that the proceeding element may be matched once, or may be matched multiple times, but as few times as possible.

Example

SuperExpressive()
  .oneOrMoreLazy.digit
  .toRegex();
// ->
/\d+?/

.exactly(n)

Assert that the proceeding element will be matched exactly n times.

Example

SuperExpressive()
  .exactly(5).digit
  .toRegex();
// ->
/\d{5}/

.atLeast(n)

Assert that the proceeding element will be matched at least n times.

Example

SuperExpressive()
  .atLeast(5).digit
  .toRegex();
// ->
/\d{5,}/

.between(x, y)

Assert that the proceeding element will be matched somewhere between x and y times.

Example

SuperExpressive()
  .between(3, 5).digit
  .toRegex();
// ->
/\d{3,5}/

.betweenLazy(x, y)

Assert that the proceeding element will be matched somewhere between x and y times, but as few times as possible.

Example

SuperExpressive()
  .betweenLazy(3, 5).digit
  .toRegex();
// ->
/\d{3,5}?/

.startOfInput

Assert the start of input, or the start of a line whenis used.

Example

SuperExpressive()
  .startOfInput
  .string('hello')
  .toRegex();
// ->
/^hello/

.endOfInput

Assert the end of input, or the end of a line whenis used.

Example

SuperExpressive()
  .string('hello')
  .endOfInput
  .toRegex();
// ->
/end$/

.anyOfChars(chars)

Matches any of the characters in the provided string chars .

Example

SuperExpressive()
  .anyOfChars('aeiou')
  .toRegex();
// ->
/[aeiou]/

.anythingButChars(chars)

Matches any character, except any of those in the provided string chars .

Example

SuperExpressive()
  .anythingButChars('aeiou')
  .toRegex();
// ->
/[^aeiou]/

.anythingButString(str)

Matches any string the same length as str , except the characters sequentially defined in str .

Example

SuperExpressive()
  .anythingButString('aeiou')
  .toRegex();
// ->
/(?:[^a][^e][^i][^o][^u])/

.anythingButRange(a, b)

Matches any character, except those that would be captured by thespecified by a and b .

Example

SuperExpressive()
  .anythingButRange(0, 9)
  .toRegex();
// ->
/[^0-9]/

.string(s)

Matches the exact string s .

Example

SuperExpressive()
  .string('hello')
  .toRegex();
// ->
/hello/

.char(c)

Matches the exact character c .

Example

SuperExpressive()
  .char('x')
  .toRegex();
// ->
/x/

.range(a, b)

Matches any character that falls between a and b . Ordering is defined by a characters ASCII or unicode value.

Example

SuperExpressive()
  .range('a', 'z')
  .toRegex();
// ->
/[a-z]/

.toRegexString()

Outputs a string representation of the regular expression that this SuperExpression models.

Example

SuperExpressive()
  .allowMultipleMatches
  .lineByLine
  .startOfInput
  .optional.string('0x')
  .capture
    .exactly(4).anyOf
      .range('A', 'F')
      .range('a', 'f')
      .range('0', '9')
    .end()
  .end()
  .endOfInput
  .toRegexString();
// ->
"/^(?:0x)?([A-Fa-f0-9]{4})$/gm"

.toRegex()

Outputs the regular expression that this SuperExpression models.

Example

SuperExpressive()
  .allowMultipleMatches
  .lineByLine
  .startOfInput
  .optional.string('0x')
  .capture
    .exactly(4).anyOf
      .range('A', 'F')
      .range('a', 'f')
      .range('0', '9')
    .end()
  .end()
  .endOfInput
  .toRegexString();
// ->
/^(?:0x)?([A-Fa-f0-9]{4})$/gm