____            _____            ____        _ _     _              _ ____  
|  _ \ ___  __ _| ____|_  ___ __ | __ ) _   _(_) | __| | ___ _ __   | / ___| 
| |_) / _ \/ _` |  _| \ \/ / '_ \|  _ \| | | | | |/ _` |/ _ \ '__|  | \___ \ 
|  _ <  __/ (_| | |___ >  <| |_) | |_) | |_| | | | (_| |  __/ | | |_| |___) |
|_| \_\___|\__, |_____/_/\_\ .__/|____/ \__,_|_|_|\__,_|\___|_|  \___/|____/ 
           |___/           |_|                                                                  

• Install
• Examples
• Documentation

Human-readable regular expressions for JavaScript

JavaScript port of regexpbuilderphp (which was a port of regexpbuilder, which is now gone). All credit goes to Andrew Jones and Max Girkens.

RegExpBuilder integrates regular expressions into the programming language, thereby making them easy to read and maintain. Regular Expressions are created by using chained methods and variables such as arrays or strings.

Supporters

Development of RegExpBuilderJS is supported by:

• Ping Bot - A free uptime and vendor monitoring service for everyone.

Installation

$ npm install regexpbuilderjs

Examples

const RegExpBuilder = require('regexpbuilderjs');
const builder = new RegExpBuilder();

Validation

const regExp = builder
    .startOfInput()
    .exactly(4).digits()
    .then('_')
    .exactly(2).digits()
    .then('_')
    .min(3).max(10).letters()
    .then('.')
    .anyOf(['png', 'jpg', 'gif'])
    .endOfInput()
    .getRegExp();

// true
regExp.test('2020_10_hund.jpg');
regExp.test('2030_11_katze.png');
regExp.test('4000_99_maus.gif');

// false
regExp.test('123_00_nein.gif');
regExp.test('4000_0_nein.pdf');
regExp.test('201505_nein.jpg');

Search

const regExp = builder
    .multiLine()
    .globalMatch()
    .min(1).max(10).anythingBut(' ')
    .anyOf(['.pdf', '.doc'])
    .getRegExp();

const text = `Lorem ipsum dolor sit amet, consetetur sadipscing elitr,
sed diam nonumy SomeFile.pdf eirmod tempor invidunt ut labore et dolore
magna aliquyam erat, sed diam voluptua. At vero eos et accusam
et justo duo dolores et ea rebum. doc_04.pdf Stet clita kasd File.doc.`;

const matches = Array.from(text.matchAll(regExp));

// true
(matches[0][0] === 'SomeFile.pdf');
(matches[1][0] === 'doc_04.pdf');
(matches[2][0] === 'File.doc');

Replace

const regExp = builder
    .min(1)
    .max(10)
    .digits()
    .getRegExp();

let text = '98 bottles of beer on the wall';

text = text.replace(regExp, match => (parseInt(match, 10) + 1).toString());

// true
('99 bottles of beer on the wall' === text);

Validation with multiple patterns

const a = builder
    .startOfInput()
    .exactly(3).digits()
    .anyOf(['.pdf', '.doc'])
    .endOfInput();

const b = builder
    .getNew()
    .startOfInput()
    .exactly(4).letters()
    .then('.jpg')
    .endOfInput();

const regExp = builder
    .getNew()
    .eitherFind(a)
    .orFind(b)
    .getRegExp();

// true
regExp.test('123.pdf');
regExp.test('456.doc');
regExp.test('bbbb.jpg');
regExp.test('aaaa.jpg');

// false
regExp.test('1234.pdf');
regExp.test('123.gif');
regExp.test('aaaaa.jpg');
regExp.test('456.docx');

Take a look at the tests for more examples.

Documentation

RegExpBuilder integrates regular expressions into the programming language, thereby making them easy to read and maintain. Regular Expressions are created by using chained methods and variables such as arrays or strings.

RegExpBuilder

const builder = new RegExpBuilder();

All public methods except getRegExp() are chainable.

find(string)

Alias for then, sounds nicer at the beginning.

builder
    .find("Hey, ")
    .then("where do you go to get ")
    .eitherFind("juice")
    .orFind("milk");

related: then()

then(string)

Matches a single occurrence of the string.

builder
    .startOfLine()
    .then("Where do you go to get ")
    .eitherFind("juice")
    .orFind("milk");

some(array)

