Simple Regex Builder

A human-friendly regex builder.

Installation

npm i simple-regex-builder

Usage

Importing

ES modules

import { REGEX, SimpleRegexBuilder } from 'simple-regex-builder';

CommonJS modules

const { REGEX, SimpleRegexBuilder} = require('simple-regex-builder');

SimpleRegexBuilder

A SimpleRegexBuilder is a mutable builder object.

const r = new SimpleRegexBuilder().global().ignoreCase();
r.startsWith('a')
    .add(REGEX.BETWEEN_N_AND_M(1, 3, REGEX.ANY_WHITESPACE))
    .endsWith('b');
console.log(r.toString());
// /^a\s{1,3}b$/gi

The regex object's sequence can be manipulated with the startsWith, endsWith, add and followedBy.

For convenience, the add and followedBy methods are synonymous.

end is the equivalent of endsWith('').

The regex modifiers can be manipulated with global, ignoreCase, multiline and unicode, which all receive a boolean parameter that defaults to true.

NOTE: The sticky modifier and lastIndex property of RegExp don't really make sense for a builder, if you need that functionality just build a RegExp object as described below and use that instead.

To reuse a partially developed builder, provide it as the argument to a new object's constructor, or use the clone method directly:

const base = new SimpleRegexBuilder().startsWith('abc');

const caseInsensitiveMatcher = new SimpleRegexBuilder(base).ignoreCase();
console.log(caseInsensitiveMatcher.toString());
// /^abc/i

const globalMatcher = base.clone().global();
console.log(globalMatcher.toString());
// /^abc/g

Building a RegExp object is done with either of the synonymous build or toRegExp methods:

const r = new SimpleRegexBuilder().add("rain").build();
const s = new SimpleRegexBuilder().add("spain").toRegExp();

For convenience, the RegExp class's exec, test and toString methods can be called directly on the SimpleRegexBuilder itself:

const r = new SimpleRegexBuilder().add("ain");
console.log(r.test('The rain in Spain falls mainly on the plain.'));
// true
console.log(r.exec('The rain in Spain falls mainly on the plain.'));
// [ 'ain', index: 5, input: 'The rain in Spain falls mainly on the plain.', groups: undefined ]

REGEX

The REGEX object includes both constants and functions that accept strings, RegExp and SimpleRegexBuilder objects.

The REGEX object is a set of key/value pairs, where some of the values are strings and some of them functions.

console.log(REGEX.ANY_CHARACTER);
// "."
console.log(REGEX.CHARACTERS_IN_SET("a-z0-9"));
// "[a-z0-9]"

Brackets

| Key | Value | Description | | --- | ------ | ----------- | | CHARACTERS_IN_SET | ("abc") => "[abc]" | Find any character between the brackets | | CHARACTERS_NOT_IN_SET | ("abc") => "[^abc]" | Find any character NOT between the brackets | | IN_SET | ("abc","d[ef]*") => "(abc\|d[ef]*)" | Find any of the alternatives specified |

Metacharacters

| Key | Value | Description | | --- | ------ | ----------- | | ANY_CHARACTER or ANY | . | Find a single character, except newline or line terminator | | WORD_CHARACTER or WORD | \w | Find any word character, equivalent to [a-zA-Z_0-9] | | NON_WORD_CHARACTER or NON_WORD | \W | Find a non-word character, equivalent to [^a-zA-Z_0-9] | | DIGIT | \d | Find a digit | | NON_DIGIT | \D | Find a non-digit character | | WHITESPACE | \s | Find a whitespace character | | NON_WHITESPACE | \S | Find a non-whitespace character | | MATCH_WORD_BEGINNING_WITH | ("word") => "\bword" | Find a match at the beginning of a word | | MATCH_WORD_ENDING_WITH | ("word") => "word\b" | Find a match at the end of a word | | MATCH_WORD_BEGINNING_AND_ENDING_WITH | ("word") => "\bword\b" | Find a match for the whole word | | MATCH_WORD_NOT_BEGINNING_WITH | ("word") => "\Bword" | Find a match for the word, but not if it's at the beginning of a word | | MATCH_WORD_NOT_ENDING_WITH | ("word") => "word\B" | Find a match for the word, but not if it's at the end of a word | | MATCH_WORD_NOT_BEGINNING_OR_ENDING_WITH | ("word") => "\Bword\B" | Find a match for the word, but not if it's at the beginning or end of a word | | NULL_CHARACTER or NULL | \0 | Find a NULL character | | NEW_LINE | \n | Find a new line character | | FORM_FEED | \f | Find a form feed character | | CARRIAGE_RETURN | \r | Find a carriage return character | | TAB | \t | Find a tab character | | VERTICAL_TAB | \v | Find a vertical tab character | | OCTAL_NUMBER or OCT | ("17") => "\17" | Find the character specified by the given octal number | | HEXADECIMAL_NUMBER or HEX_NUMBER or HEX | ("1a") => "\x1a" | Find the character specified by the given hexadecimal number | | UNICODE_CHARACTER or UNICODE | ("1F1EE", "1F1F1") => "\u{1F1EE}\u{1F1F1}" | Find the Unicode character specified by a given hexadecimal number / numbersWARNING: the unicode modifier must be provided in order for this to match |

Quantifiers

Quantifier methods accept regex in the form of strings, RegExp objects and SimpleRegexBuilder objects.

If the length of the given argument is greater than 1 then it will be enclosed in brackets, eg. ("n") => "n*" but ("abc") => "(abc)*".

| Key | Value | Description | | --- | ------ | ----------- | | ONE_OR_MORE or AT_LEAST_ONE | ("n") => "n+", | Matches any string that contains at least one n | | ZERO_OR_MORE | ("n") => "n*" | Matches any string that contains zero or more occurrences of n | | ZERO_OR_ONE or OPTIONAL | ("n") => "n?" | Matches any string that contains zero or one occurrences of n | | EXACTLY_X or EXACTLY_N or EXACTLY | (2, "n") => "n{3}" | Matches any string that contains a sequence of X n's | | BETWEEN_X_AND_Y or BETWEEN_N_AND_M or BETWEEN: (1, 3, "n") => "n{1,3}" | Matches any string that contains a sequence of X to Y n's | | AT_LEAST_X or AT_LEAST_N or AT_LEAST | (1, "n") => "n{1,}" | Matches any string that contains a sequence of at least X n's | | IS_FOLLOWED_BY or FOLLOWED_BY | ("\s+term") => "(?=\s+term)" | Matches any string that is followed by a specific string n | | IS_NOT_FOLLOWED_BY or NOT_FOLLOWED_BY | ("\s+term") => "(?!\s+term)" | Matches any string that is followed by a specific string n |

License

MIT

ALL CONTRIBUTIONS AND FEEDBACK WELCOME