Javascript helper functions for handling Regular Expressions and parsing user input as Regular Expressions
Docs best viewed at foxxmd.github.io/regex-buddy-core
Are you tired of dealing with different results based on whether a Regex is global
or not? Do you hate having to deal with match
, test
, matchAll
, and exec
?
Use regex-buddy's parseRegex
with any Regex object and get back:
- On no match =>
undefined
- On 1 or more matches (regardless of
global
) => an array ofRegExResult
objects that contain all the context you need.
Do you want to allow users to search/match strings? What about allowing users to search/match a string with Regular Expressions? But isn't that a headache??
Not anymore! With regex-buddy's parseToRegex
and parseToRegexOrLiteralSearch
, using the power of @stdlib/regexp-regexp
under the hood, you can treat any search input as a regular expression and gracefully fallback to "dumb" searching. Always get a RegExp
object back regardless of the input given!
npm install @foxxmd/regex-buddy-core
Uses @stdlib/regexp-regexp
to convert a regular string into a Regular Expression RegExp
object.
val: string
- Value to convert EX'/^my (reg)ular expression$/'
defaultFlags?: string
- Optional flags to add to the parsed expression, if none were found.
import {parseToRegex} from '@foxxmd/regex-buddy-core';
const myReg = parseToRegex('/my (reg)?ular expression/', 'i');
myReg.test('this string has my ReGuLaR expression in it'); // true
const myPlainStr = parseToRegex('just some plain string');
console.log(myPlainStr); //undefined
Tries to convert a regular string into a RegExp object using parseToRegex()
. If the string is not a valid regular expression then the string is escaped and used as character literals to create a "dumb" expression that matches the string's value as-is. If the string cannot be converted to a valid expression an error is thrown.
val: string
- Value to convert EX'/^my (reg)ular expression$/'
options?
- Can be either- An optional
string
of flags to add to the parsed expression, if none were found. - A
LiteralSearchOptions
object used to customize the literal search expression generated.
- An optional
import {parseToRegexOrLiteralSearch} from '@foxxmd/regex-buddy-core';
const strAsReg = parseToRegexOrLiteralSearch('/my (reg)?ular expression/', 'i');
strAsReg.test('this string has my ReGuLaR expression in it'); // true
const plainStr = parseToRegexOrLiteralSearch('exactStr', 'i'); // defaults to behavior: 'exact'
strAsReg.test('exactSTR'); // true
const containsStr = parseToRegexOrLiteralSearch('anywhere', {flags: 'i', behavior: 'contains'});
containsStr.test('has the keyword anywhere in the string'); // true
Takes a RegExp
and string value to test and returns:
- If no matches =>
undefined
- If any matches => An array of
RegExResult
parseRegex
will handle the expression regardless of whether it is global
or not. If it is global
then the returned array will contain all matches. If it is not global the returned array will only have one result.
reg: RegExp
- Regular Expression object to test withval: string
- The string to test on
import {parseRegex} from '@foxxmd/regex-buddy-core';
const normalRes = parseRegex(new RegExp(/my (reg)?ular (?<myGroup>exp)ression/i), 'this string has my ReGuLaR expression in it');
console.log(normalRes); // [ {...} ]
console.log(normalRes[0]);
// {
// match: 'this string has my ReGuLaR expression in it',
// index: 0,
// groups: ['reg'],
// named: {
// myGroup: 'exp'
// }
// }
const noRes = parseRegex(new RegExp(/my (reg)?ular (?<myGroup>exp)ression/i), 'it has no match');
console.log(noRes); // undefined
const globalRes = parseRegex(new RegExp(/all matches/g), 'this has all matches because it globally has all matches');
console.log(globalRes);
// [
// {
// match: 'this has all matches because it globally has all matches',
// index: 9,
// groups: [],
// named: {}
// },
// {
// match: 'this has all matches because it globally has all matches',
// index: 45,
// groups: [],
// named: {}
// }
// ]
A convenience function for dealing with non-global expressions. The same as parseRegex()
except:
- throw an error if more than one match (does not allow
global
) - return result is either
undefined
orRegexResult
(not an array)
import {parseRegexSingle} from '@foxxmd/regex-buddy-core';
const normalRes = parseRegexSingle(new RegExp(/my (reg)?ular (?<myGroup>exp)ression/i), 'this string has my ReGuLaR expression in it');
console.log(normalRes);
// {
// match: 'this string has my ReGuLaR expression in it',
// index: 0,
// groups: ['reg'],
// named: {
// myGroup: 'exp'
// }
// }
const noRes = parseRegexSingle(new RegExp(/my (reg)?ular (?<myGroup>exp)ression/i), 'it has no match');
console.log(noRes); // undefined
const globalRes = parseRegexSingle(new RegExp(/all matches/g), 'this has all matches because it globally has all matches'); // THROWS AN ERROR
A convenience function that parses a string using parseToRegexOrLiteralSearch()
, tests it against a value, and returns a tuple of:
boolean
Whether a match was foundstring
The (first) matched string
test: string
- Value to convert to an expressionsubject: string
- The string to test onoptions?
- Can be either- An optional
string
of flags to add to the parsed expression, if none were found. - A
LiteralSearchOptions
object used to customize the literal search expression generated.- If
behavior
is not defined thencontains
is used.
- If
- An optional
import {testMaybeRegex} from '@foxxmd/regex-buddy-core';
const result = testMaybeRegex('/my (reg)?ular expression/', 'this string has my ReGuLaR expression in it');
console.log(result); // [true, 'my ReGuLaR expression']
const noMatch = testMaybeRegex(new RegExp(/my (reg)?ular (?<myGroup>exp)ression/i), 'it has no match');
console.log(noMatch); // undefined
Perform one or more search-and-replace functions on a string by providing SearchAndReplaceRegExp
criteria. This is very similar to String.replace() except that:
- it can accept multiple search-and-replace operations that are performed on the resulting value of each previous operation
- the
search
value can be aRegExp
object, or a string that that is converted usingparseToRegexOrLiteralSearch()
)
val?: string
- String to perform operations onops: SearchAndReplaceRegExp[]
- One or more search-and-replace criteria to use for the operations.options?
- Optional, how to convertsearch
string values to literal searches. Can be either- An optional
string
of flags to add to the parsed expression, if none were found. - A
LiteralSearchOptions
object used to customize the literal search expression generated.- If
behavior
is not defined thencontains
is used.
- If
- An optional
import {searchAndReplace} from '@foxxmd/regex-buddy-core';
const ops = [
{
search: '/remove (this)/',
replace: ''
},
{
search: '/TEST/ig',
replace: 'DOUBLETEST'
}
];
const result = searchAndReplace('this is a TeSt which will remove this TEST', ops);
console.log(result); // this is a DOUBLETEST which will remove DOUBLETEST
An object that defines how a string is handled prior to usage as a literal string expression as well as how to search for the literal string.
flags?: string
- Optional flags to add to the parsed literal search expressiontrim?: boolean
- Trim whitespace from string value before transforming and escapingtransform?: (SearchAndReplaceRegExp | SearchAndReplaceRegExp[])
- One or more search-and-replace criteria used to transform the string value before using it as the literal search expressionescapeTransform?: SearchAndReplaceRegExp
- A search-and-replace criteria used to escape the string value before it is inserted into the literal search expression. This operation is run after anytransform
operations. A default escape function is provided.behavior?: string
- How the literal search value expression should be built IE how to search for the value in a string:exact
=> tested string must match the search value exactlycontains
=> search value must be present somewhere within the tested stringstartsWith
=> search value must be present at the beginning of the tested stringendsWith
=> search value must be present at the end of the tested string
Criteria used to perform a search-and-replace operation on a string. This is very similar to String.replace() except that string
value used for search
will be converted to RegExp first using parseToRegexOrLiteralSearch()
.
search: (string | RegExp)
- The search value to test for. Can be a normal string (converted to a case-sensitive literal) or a valid regular expression as a string, or an actual RegExp object.replace: string
- The replacement string/value to use when search is found. This can be a literal string like'replace with this'
, an empty string to remove the search value (''
), or a special regex value.
A normalized regular expression match.
match: string
- The subset of the string that matched the expressionindex: number
- The zero-based index of the string where the matched expression begangroups: (string|undefined)[]
- An array of values from capture groups in the expression. If a capture group did not match its value is undefined.named: { [string]: string }
- An object with (key => values) consisting of (named capture group name => capture group value)
MIT