Specifies that there is at least one character and that each character must be one of those contained in the array of strings. Each string in the array must be a single character.

const digits = ["3", "7", "8"];
builder
    .some(digits)
    .then(".");

maybeSome(array)

The same as some(array), except that there may be no characters at all, rather than at least one.

const digits = ["3", "7", "8"];
builder
    .maybeSome(digits);

maybe(string)

Specifies that the string may or may not occur.

builder
    .maybe("milk");

anything()

Specifies that there is zero or more of any character.

builder
    .anything();

anythingBut(string)

Specifies that there is zero or more of any character as long as the string of resulting characters does not start with the supplied string.

builder
    .anythingBut("milk");

something()

Specifies that there is one or more of any character.

builder
    .something();

lineBreak()

Specifies that there is a line break.

builder
    .lineBreak();

lineBreaks()

Specifies that there are multiple line breaks.

builder
    .exactly(2)
    .lineBreaks();

whitespace()

If used alone, specifies that there is a single whitespace character.

builder
    .whitespace();

tab()

Specifies that there is a single tab.

builder
    .tab();

tabs()

Specifies that there are multiple tabs.

builder
    .exactly(2)
    .tabs();

digit()

Specifies that there is a single digit.

builder
    .digit();

digits()

Specifies that there are multiple digits.

builder
    .exactly(2)
    .digits();

letter()

Specifies that there is a single letter.

builder
    .letter();

letters()

Specifies that there are multiple letters.

builder
    .exactly(2)
    .letters();

lowerCaseLetter()

Specifies that there is a single lowercase letter.

builder
    .lowerCaseLetter();

lowerCaseLetters()

Specifies that there are multiple lowercase letters.

builder
    .exactly(2)
    .lowerCaseLetters();

upperCaseLetter()

Specifies that there is a single uppercase letter.

builder
    .upperCaseLetter();

upperCaseLetters()

Specifies that there are multiple uppercase letters.

builder
    .exactly(2)
    .upperCaseLetters();

startOfInput()

Matches the start of input.

builder
    .startOfInput()
    .min(1)
    .of("milk");

related: endOfInput()

startOfLine()

Matches the start of input or start of a line.

builder
    .startOfLine()
    .min(1)
    .of("milk");

related: endOfLine()

endOfInput()

Matches the end of input.

builder
    .min(1)
    .of("milk")
    .endOfInput();

related: startOfInput()

endOfLine()

Matches the end of input or line.

builder
    .min(1)
    .of("milk")
    .endOfLine();

related: startOfLine()

eitherFind(RegExpBuilder)

Used with or. This method takes a new RegExpBuilder object.

const a = builder.exactly(1).of("milk");
const b = builder.exactly(2).of("juice");

builder
    .eitherFind(a)
    .orFind(b);

related: orFind(RegExpBuilder)

orFind(RegExpBuilder)

Used after either. Multiple or methods can be chained together. This method takes a new RegExpBuilder object.

const a = builder.exactly(1).of("milk");
const b = builder.exactly(2).of("juice");

builder
    .eitherFind(a)
    .orFind(b);

related: eitherFind(RegExpBuilder)

eitherFind(string)

Used with or. This method takes a string.

builder
    .eitherFind("milk")
    .orFind("juice");

related: orFind(string)

orFind(string)

Used after either. Multiple or methods can be chained together. This method takes a string.

builder
    .eitherFind("milk")
    .orFind("juice");

related: eitherFind(string)

neither(RegExpBuilder)

Used with nor. This method takes a new RegExpBuilder object.

const a = builder.exactly(1)
    .of("milk");
const b = builder.exactly(2)
    .of("juice");

builder
    .neither(a)
    .nor(b);

related: nor(RegExpBuilder)

nor(RegExpBuilder)

Used after neither. Multiple nor methods can be chained together. This method takes a new RegExpBuilder object.

const a = builder.exactly(1)
    .of("milk");
const b = builder.exactly(2)
    .of("juice");

builder
    .neither(a)
    .nor(b);

related: neither(RegExpBuilder)

neither(string)

Used with nor. This method takes a string.

builder
    .neither("milk")
    .nor("juice");

related: nor(string)

nor(string)

Used after neither. Multiple nor methods can be chained together. This method takes a string.

builder
    .neither("milk")
    .nor("juice");

related: neither(string)

exactly(number)

