Documentation improvements

Author: slevithan

README.md

@@ -115,11 +115,13 @@ Then you can do this:
 
 ```js
 // Test some Unicode scripts
+// Can also use the Script= prefix to match ES2018: \p{Script=Hiragana}
 XRegExp('^\\p{Hiragana}+$').test('ひらがな'); // -> true
 XRegExp('^[\\p{Latin}\\p{Common}]+$').test('Über Café.'); // -> true
 
-// Test the Unicode categories L (Letter) and M (Mark)
-const unicodeWord = XRegExp.tag()`^\pL[\pL\pM]*$`;
+// Test the Unicode categories Letter and Mark
+// Can also use the short names \p{L} and \p{M}
+const unicodeWord = XRegExp.tag()`^\p{Letter}[\p{Letter}\p{Mark}]*$`;
 unicodeWord.test('Русский'); // -> true
 unicodeWord.test('日本語'); // -> true
 unicodeWord.test('العربية'); // -> true
@@ -129,15 +131,14 @@ By default, `\p{…}` and `\P{…}` support the Basic Multilingual Plane (i.e. c
 
 ```js
 // Using flag A to match astral code points
-XRegExp('^\\pS$').test('💩'); // -> false
-XRegExp('^\\pS$', 'A').test('💩'); // -> true
-XRegExp('(?A)^\\pS$').test('💩'); // -> true
+XRegExp('^\\p{S}$').test('💩'); // -> false
+XRegExp('^\\p{S}$', 'A').test('💩'); // -> true
 // Using surrogate pair U+D83D U+DCA9 to represent U+1F4A9 (pile of poo)
-XRegExp('(?A)^\\pS$').test('\uD83D\uDCA9'); // -> true
+XRegExp('^\\p{S}$', 'A').test('\uD83D\uDCA9'); // -> true
 
 // Implicit flag A
 XRegExp.install('astral');
-XRegExp('^\\pS$').test('💩'); // -> true
+XRegExp('^\\p{S}$').test('💩'); // -> true
 ```
 
 Opting in to astral mode disables the use of `\p{…}` and `\P{…}` within character classes. In astral mode, use e.g. `(\pL|[0-9_])+` instead of `[\pL0-9_]+`.
@@ -168,21 +169,20 @@ Named subpatterns can be provided as strings or regex objects. A leading `^` and
 Provides tagged template literals that create regexes with XRegExp syntax and flags:
 
 ```js
-XRegExp.match('word', XRegExp.tag()`\w\b`);
-// -> 'd'
-
-const h12 = /1[0-2]|0?[1-9]/;
-const h24 = /2[0-3]|[01][0-9]/;
-const hours = XRegExp.tag('x')`${h12} : | ${h24}`;
-const minutes = /^[0-5][0-9]$/;
-// Note that explicitly naming the 'minutes' group is required for named backreferences
-const time = XRegExp.tag('x')`^ ${hours} (?<minutes>${minutes}) $`;
+XRegExp.tag()`\b\w+\b`.test('word'); // -> true
 
+const hours = /1[0-2]|0?[1-9]/;
+const minutes = /(?<minutes>[0-5][0-9])/;
+const time = XRegExp.tag('x')`\b ${hours} : ${minutes} \b`;
 time.test('10:59'); // -> true
 XRegExp.exec('10:59', time).groups.minutes; // -> '59'
