Super Expressive is 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 4kb with minification + gzip!).
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)index.d.ts file for full TypeScript supportSuperExpressive turns those complex and unwieldy regexes that appear in code reviews into something that can be read, understood, and properly reviewed by your peers - and maintained by anyone!
const SuperExpressive = require('super-expressive');
// Or as an ES6 module
import SuperExpressive from 'super-expressive';
The following example recognises and captures the value of a 16-bit hexadecimal 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})$/
You can experiment with SuperExpressive in the Super Expressive Playground by @nartc. This is a great way to build a regex description, and test it against various inputs.
Super Expressive has been ported to the following languages:
https://github.com/bassim/super-expressive-php by @bassim
https://github.com/hiy/super-expressive-ruby by @hiy
https://github.com/stanislav-tsaplev/super_expressive by @stanislav-tsaplev
SuperExpressive()
Creates an instance of SuperExpressive.
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
Uses the m flag on the regular expression, which indicates that it should treat the .startOfInput and .endOfInput markers as the start and end of lines.
Example
SuperExpressive()
.lineByLine
.string('^hello$')
.toRegex();
// ->
/\^hello\$/m
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
Uses the d flag on the regular expression, which indicates that it should generate indices for the start and end of each capture group.
Example
SuperExpressive()
.generateIndices
.string('hello')
.toRegex();
// ->
/hello/d
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
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
Uses the s flag on the regular expression, which indicates that the input should be treated as a single line, where the .startOfInput and .endOfInput markers explicitly mark the start and end of input, and .anyChar also matches newlines.
Example
SuperExpressive()
.singleLine
.string('hello')
.anyChar
.string('world')
.toRegex();
// ->
/hello.world/s
Matches any single character. When combined with .singleLine, it also matches newlines.
Example
SuperExpressive() .anyChar .toRegex(); // -> /./
Matches any whitespace character, including the special whitespace characters: \r\n\t\f\v.
Example
SuperExpressive() .whitespaceChar .toRegex(); // -> /\s/
Matches any non-whitespace character, excluding also the special whitespace characters: \r\n\t\f\v.
Example
SuperExpressive() .nonWhitespaceChar .toRegex(); // -> /\S/
Matches any digit from 0-9.
Example
SuperExpressive() .digit .toRegex(); // -> /\d/
Matches any non-digit.
Example
SuperExpressive() .nonDigit .toRegex(); // -> /\D/
Matches any alpha-numeric (a-z, A-Z, 0-9) characters, as well as _.
Example
SuperExpressive() .word .toRegex(); // -> /\w/
Matches any non alpha-numeric (a-z, A-Z, 0-9) characters, excluding _ as well.
Example
SuperExpressive() .nonWord .toRegex(); // -> /\W/
Matches (without consuming any characters) immediately between a character matched by .word and a character not matched by .word (in either order).
Example
SuperExpressive() .digit .wordBoundary .toRegex(); // -> /\d\b/
Matches (without consuming any characters) at the position between two characters matched by .word.
Example
SuperExpressive() .digit .nonWordBoundary .toRegex(); // -> /\d\B/
Matches a \n character.
Example
SuperExpressive() .newline .toRegex(); // -> /\n/
Matches a \r character.
Example
SuperExpressive() .carriageReturn .toRegex(); // -> /\r/
Matches a \t character.
Example
SuperExpressive() .tab .toRegex(); // -> /\t/
Matches a \v character.
Example
SuperExpressive() .verticalTab .toRegex(); // -> /\v/
Matches a \f character.
Example
SuperExpressive() .formFeed .toRegex(); // -> /\f/
Matches a \b character.
Example
SuperExpressive() .backspace .toRegex(); // -> /[\b]/
Matches a \u0000 character (ASCII 0).
Example
SuperExpressive() .nullByte .toRegex(); // -> /\0/
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])/
Creates a capture group for the proceeding elements. Needs to be finalised with .end(). Can be later referenced with backreference(index).
Example
SuperExpressive()
.capture
.range('a', 'f')
.range('0', '9')
.string('XXX')
.end()
.toRegex();
// ->
/([a-f][0-9]XXX)/
Creates a named capture group for the proceeding elements. Needs to be finalised with .end(). Can be later referenced with namedBackreference(name) or backreference(index).
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 namedCapture.
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>/
Matches exactly what was previously matched by a capture or namedCapture using 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/
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)?/
Signifies the end of a SuperExpressive grouping, such as .anyOf, .group, or .capture.
Example
SuperExpressive()
.capture
.anyOf
.range('a', 'f')
.range('0', '9')
.string('XXX')
.end()
.end()
.toRegex();
// ->
/((?:XXX|[a-f0-9]))/
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]/
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]/
Assert that the elements contained within are found immediately before this point in the string. Needs to be finalised with .end().
Example
SuperExpressive()
.assertBehind
.string('hello ')
.end()
.string('world')
.toRegex();
// ->
/(?<=hello )world/
Assert that the elements contained within are not found immediately before this point in the string. Needs to be finalised with .end().
Example
SuperExpressive()
.assertNotBehind
.string('hello ')
.end()
.string('world')
.toRegex();
// ->
/(?<!hello )world/
Assert that the proceeding element may or may not be matched.
Example
SuperExpressive() .optional.digit .toRegex(); // -> /\d?/
Assert that the proceeding element may not be matched, or may be matched multiple times.
Example
SuperExpressive() .zeroOrMore.digit .toRegex(); // -> /\d*/
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*?/
Assert that the proceeding element may be matched once, or may be matched multiple times.
Example
SuperExpressive() .oneOrMore.digit .toRegex(); // -> /\d+/
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+?/
Assert that the proceeding element will be matched exactly n times.
Example
SuperExpressive()
.exactly(5).digit
.toRegex();
// ->
/\d{5}/
Assert that the proceeding element will be matched at least n times.
Example
SuperExpressive()
.atLeast(5).digit
.toRegex();
// ->
/\d{5,}/
Assert that the proceeding element will be matched at least n times, but as few times as possible.
Example
SuperExpressive()
.atLeastLazy(5).digit
.toRegex();
// ->
/\d{5,}?/
Assert that the proceeding element will be matched somewhere between x and y times.
Example
SuperExpressive()
.between(3, 5).digit
.toRegex();
// ->
/\d{3,5}/
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}?/
Assert the start of input, or the start of a line when .lineByLine is used.
Example
SuperExpressive()
.startOfInput
.string('hello')
.toRegex();
// ->
/^hello/
Assert the end of input, or the end of a line when .lineByLine is used.
Example
SuperExpressive()
.string('hello')
.endOfInput
.toRegex();
// ->
/hello$/
Matches any of the characters in the provided string chars.
Example
SuperExpressive()
.anyOfChars('aeiou')
.toRegex();
// ->
/[aeiou]/
Matches any character, except those that match any of the specified elements. Needs to be finalised with .end().
Example
SuperExpressive()
.anythingBut
.digit
.range('a','z')
.string('XXX')
.end()
.toRegex();
// ->
/(?:(?!XXX)[^\da-z])/
Matches any character, except any of those in the provided string chars.
Example
SuperExpressive()
.anythingButChars('aeiou')
.toRegex();
// ->
/[^aeiou]/
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])/
Matches any character, except those that would be captured by the .range specified by a and b.
Example
SuperExpressive() .anythingButRange(0, 9) .toRegex(); // -> /[^0-9]/
Matches the exact string s.
Example
SuperExpressive()
.string('hello')
.toRegex();
// ->
/hello/
Matches the exact character c.
Example
SuperExpressive()
.char('x')
.toRegex();
// ->
/x/
Matches a control character using carat notation (Ctrl^c) where c is a single latin letter from A-Z.
Example
SuperExpressive()
.controlChar('J')
.toRegex();
// ->
/\cJ/
Matches a character with the code hex, where hex is a 2 dogit hexadecimal string.
Example
SuperExpressive()
.hexCode('2A')
.toRegex();
// ->
/\x2A/
Matches a UTF-16 code unit with the code hex, where hex is a 4 digit hexadecimal string.
Example
SuperExpressive()
.utf16Code('002A')
.toRegex();
// ->
/\u002A/
Matches a Unicode character code with the value hex, where hex is a 4 or 5 digit hexadecimal string. Implicitly enables the u flag on the regular expression.
Example
SuperExpressive()
.unicodeCharCode('0002A')
.toRegex();
// ->
/\u{0002A}/u .unicodeProperty(property)
Matches a Unicode character with the given Unicode property. See the MDN Docs for valid properties. Implicitly enables the u flag on the regular expression.
Example
SuperExpressive()
.unicodeProperty('Script=Latin')
.toRegex();
// ->
/\p{Script=Latin}/u .notUnicodeProperty(property)
Matches a Unicode character without the given Unicode property. See the MDN Docs for valid properties. Implicitly enables the u flag on the regular expression.
Example
SuperExpressive()
.notUnicodeProperty('Script=Latin')
.toRegex();
// ->
/\P{Script=Latin}/u
Matches any character that falls between a and b. Ordering is defined by a characters ASCII or unicode value. The u flag is automatically enabled if either a or b are unicode characters larger than 2 bytes.
Example
SuperExpressive()
.range('a', 'z')
.range('\u{1F600}', '\u{1F606}')
.toRegex();
// ->
/[a-z][😀-😆]/u .subexpression(expr, opts?)
'')true)true)Matches another SuperExpressive instance inline. Can be used to create libraries, or to modularise you code. By default, flags and start/end of input markers are ignored, but can be explcitly turned on in the options object.
Example
// A reusable SuperExpressive...
const fiveDigits = SuperExpressive().exactly(5).digit;
SuperExpressive()
.oneOrMore.range('a', 'z')
.atLeast(3).anyChar
.subexpression(fiveDigits)
.toRegex();
// ->
/[a-z]+.{3,}\d{5}/
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"
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
.toRegex();
// ->
/^(?:0x)?([A-Fa-f0-9]{4})$/gm
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.3