francisrstokes/super-expressive francisrstokes/super-expressive

  • Stars
    star
    4,464
  • Rank 9,178 (Top 0.2 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created almost 4 years ago
  • Updated about 1 year ago
Twitter logo Share LinkedIn logo Share Facebook logo Share
francisrstokes/super-expressive
github

francisrstokes

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

๐Ÿฆœ Super Expressive is a zero-dependency JavaScript library for building regular expressions in (almost) natural language

Super Expressive

Super Expressive Logo

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

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
  • subexpressions can be used to create meaningful, reusable components
  • includes an index.d.ts file for full TypeScript support

SuperExpressive 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!

Installation and Usage

npm i super-expressive

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

// Or as an ES6 module
import SuperExpressive from 'super-expressive';

Example

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})$/

Playground

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.

Ports

Super Expressive has been ported to the following languages:

PHP

https://github.com/bassim/super-expressive-php by @bassim

Ruby

https://github.com/hiy/super-expressive-ruby by @hiy

Python

https://github.com/stanislav-tsaplev/super_expressive by @stanislav-tsaplev

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/

.verticalTab

Matches a \v character.

Example

SuperExpressive()
  .verticalTab
  .toRegex();
// ->
/\v/

.formFeed

Matches a \f character.

Example

SuperExpressive()
  .formFeed
  .toRegex();
// ->
/\f/

.backspace

Matches a \b character.

Example

SuperExpressive()
  .backspace
  .toRegex();
// ->
/[\b]/

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

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 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>/

.backreference(index)

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/

.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]/

.assertBehind

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/

.assertNotBehind

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/

.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();
// ->
/hello$/

.anyOfChars(chars)

Matches any of the characters in the provided string chars.

Example

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

.anythingBut

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])/

.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/

.controlChar(c)

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/

.hexCode(hex)

Matches a character with the code hex, where hex is a 2 dogit hexadecimal string.

Example

SuperExpressive()
  .hexCode('2A')
  .toRegex();
// ->
/\x2A/

.utf16Code(hex)

Matches a UTF-16 code unit with the code hex, where hex is a 4 digit hexadecimal string.

Example

SuperExpressive()
  .utf16Code('002A')
  .toRegex();
// ->
/\u002A/

.unicodeCharCode(hex)

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

.range(a, b)

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?)

  • opts.namespace: A string namespace to use on all named capture groups in the subexpression, to avoid naming collisions with your own named groups (default = '')
  • opts.ignoreFlags: If set to true, any flags this subexpression specifies should be disregarded (default = true)
  • opts.ignoreStartAndEnd: If set to true, any startOfInput/endOfInput asserted in this subexpression specifies should be disregarded (default = 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}/

.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
  .toRegex();
// ->
/^(?:0x)?([A-Fa-f0-9]{4})$/gm

More Repositories

1

construct-js

๐Ÿ› ๏ธA library for creating byte level data structures.
TypeScript
1,349
star
2

arcsecond

โœจZero Dependency Parser Combinator Library for JS Based on Haskell's Parsec
TypeScript
500
star
3

16bitjs

๐Ÿ’ป A 16-bit virtual machine, including assembly language with 37 instructions, binary assembler, and a step through debugger
JavaScript
470
star
4

githublog

I'm sick of complex blogging solutions, so markdown files in a git repo it is
338
star
5

tega

๐Ÿ•น TypeScript Embedded GameBoy Macro Assembler
TypeScript
227
star
6

hexnut

๐Ÿ”ฉ Hexnut is a middleware based, express/koa like framework for web sockets
JavaScript
208
star
7

React-Machinery

๐Ÿ”ฅ React Machinery provides a simple to use, component based approach to state machines in react.
JavaScript
105
star
8

vec-la

Tiny linear algebra library specifically for 2d
JavaScript
41
star
9

bewitched

๐Ÿง™๐Ÿป Command line hex editor
TypeScript
35
star
10

Lazy-Infinite-List

๐Ÿ—’๏ธ A Fantasy Land compliant Infinite List Data Structure
JavaScript
26
star
11

tiny-c-projects

A collection of small C projects - usually a minimal example of something interesting
C
25
star
12

vmfc

Stack-based VM Architecture in JavaScript. (Virtual Machine Fantasy Console)
JavaScript
23
star
13

vec-la-fp

โ†—๏ธ A tiny (functional) 2d linear algebra library
JavaScript
22
star
14

arcsecond-binary

Binary parsers for arcsecond!
JavaScript
19
star
15

GMMK-Driver

An open source, reverse engineered control driver for the GMMK mechanical keyboard
TypeScript
19
star
16

AES-C

A (non-production) implementation of AES for educational purposes
C
14
star
17

