🦜 Super Expressive is a zero-dependency JavaScript library for building regular expressions in (almost) natural language

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 3kb with minification + gzip!).

Information

Category: JavaScript / RegExp
Watchers: 11
Star: 433
Fork: 6
Last update: Jul 16, 2020

Resource links

https://github.com/francisrstokes/super-expressive

README
Issues 9

Super Expressive

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 3kb with minification + gzip!).

Why
Installation and Usage
Example
API
Click to expand

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:

properties and methods describe what they do in plain English
order matters! quantifiers are specified before the thing they change, just like in English (e.g. SuperExpressive().exactly(5).digit)
if you make a mistake, you'll know how to fix it. SuperExpressive will guide you towards a fix if your expression is invalid

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 the .startOfInput and .endOfInput markers 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 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

.anyChar

Matches any single character. When combined with .singleLine, 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 by .word and a character not matched by .word (in either order).

Example

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

.nonWordBoundary

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

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().

Example

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

.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 .anyOf, .group, or .capture.

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 when .lineByLine is used.

Example

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

.endOfInput

Assert the end of input, or the end of a line when .lineByLine is 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 the .range specified 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

1 Open More issues

Closed

Is there a way of compiling regex at build time.

I'm one of those people who avoids regex at all times because of it's readability issues, but I love its conciseness.

From the readme is appears that this library is runtime only, but I was wondering if there could be a way of compiling into regex for production to combine the best of both worlds?

opened Nov 14, 2020 by MattyBalaam 6

Closed

Proposal: include support for plugins

It would be nice to support user-definable plugins, i.e. "Phone Number"

Something like:

const myRegex = SuperExpressive({ plugins: [ phoneNumber ] })
  .startOfInput
  .optional.string('0x')
  .capture
    .exactly(4).group
      .plugin.phoneNumber()
      .newline
    .end()
  .end()
  .endOfInput
  .toRegex();

opened Jul 17, 2020 by jcao219 6

Closed

Type declarations

I created index.d.ts with JSDoc annotations copied directly from the README. It enables ES6-style default importing of SuperExpressive, which can then be used the normal way.

opened Jul 16, 2020 by jimmyaffatigato 6

Closed

lookBehind API missing from playground

The docs mention assertBehind and assertNotBenind but they don't work in the playground.

Also, JS didn't used to support lookBehind, only lookAhead - might be worth documenting when this changed?

opened Jan 21, 2021 by chris-findlay 5

Closed

Porting for Ruby

Hi. Thank you for the wonderful library!

I usually write programs using Ruby. So I made a port for Ruby so that I can use super-expressive in Ruby as well. If you don't mind, I would like to publish a super-expressive for Ruby. Is that okay?

opened Oct 26, 2020 by hiy 3

Closed

Why not support plural form?

In addition to

SuperExpressive().exactly(5).digit

why not support

SuperExpressive().exactly(5).digits

opened Jul 17, 2020 by kalmanh 3

Open

incomplete *Lazy coverage

While you have covered all variants of {,}, including * and +, the lazy alternatives are missing for exactly and atLeast.

opened Jan 21, 2021 by chris-findlay 2

Open

Compare with similar libraries

VerbalExpressions is a library that's been around for a long time, with a lot of stars and a lot of ports, but there are reasons to choose SuperExpressive instead:

VerbalExpressions are incompatible with Promises and Async/Await, because they contain a non-compliant .then() method. If you return a verbal expression from a promise, it's not going to behave as expected.
No support for various regular expression features:
- non-capturing groups
- named groups
- backreferences
- lookaheads
- etc
No support for sub expressions, so creating reusable parts is not possible
VerbalExpressions are mutable, so creating a new expression based on an existing one is not possible (see example below)

expr.maybe('s');
const expr2 = expr.maybe('t');

// expr is now: expr.maybe('s').maybe('t')

opened Aug 11, 2020 by francisrstokes 0

Open

Expand documentation with examples section

To aid in showing how Super Expressive can be used in a practical context, it would be nice add an examples folder, with various common regex use cases.