+
+const backref1 = /(a)\1/;
+const backref2 = /(b)\1/;
+XRegExp.tag()`${backref1}${backref2}`.test('aabb'); // -> true
 ```
 
-`XRegExp.tag` does more than just basic interpolation. For starters, you get all the XRegExp syntax and flags. Even better, since `XRegExp.tag` uses your pattern as a raw string, you no longer need to escape all your backslashes. And since it relies on `XRegExp.build` under the hood, you get all of its extras for free. Leading `^` and trailing unescaped `$` are stripped from interpolated patterns if both are present (to allow embedding independently useful anchored regexes), interpolating into a character class is an error (to avoid unintended meaning in edge cases), interpolated patterns are treated as atomic units when quantified, interpolated strings have their special characters escaped, and any backreferences within an interpolated regex are rewritten to work within the overall pattern.
+`XRegExp.tag` does more than just interpolation. You get all the XRegExp syntax and flags, and since it reads patterns as raw strings, you no longer need to escape all your backslashes. `XRegExp.tag` also uses `XRegExp.build` under the hood, so you get all of its extras for free. Leading `^` and trailing unescaped `$` are stripped from interpolated patterns if both are present (to allow embedding independently useful anchored regexes), interpolating into a character class is an error (to avoid unintended meaning in edge cases), interpolated patterns are treated as atomic units when quantified, interpolated strings have their special characters escaped, and any backreferences within an interpolated regex are rewritten to work within the overall pattern.
 
 ### XRegExp.matchRecursive
 

src/addons/build.js

@@ -87,14 +87,17 @@ export default (XRegExp) => {
      * @returns {Function} Handler for template literals that construct regexes with XRegExp syntax.
      * @example
      *
-     * const h12 = /1[0-2]|0?[1-9]/;
-     * const h24 = /2[0-3]|[01][0-9]/;
-     * const hours = XRegExp.tag('x')`${h12} : | ${h24}`;
-     * const minutes = /^[0-5][0-9]$/;
-     * // Note that explicitly naming the 'minutes' group is required for named backreferences
-     * const time = XRegExp.tag('x')`^ ${hours} (?<minutes>${minutes}) $`;
+     * XRegExp.tag()`\b\w+\b`.test('word'); // -> true
+     *
+     * const hours = /1[0-2]|0?[1-9]/;
+     * const minutes = /(?<minutes>[0-5][0-9])/;
+     * const time = XRegExp.tag('x')`\b ${hours} : ${minutes} \b`;
      * time.test('10:59'); // -> true
-     * XRegExp.exec('10:59', time).minutes; // -> '59'
+     * XRegExp.exec('10:59', time).groups.minutes; // -> '59'
+     *
+     * const backref1 = /(a)\1/;
+     * const backref2 = /(b)\1/;
+     * XRegExp.tag()`${backref1}${backref2}`.test('aabb'); // -> true
      */
     XRegExp.tag = (flags) => (literals, ...substitutions) => {
         const subpatterns = substitutions.map(interpolate).reduce(reduceToSubpatternsObject, {});
@@ -125,7 +128,7 @@ export default (XRegExp) => {
      *   minutes: /^[0-5][0-9]$/
      * });
      * time.test('10:59'); // -> true
-     * XRegExp.exec('10:59', time).minutes; // -> '59'
+     * XRegExp.exec('10:59', time).groups.minutes; // -> '59'
      */
     XRegExp.build = (pattern, subs, flags) => {
         flags = flags || '';

src/addons/matchrecursive.js

@@ -29,7 +29,7 @@ export default (XRegExp) => {
      * @param {String} str String to search.
      * @param {String} left Left delimiter as an XRegExp pattern.
      * @param {String} right Right delimiter as an XRegExp pattern.
-     * @param {String} [flags] Any native or XRegExp flags, used for the left and right delimiters.
+     * @param {String} [flags] Any combination of XRegExp flags, used for the left and right delimiters.
      * @param {Object} [options] Lets you specify `valueNames` and `escapeChar` options.
      * @returns {!Array} Array of matches, or an empty array.
      * @example

src/xregexp.js

@@ -752,7 +752,8 @@ XRegExp.addToken = (regex, handler, options) => {
  * @returns {RegExp} Cached XRegExp object.
  * @example
  *
- * while (match = XRegExp.cache('.', 'gs').exec(str)) {
+ * let match;
+ * while (match = XRegExp.cache('.', 'gs').exec('abc')) {
  *   // The regex is compiled once only
  * }
  */
@@ -778,15 +779,15 @@ XRegExp.cache.flush = (cacheName) => {
 
 /**
  * Escapes any regular expression metacharacters, for use when matching literal strings. The result
- * can safely be used at any point within a regex that uses any flags.
+ * can safely be used at any position within a regex that uses any flags.
  *
  * @memberOf XRegExp
  * @param {String} str String to escape.
  * @returns {string} String with regex metacharacters escaped.
  * @example
  *
  * XRegExp.escape('Escaped? <.>');
- * // -> 'Escaped\?\ <\.>'
+ * // -> 'Escaped\?\u0020<\.>'
  */
 XRegExp.escape = (str) => String(nullThrows(str)).replace(/[-\[\]{}()*+?.,\\^$|#\s]/g, (match) => {
     if (/\s/.test(match)) {
@@ -1071,8 +1072,8 @@ XRegExp.match = (str, regex, scope) => {
  * // -> ['2', '4', '56']
  *
  * // Passing forward and returning specific backreferences
- * html = '<a href="http://xregexp.com/api/">XRegExp</a>\
- *         <a href="http://www.google.com/">Google</a>';
+ * const html = `<a href="http://xregexp.com/api/">XRegExp</a>
+ *               <a href="http://www.google.com/">Google</a>`;
  * XRegExp.matchChain(html, [
  *   {regex: /<a href="([^"]+)">/i, backref: 1},
  *   {regex: XRegExp('(?i)^https?://(?<domain>[^/?#]+)'), backref: 'domain'}
@@ -1120,7 +1121,7 @@ XRegExp.matchChain = (str, chain) => (function recurseChain(values, level) {
  * Returns a new string with one or all matches of a pattern replaced. The pattern can be a string
  * or regex, and the replacement can be a string or a function to be called for each match. To
  * perform a global search and replace, use the optional `scope` argument or include flag g if using
- * a regex. Replacement strings can use `${n}` or `$<n>` for named and numbered backreferences.
+ * a regex. Replacement strings can use `$<n>` or `${n}` for named and numbered backreferences.
  * Replacement functions can use named backreferences via the last argument. Also fixes browser bugs
  * compared to the native `String.prototype.replace` and can be used reliably cross-browser.
  *
@@ -1138,7 +1139,7 @@ XRegExp.matchChain = (str, chain) => (function recurseChain(values, level) {
  *     - $<n>, ${n} - Where n is a name or any number of digits that reference an existing capturing
  *       group, inserts backreference n.
  *   Replacement functions are invoked with three or more arguments:
- *     - args[0] - The matched substring (corresponds to `$&`` above). If the `namespacing` feature
+ *     - args[0] - The matched substring (corresponds to `$&` above). If the `namespacing` feature
  *       is off, named backreferences are accessible as properties of this argument.
  *     - args[1..n] - One argument for each backreference (corresponding to `$1`, `$2`, etc. above).
  *       If the regex has no capturing groups, no arguments appear in this position.
