Documentation updates

Author: slevithan

README.md

@@ -4,7 +4,7 @@
 [![npm](https://img.shields.io/npm/v/regex-utilities)](https://www.npmjs.com/package/regex-utilities)
 [![bundle size](https://deno.bundlejs.com/badge?q=regex-utilities&treeshake=[*])](https://bundlejs.com/?q=regex-utilities&treeshake=[*])
 
-Tiny utilities shared by the [`regex`](https://github.com/slevithan/regex) library and its extensions. Useful for parsing and processing regular expressions, when you don't need a full regex AST builder.
+Tiny utilities shared by the [regex](https://github.com/slevithan/regex) library and its plugins. Useful for parsing and processing regular expression syntax in a lightweight way, when you don't need a full regex AST.
 
 ## Constants
 
@@ -17,24 +17,53 @@ Frozen object with the following properties for tracking regex syntax context:
 
 ## Functions
 
-See documentation in the source code for more details.
+For all of the following functions, argument `expression` is the target string, and `needle` is the pattern to search for.
+
+- Argument `expression` is assumed to be a flag-`v`-mode regex pattern string (in other words, nested character classes are allowed when determining the context for a match).
+- Argument `needle` is a regex pattern as a string, and is applied with flags `su`.
+- If argument `context` is not provided, matches are allowed in all contexts (in other words, inside and outside of character classes).
 
 ### `execUnescaped`
 
-Returns a match object for the first unescaped instance of a pattern that is in the given context. Else, returns `null`.
+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`
 
-Checks whether an unescaped instance of a pattern appears in the given context.
+Arguments: `expression, needle, [context]`
+
+Checks whether an unescaped instance of a regex pattern appears in the given context.
 
 ### `forEachUnescaped`
 
-Runs a callback for each unescaped instance of a pattern that is in the given context.
+Arguments: `expression, needle, callback, [context]`
+
+Runs a callback for each unescaped instance of a regex pattern in the given context.
 
 ### `replaceUnescaped`
 
-Replaces all unescaped instances of a pattern that are in the given context.
+Arguments: `expression, needle, replacement, [context]`
+
+Replaces all unescaped instances of a regex pattern in the given context, using a replacement string or callback.
+
+<details>
+  <summary>Examples</summary>
+
+```js
+replaceUnescaped('.\\.\\\\.[[\\.].].', '\\.', '~');
+// → '~\\.\\\\~[[\\.]~]~'
+
+replaceUnescaped('.\\.\\\\.[[\\.].].', '\\.', '~', Context.DEFAULT);
+// → '~\\.\\\\~[[\\.].]~'
+
+replaceUnescaped('.\\.\\\\.[[\\.].].', '\\.', '~', Context.CHAR_CLASS);
+// → '.\\.\\\\.[[\\.]~].'
+```
+</details>
 
 ### `getGroupContents`
 
-Returns the contents of the group within the given pattern, with the group being identified by the position where its contents start (i.e., just *after* the group's opening delimiter). Accounts for escaped characters, nested groups, and character classes. Returns the rest of the string if the group is unclosed.
+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.

spec/utilities-spec.js

@@ -37,6 +37,11 @@ describe('replaceUnescaped', () => {
   it('should replace all using a replacement function and named backrefs', () => {
     expect(replaceUnescaped('%1 %22', '%(?<num>\\d+)', ({groups: {num}}) => `\\${num}`)).toBe('\\1 \\22');
   });
+
+  // Just documenting current behavior
+  it('should replace with a literal string (no backreferences) if given a replacement string', () => {
+    expect(replaceUnescaped('ab', '(.)(?<a>.)', '~$1$<a>~')).toBe('~$1$<a>~');
+  });
 });
 
 describe('forEachUnescaped', () => {

src/index.js

@@ -5,7 +5,8 @@ export const Context = Object.freeze({
 });
 
 /**
-Replaces all unescaped instances of a pattern that are in the given context.
+Replaces all unescaped instances of a regex pattern in the given context, using a replacement
+string or callback.
 
 Doesn't skip over complete multicharacter tokens (only `\` plus its folowing char) so must be used
 with knowledge of what's safe to do given regex syntax. Assumes UnicodeSets-mode syntax.
@@ -15,12 +16,12 @@ with knowledge of what's safe to do given regex syntax. Assumes UnicodeSets-mode
 @param {'DEFAULT' | 'CHAR_CLASS'} [context] All contexts if not specified
 @returns {string} Updated expression
 @example
-replaceUnescaped(String.raw`.\.\\.[[\.].].`, '\\.', '~');
-// → String.raw`~\.\\~[[\.]~]~`
-replaceUnescaped(String.raw`.\.\\.[[\.].].`, '\\.', '~', Context.DEFAULT);
-// → String.raw`~\.\\~[[\.].]~`
-replaceUnescaped(String.raw`.\.\\.[[\.].].`, '\\.', '~', Context.CHAR_CLASS);
-// → String.raw`.\.\\.[[\.]~].`
+replaceUnescaped('.\\.\\\\.[[\\.].].', '\\.', '~');
+// → '~\\.\\\\~[[\\.]~]~'
+replaceUnescaped('.\\.\\\\.[[\\.].].', '\\.', '~', Context.DEFAULT);
+// → '~\\.\\\\~[[\\.].]~'
+replaceUnescaped('.\\.\\\\.[[\\.].].', '\\.', '~', Context.CHAR_CLASS);
+// → '.\\.\\\\.[[\\.]~].'
 */
 export function replaceUnescaped(expression, needle, replacement, context) {
   const re = new RegExp(`${needle}|(?<skip>\\\\?.)`, 'gsu');
@@ -47,7 +48,7 @@ export function replaceUnescaped(expression, needle, replacement, context) {
 }
 
 /**
-Runs a callback for each unescaped instance of a pattern that is in the given context.
+Runs a callback for each unescaped instance of a regex pattern in the given context.
 
 Doesn't skip over complete multicharacter tokens (only `\` plus its folowing char) so must be used
 with knowledge of what's safe to do given regex syntax. Assumes UnicodeSets-mode syntax.
@@ -62,8 +63,8 @@ export function forEachUnescaped(expression, needle, callback, context) {
 }
 
 /**
-Returns a match object for the first unescaped instance of a pattern that is in the given context.
-Else, returns `null`.
+Returns a match object for the first unescaped instance of a regex pattern in the given context, or
+`null`.
 
 Doesn't skip over complete multicharacter tokens (only `\` plus its folowing char) so must be used
 with knowledge of what's safe to do given regex syntax. Assumes UnicodeSets-mode syntax.
@@ -101,7 +102,7 @@ export function execUnescaped(expression, needle, pos = 0, context) {
 }
 
 /**
-Checks whether an unescaped instance of a pattern appears in the given context.
+Checks whether an unescaped instance of a regex pattern appears in the given context.
 
 Doesn't skip over complete multicharacter tokens (only `\` plus its folowing char) so must be used
 with knowledge of what's safe to do given regex syntax. Assumes UnicodeSets-mode syntax.
@@ -116,10 +117,10 @@ export function hasUnescaped(expression, needle, context) {
 }
 
 /**
-Returns the contents of the group within the given pattern, with the group being identified by the
-position where its contents start (i.e., just *after* the group's opening delimiter). Accounts for
-escaped characters, nested groups, and character classes. Returns the rest of the string if the
-group is unclosed.
+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.
 
 Assumes UnicodeSets-mode syntax.
 @param {string} expression Search target