[ ] Using string.replace (#5)
[ ] Using string.match to capture information
- [ ] Indexed groups
- [ ] Named groups
[ ] Code organisation with subexpressions

Each example should be a separate .md document, with a title, short introduction, some commented example code, and related links sections (to things like MDN, or regex101). The examples folder should contain an index.md that acts as the contents page - linking to each example with a one sentence description.

opened Jul 25, 2020 by francisrstokes 0

super-expressive-php is a php library that allows you to build regular expressions in almost natural language

Code for the paper Neural Generation of Regular Expressions from Natural Language with Minimal Domain Knowledge (EMNLP 2016). http://arxiv.org/abs/1608.03000

A simple take on regular expressions for beginners

RegexGen.js is a JavaScript Regular Expression Generator that helps to construct complex regular expressions.

C++ regular expressions made easy

A library that provides regular expression patterns. If you hate to write regular expressions, then expynent can help you.

regex — Regular expressions (RE2 style)

🍫 A collection of common regular expressions for Go

rusty_hogs - This project provides a set of scanners that will use regular expressions to try and detect the presence of sensitive information such as API keys, passwords, and personal information. It includes a set of regular expressions by default, but will also accept a JSON object containing your custom regular expressions.

Regular expressions matching at compile time with TypeScript

"Natural" is a general natural language facility for nodejs.

SecretFinder - A python script for find sensitive data (apikeys, accesstoken,jwt,..) and search anything on javascript files

Java regular expressions made easy.

inspired by regular expressions but can do nested structures

Explore, test, and check regular expressions in the terminal.

Friendly Interactive Shell and Expressive Programming Language

Serialize JavaScript to a superset of JSON that includes regular expressions and functions.

Search Git commits in natural language

UDapter is a multilingual dependency parser that uses "contextual" adapters together with language-typology features for language-specific adaptation. This repository includes the code for "UDapter: Language Adaptation for Truly Universal Dependency Parsing"

Düzenli ifadeler (Regular Expressions | #Regex) Nedir? Nasıl Kullanılır? #JavaScript ile Regex

Extended JavaScript regular expressions

Share this repo

Related Repos

RegExp

LogRegex allows you to find patterns inside of logs

LogRegex LogRegex allows you to find patterns inside of logs. Let's jump right into an example: import { FileHandler, LogRegex, Matcher } from "./inde

RegExp

3.1k

Extended JavaScript regular expressions

XRegExp 5.1.0 XRegExp provides augmented (and extensible) JavaScript regular expressions. You get modern syntax and flags beyond what browsers support

RegExp

1.9k

Learn RegEx step by step, from zero to advanced.

RegExp

Jōyō kanji hyō (List of regular-use Han characters in Japan)

常用漢字表常用漢字表（平成22年内閣告示第2号）のPDFから本表を抽出し、JSON形式に変換したものです。著作権について著作権法第十三条の二において、国が発する告示は、著作権法第二章の規定による権利の目的となることができない旨が定められています。 e-gov 法令検索著作権法データ抽出プロ

RegExp

Make Regular Expressions More Exciting

NOTE: This is a toy package created for expository purposes, for the second edition of R Packages. It is not meant to actually be useful. If you want

RegExp

A DSL that translates to regex

luna No more regrets, wield the power of regex with the readability of English with luna. About luna is a Domain specific language (DSL) that is reada

RegExp

Add context awareness to your apps and frameworks by safely evaluating user-defined condit...

whence Add context awareness to your apps and frameworks by safely evaluating user-defined conditional expressions. Useful for evaluating expressions

RegExp

A typescript library for type-safe regex for named capture groups

A typescript library for writing type-safe regular expressions using named capture groups.

RegExp

A robust and light-weight path-to-regexp alternative

@egoist/path-parser This module is entirely extracted from vue-router, it's basically a light-weight version of path-to-regexp with path ranking suppo

RegExp

A regular expression pattern for Java/JavaScript to match all emoji in the emoji-test.txt ...

emoji-test-regex-pattern emoji-test-regex-pattern offers Java- and JavaScript-compatible regular expression patterns to match all emoji symbols and se

RegExp

1.3k

A curated collection of awesome Regex libraries, tools, frameworks and software

RegExp

Cron UI: Input component to generate cron expressions easily and intuitively

Cron Expression Input Description Cron Expression UI: Input component to generate cron expressions easily and intuitively, as in https://crontab.guru/

RegExp

433

🦜 Super Expressive is a zero-dependency JavaScript library for building regular expressio...

RegExp

166

The magical sticky regex-based parser generator 🧙

RegExp

3.7k

The code for iHateregex.io 😈 - The Regex Cheat Sheet

iHateRegex 😈 don't just use; understand. iHateRegex.io - a regex cheatsheet for the haters. Chat with us on Telegram Features 😎 Visual representation of