Used to specify the exact number of times a pattern will repeat.

builder
    .exactly(1)
    .of("milk");

related: min(number), max(number)

min(number)

Used to specify the minimum number of times a pattern will repeat. This method can optionally occur before max()

builder
    .min(1)
    .of("milk");

related: max(number)

max(number)

Used to specify the maximum number of times a pattern will repeat. This method can optionally occur after min()

builder
    .max(1)
    .of("milk");

related: min(number)

of(string)

Used to match a string.

builder
    .exactly(1)
    .of("milk");

related: from(array), notFrom(array), like(RegExpBuilder)

anyOf(string)

Match one of multiple strings.

builder
    .startOfInput()
    .min(2).max(5).letters()
    .anyOf([".jpg", ".gif", ".png"]);

related: from(array), notFrom(array)

ofAny()

Used to match any character.

builder
    .exactly(1)
    .ofAny();

related: anything()

ofGroup(number)

Used to match a previously defined group.

builder
    .exactly(3)
    .of("milk")
    .asGroup()
    .exactly(1)
    .of("juice")
    .exactly(1)
    .ofGroup(1);

related: asGroup()

from(array)

Used to match any of the characters contained in the array. It is equivalent to the regular expression [array].

builder
    .exactly(3)


    .from(["p", "q", "r"]);

related: notFrom(array)

notFrom(array)

Used to match any characters other than those contained in the array. It is equivalent to the regular expression [^array].

builder
    .exactly(3)
    .notFrom(["p", "q", "r"]);

related: from(array)

like(RegExpBuilder)

Used to nest patterns. This method takes a new RegExpBuilder object.

const pattern = builder
    .min(1)
    .of("milk")
    .min(2)
    .of("juice");

builder
    .getNew()
    .exactly(2)
    .like(pattern);

reluctantly()

Used to specify that the pattern is matched reluctantly. This means that the smallest possible match is found, rather than the largest possible match.

builder
    .find("milk")
    .anything()
    .reluctantly()
    .digit();

ahead(RegExpBuilder)

Equivalent to the concept of lookaheads in regular expressions. This method takes a new RegExpBuilder object.

const pattern = builder
    .exactly(1)
    .of("juice");

builder
    .getNew()
    .exactly(1)
    .of("fruit")
    .ahead(pattern);

related: notAhead(RegExpBuilder)

notAhead(RegExpBuilder)

Equivalent to the concept of lookaheads in regular expressions. This method takes a new RegExpBuilder object.

const pattern = builder
    .exactly(1)
    .of("pqr");

builder
    .getNew()
    .exactly(1)
    .of("milk")
    .notAhead(pattern);

related: ahead(RegExpBuilder)

asGroup()

Equivalent to the concept of capturing groups in regular expressions.

const regExp = builder
    .min(1)
    .max(3)
    .of("p")
    .exactly(1)
    .of("milk")
    .asGroup()
    .exactly(1)
    .from(["p", "q", "r"])
    .getRegExp();

const matches = regExp.exec("pmilkq");
matches[1] === "milk"; //true

related: ofGroup(number)

ignoreCase()

Used before calling getRegExp() to ensure that the regular expression ignores case.

builder
    .min(1)
    .max(3)
    .of("Milk")
    .ignoreCase()
    .getRegExp();

multiLine()

Used before calling getRegExp() to set multiline on the regular expression. Normally when start() or end() are called, they refer to the start or end of the input. When multiLine() is called, they refer to the start or end of a line instead.

const builderA = builder
    .startOfLine()
    .min(1)
    .of("milk");

const builderB = builder
    .min(1)
    .like(builderA)
    .multiLine()
    .getRegExp();

getRegExp()

Once you have finished building your regular expression, getRegExp() should be called to get the actual RegExp object.

const regExp = builder
    .min(1)
    .of("milk")
    .multiLine()
    .getRegExp();

regExp.test("milk"); //true

append(RegExpBuilder)

Used to append patterns to the end of an existing pattern.

const a = builder
    .min(1)
    .of("fruit");
    
const b = builder
    .min(2)
    .of("juice");

a.append(b);

optional(RegExpBuilder)

The regular expression in the example below suggests that p1 must occur once, and then p2 might occur once.

const a = builder
    .min(1)
    .of("milk");

const b = builder
    .min(2)
    .of("juice");

a.optional(b);