regex-utilities
v2.3.0
Published
Tiny helpers for processing regex syntax
Downloads
2,729
Readme
regex-utilities
Tiny utilities that the regex library makes available for reuse in its plugins. Useful for parsing and processing regular expression syntax in a lightweight way, when you don't need a full regex AST.
Constants
Context
Frozen object with the following properties for tracking regex syntax context:
DEFAULT
- Base context.CHAR_CLASS
- Character class context.
Functions
For all of the following functions, argument expression
is the target string, and needle
is the regex pattern to search for.
- Argument
expression
(the string being searched through) is assumed to be a flag-v
-mode regex pattern string. In other words, nested character classes within it are supported when determining the context for a match. - Argument
needle
(the regex pattern being searched for) is provided as a string, and is applied with flagssu
. - If argument
context
is not provided, matches are allowed in all contexts. In other words, inside and outside of character classes.
replaceUnescaped
Arguments: expression, needle, replacement, [context]
Replaces all unescaped instances of a regex pattern in the given context, using a replacement string or function.
const str = '.\\.\\\\.[[\\.].].';
replaceUnescaped(str, '\\.', '@');
// → '@\\.\\\\@[[\\.]@]@'
replaceUnescaped(str, '\\.', '@', Context.DEFAULT);
// → '@\\.\\\\@[[\\.].]@'
replaceUnescaped(str, '\\.', '@', Context.CHAR_CLASS);
// → '.\\.\\\\.[[\\.]@].'
Details for the replacement
argument:
- If a string is provided, it's used literally without special handling for backreferences, etc.
- If a function is provided, it receives two arguments:
- The match object (which includes
groups
,index
, etc.). - An object with extended details (
context
andnegated
) about where the match was found.
- The match object (which includes
execUnescaped
Arguments: expression, needle, [pos = 0], [context]
Returns a match object for the first unescaped instance of a regex pattern in the given context, or null
.
hasUnescaped
Arguments: expression, needle, [context]
Checks whether an unescaped instance of a regex pattern appears in the given context.
forEachUnescaped
Arguments: expression, needle, callback, [context]
Runs a function for each unescaped match of a regex pattern in the given context. The function receives two arguments:
- The match object (which includes
groups
,index
, etc.). - An object with extended details (
context
andnegated
) about where the match was found.
getGroupContents
Arguments: expression, contentsStartPos
Extracts the full contents of a group (subpattern) from the given expression, accounting for escaped characters, nested groups, and character classes. The group is identified by the position where its contents start (the string index just after the group's opening delimiter). Returns the rest of the string if the group is unclosed.