teensy-nes

NES Emulator on a Teensy 4.1
C++
8
star
18

hexnut-client

JavaScript
8
star
19

trump-chain

JavaScript
8
star
20

kandinsky-js

๐ŸŒˆA tiny colour library
JavaScript
7
star
21

Classiest

๐Ÿธ Create classier classes with overloadable methods, getters, setters, and statics!
JavaScript
7
star
22

ebpf-usb

A tool for monitoring (specific) USB devices
Python
6
star
23

super-expressive-fp

SuperExpressive, but with a wrapped API for functional programming
JavaScript
6
star
24

Image-Glitcher

๐Ÿ’ข Generates glitchy GIFs from JPEGs
JavaScript
5
star
25

rustack-machine

A simple stack machine in rust
Rust
5
star
26

bito

B.I.T.O - Programatic Beats Code Golfed In Your Browser
JavaScript
5
star
27

Steganography-C

Steganographic encoding implementation for hiding data in images
C
4
star
28

ATmega328P-Bare-Metal-Task-Switching

๐ŸŽ– A minimal implementation of a task-switching kernel in C for the ATmega328P chip
C
4
star
29

hexnut-sequence

Sequencing middleware for the HexNut framework
JavaScript
3
star
30

hexnut-handle

Simple hexnut middleware for dealing with connections and messages
JavaScript
3
star
31

algebraic-types

JavaScript
3
star
32

SpelBoy

A GameBoy (DMG) emulator written in TypeScript
TypeScript
3
star
33

modular-animation-synthesizer

https://francisrstokes.github.io/modular-animation-synthesizer/
JavaScript
3
star
34

frame-http

๐Ÿ–ผ๏ธLaughably minimal http framework combining the best parts of express and koa
JavaScript
3
star
35

ElessarOS

risc-v OS inspired by xv6
C
2
star
36

Brainfuck-Interpreter

Brainfuck interpreter using Jison
JavaScript
2
star
37

SNES-Controller-Arduino-Leonardo

Turn the SNES controller into a USB controller for use with an emulator
C++
2
star
38

lazy-do

Fantasy Land compliant do notation for lazy structures ๐Ÿฆ„
JavaScript
2
star
39

zig-expressions

A regular expression engine written in Zig
Zig
2
star
40

readme-cli

๐Ÿ“– A CLI tool for rendering npm/github README files in the terminal
JavaScript
2
star
41

microcan

JavaScript
2
star
42

simple-transduce

A really simple transducer module to easily convert map-filter-reduce chains to single pass transducers.
JavaScript
2
star
43

creative-code-toolkit-fp

JavaScript
2
star
44

aoc-2023

Zig
1
star
45

WaveStrider

CMake
1
star
46

lambda-lang

JavaScript
1
star
47

hexnut-bodyparser

JavaScript
1
star
48

hexnut-restore-connection

HexNut middleware to restore a lost connection
JavaScript
1
star
49

app-and-bootloader

Simple app and bootloader implementation for STM32 using libopencm3
Makefile
1
star
50

salsa20-on-rp2040

My entry for LLJam0001: Salsa20 hardware encryption device using a Raspberry Pi Pico
C
1
star
51

bus-pirate

Bus Pirate integration for TS and JS
TypeScript
1
star
52

microcan-fp

JavaScript
1
star
53

riscv-gateware-ts

A RISC-V processor with gateware-ts
TypeScript
1
star
54

primer-js

๐Ÿ•ฐ A tiny (474 bytes minified + gzipped) library for creating normalised, unit independent timelines
JavaScript
1
star
55

zig-stm32-bare-metal

Minimal zig code to blink a LED for the STM32F401RE chip
Zig
1
star
56

Jazz-Chordr

Memorise common jazz chords https://francisrstokes.github.io/Jazz-Chordr/
JavaScript
1
star
57

Hindley-Milner-Parser

A Hindley-Milner type signature parser in haskell
Haskell
1
star
58

hexnut-with-observable

A Hexnut middleware for integrating with rxjs
JavaScript
1
star
59

gibson-engine

A minimalist text game (interactive fiction) engine
JavaScript
1
star
60

Redux-State-Resolver

๐Ÿ’กCleanly resolve a sequence of dependencies - write component logic that can assume the state has what it needs.
JavaScript
1
star
61

x86_64-Userspace-Emulator

C
1
star
62

hexnut-router

Routing middleware for HexNut
JavaScript
1
star
63

c-proj-init

A script to generate a skeleton C project, with a minimal Makefile and vscode debugging
JavaScript
1
star
64

autonotyper

An automatic typing engine tht can be plugged into anything
JavaScript
1
star
65

4FVM

Spiritual successor to 16bitJS
JavaScript
1
star