@@ -1206,8 +1207,8 @@ XRegExp.replace = (str, search, replacement, scope) => {
  * array of replacement details. Later replacements operate on the output of earlier replacements.
  * Replacement details are accepted as an array with a regex or string to search for, the
  * replacement string or function, and an optional scope of 'one' or 'all'. Uses the XRegExp
- * replacement text syntax, which supports named backreference properties via `${name}` or
- * `$<name>`.
+ * replacement text syntax, which supports named backreference properties via `$<name>` or
+ * `${name}`.
  *
  * @memberOf XRegExp
  * @param {String} str String to search.
@@ -1216,12 +1217,12 @@ XRegExp.replace = (str, search, replacement, scope) => {
  * @example
  *
  * str = XRegExp.replaceEach(str, [
- *   [XRegExp('(?<name>a)'), 'z${name}'],
+ *   [XRegExp('(?<name>a)'), 'z$<name>'],
  *   [/b/gi, 'y'],
  *   [/c/g, 'x', 'one'], // scope 'one' overrides /g
  *   [/d/, 'w', 'all'],  // scope 'all' overrides lack of /g
  *   ['e', 'v', 'all'],  // scope 'all' allows replace-all for strings
- *   [/f/g, ($0) => $0.toUpperCase()]
+ *   [/f/g, (match) => match.toUpperCase()]
  * ]);
  */
 XRegExp.replaceEach = (str, replacements) => {
@@ -1287,16 +1288,16 @@ XRegExp.split = (str, separator, limit) => fixed.split.call(nullThrows(str), sep
 XRegExp.test = (str, regex, pos, sticky) => !!XRegExp.exec(str, regex, pos, sticky);
 
 /**
- * Uninstalls optional features according to the specified options. All optional features start out
- * uninstalled, so this is used to undo the actions of `XRegExp.install`.
+ * Uninstalls optional features according to the specified options. Used to undo the actions of
+ * `XRegExp.install`.
  *
  * @memberOf XRegExp
  * @param {Object|String} options Options object or string.
  * @example
  *
  * // With an options object
  * XRegExp.uninstall({
- *   // Disables support for astral code points in Unicode addons
+ *   // Disables support for astral code points in Unicode addons (unless enabled per regex)
  *   astral: true,
  *
  *   // Don't add named capture groups to the `groups` property of matches

types/index.d.ts

@@ -534,7 +534,7 @@ declare namespace XRegExp {
      *   minutes: /^[0-5][0-9]$/
      * });
      * time.test('10:59'); // -> true
-     * XRegExp.exec('10:59', time).minutes; // -> '59'
+     * XRegExp.exec('10:59', time).groups.minutes; // -> '59'
      */
     function build(pattern: string, subs: Record<string, Pattern>, flags?: string): RegExp;
 
@@ -547,22 +547,23 @@ declare namespace XRegExp {
      * @returns Cached XRegExp object.
      * @example
      *
-     * while (match = XRegExp.cache('.', 'gs').exec(str)) {
+     * let match;
+     * while (match = XRegExp.cache('.', 'gs').exec('abc')) {
      *   // The regex is compiled once only
      * }
      */
     function cache(pattern: string, flags: string): RegExp;
 
     /**
      * Escapes any regular expression metacharacters, for use when matching literal strings. The result
-     * can safely be used at any point within a regex that uses any flags.
+     * can safely be used at any position within a regex that uses any flags.
      *
      * @param str - String to escape.
      * @returns String with regex metacharacters escaped.
      * @example
      *
      * XRegExp.escape('Escaped? <.>');
-     * // -> 'Escaped\?\ <\.>'
+     * // -> 'Escaped\?\u0020<\.>'
      */
     function escape(str: string): string;
 
@@ -732,8 +733,8 @@ declare namespace XRegExp {
      * // -> ['2', '4', '56']
      *
      * // Passing forward and returning specific backreferences
-     * html = '<a href="http://xregexp.com/api/">XRegExp</a>\
-     *         <a href="http://www.google.com/">Google</a>';
+     * const html = `<a href="http://xregexp.com/api/">XRegExp</a>
+     *               <a href="http://www.google.com/">Google</a>`;
      * XRegExp.matchChain(html, [
      *   {regex: /<a href="([^"]+)">/i, backref: 1},
      *   {regex: XRegExp('(?i)^https?://(?<domain>[^/?#]+)'), backref: 'domain'}
@@ -750,7 +751,7 @@ declare namespace XRegExp {
      * @param str - String to search.
      * @param left - Left delimiter as an XRegExp pattern.
      * @param right - Right delimiter as an XRegExp pattern.
-     * @param flags - Any native or XRegExp flags, used for the left and right delimiters.
+     * @param flags - Any combination of XRegExp flags, used for the left and right delimiters.
      * @param options - Lets you specify `valueNames` and `escapeChar` options.
      * @returns Array of matches, or an empty array.
      * @example
@@ -799,7 +800,7 @@ declare namespace XRegExp {
      * Returns a new string with one or all matches of a pattern replaced. The pattern can be a string
      * or regex, and the replacement can be a string or a function to be called for each match. To
      * perform a global search and replace, use the optional `scope` argument or include flag g if using
-     * a regex. Replacement strings can use `${n}` or `$<n>` for named and numbered backreferences.
+     * a regex. Replacement strings can use `$<n>` or `${n}` for named and numbered backreferences.
      * Replacement functions can use named backreferences via the last argument. Also fixes browser bugs
      * compared to the native `String.prototype.replace` and can be used reliably cross-browser.
      *
@@ -834,21 +835,21 @@ declare namespace XRegExp {
      * array of replacement details. Later replacements operate on the output of earlier replacements.
      * Replacement details are accepted as an array with a regex or string to search for, the
      * replacement string or function, and an optional scope of 'one' or 'all'. Uses the XRegExp
-     * replacement text syntax, which supports named backreference properties via `${name}` or
-     * `$<name>`.
+     * replacement text syntax, which supports named backreference properties via `$<name>` or
+     * `${name}`.
      *
      * @param str - String to search.
      * @param replacements - Array of replacement detail arrays.
      * @returns New string with all replacements.
      * @example
      *
      * str = XRegExp.replaceEach(str, [
-     *   [XRegExp('(?<name>a)'), 'z${name}'],
+     *   [XRegExp('(?<name>a)'), 'z$<name>'],
      *   [/b/gi, 'y'],
      *   [/c/g, 'x', 'one'], // scope 'one' overrides /g
      *   [/d/, 'w', 'all'],  // scope 'all' overrides lack of /g
      *   ['e', 'v', 'all'],  // scope 'all' allows replace-all for strings
-     *   [/f/g, ($0) => $0.toUpperCase()]
+     *   [/f/g, (match) => match.toUpperCase()]
      * ]);
      */
     function replaceEach(str: string, replacements: ReplacementDetail[]): string;
@@ -894,14 +895,17 @@ declare namespace XRegExp {
      * @returns Handler for template literals that construct regexes with XRegExp syntax.
      * @example
      *
-     * const h12 = /1[0-2]|0?[1-9]/;
-     * const h24 = /2[0-3]|[01][0-9]/;
-     * const hours = XRegExp.tag('x')`${h12} : | ${h24}`;
-     * const minutes = /^[0-5][0-9]$/;
-     * // Note that explicitly naming the 'minutes' group is required for named backreferences
-     * const time = XRegExp.tag('x')`^ ${hours} (?<minutes>${minutes}) $`;
+     * XRegExp.tag()`\b\w+\b`.test('word'); // -> true
+     *
+     * const hours = /1[0-2]|0?[1-9]/;
+     * const minutes = /(?<minutes>[0-5][0-9])/;
+     * const time = XRegExp.tag('x')`\b ${hours} : ${minutes} \b`;
      * time.test('10:59'); // -> true
-     * XRegExp.exec('10:59', time).minutes; // -> '59'
+     * XRegExp.exec('10:59', time).groups.minutes; // -> '59'
+     *
+     * const backref1 = /(a)\1/;
+     * const backref2 = /(b)\1/;
+     * XRegExp.tag()`${backref1}${backref2}`.test('aabb'); // -> true
      */
     function tag(flags?: string | null): (literals: TemplateStringsArray, ...substitutions: any[]) => RegExp;
 
@@ -930,15 +934,15 @@ declare namespace XRegExp {
     function test(str: string, regex: Pattern, pos?: number, sticky?: boolean | 'sticky'): boolean;
 
     /**
-     * Uninstalls optional features according to the specified options. All optional features start out
-     * uninstalled, so this is used to undo the actions of `XRegExp.install`.
+     * Uninstalls optional features according to the specified options. Used to undo the actions of
+     * `XRegExp.install`.
      *
      * @param options - Options object or string.
      * @example
      *
      * // With an options object
      * XRegExp.uninstall({
-     *   // Disables support for astral code points in Unicode addons
+     *   // Disables support for astral code points in Unicode addons (unless enabled per regex)
      *   astral: true,
      *
      *   // Don't add named capture groups to the `groups` property of matches