Remove the rregex sugar tag

Author: slevithan

README.md

@@ -1,4 +1,8 @@
-# regex-recursion [![npm](https://img.shields.io/npm/v/regex-recursion)](https://www.npmjs.com/package/regex-recursion)
+# regex-recursion
+
+[![build status](https://github.com/slevithan/regex-recursion/workflows/CI/badge.svg)](https://github.com/slevithan/regex-recursion/actions)
+[![npm](https://img.shields.io/npm/v/regex-recursion)](https://www.npmjs.com/package/regex-recursion)
+[![bundle size](https://deno.bundlejs.com/badge?q=regex-recursion&treeshake=[*])](https://bundlejs.com/?q=regex-recursion&treeshake=[*])
 
 This is a plugin for the [`regex`](https://github.com/slevithan/regex) library that adds support for recursive matching up to a specified max depth *N*, where *N* must be between 2 and 100. Generated regexes are native `RegExp` instances, and support all JavaScript regular expression features.
 
@@ -13,19 +17,26 @@ Recursive matching supports named captures/backreferences, and makes them indepe
 ## Install and use
 
 ```sh
-npm install regex-recursion
+npm install regex regex-recursion
 ```
 
 ```js
-import {rregex} from 'regex-recursion';
+import {regex} from 'regex';
+import {recursion} from 'regex-recursion';
+
+const re = regex({plugins: [recursion]})`…`;
 ```
 
-In browsers:
+In browsers (using a global name):
 
 ```html
+<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/regex.min.js"></script>
 <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/regex-recursion.min.js"></script>
 <script>
-  const {rregex} = Regex.ext;
+  const {regex} = Regex;
+  const {recursion} = Regex.plugins;
+
+  const re = regex({plugins: [recursion]})`…`;
 </script>
 ```
 
@@ -37,14 +48,15 @@ In browsers:
 
 ```js
 // Matches sequences of up to 50 'a' chars followed by the same number of 'b'
-rregex`a(?R=50)?b`.exec('test aaaaaabbb')[0];
+const re = regex({plugins: [recursion]})`a(?R=50)?b`;
+re.exec('test aaaaaabbb')[0];
 // → 'aaabbb'
 ```
 
 #### As the entire string
 
 ```js
-const re = rregex`^
+const re = regex({plugins: [recursion]})`^
   (?<balanced>
     a
     # Recursively match just the specified group
@@ -60,7 +72,7 @@ re.test('aaabb'); // → false
 
 ```js
 // Matches all balanced parentheses up to depth 50
-const parens = rregex('g')`\(
+const parens = regex({flags: 'g', plugins: [recursion]})`\(
   ( [^\(\)] | (?R=50) )*
 \)`;
 
@@ -76,35 +88,39 @@ const parens = rregex('g')`\(
 Here's an alternative that matches the same strings, but adds a nested quantifier. It then uses an atomic group to prevent this nested quantifier from creating the potential for runaway backtracking:
 
 ```js
-const parens = rregex('g')`\(
+const parens = regex({flags: 'g', plugins: [recursion]})`\(
   ( (?> [^\(\)]+ ) | (?R=50) )*
 \)`;
 ```
 
 This matches sequences of non-parens in one step with the nested `+` quantifier, and avoids backtracking into these sequences by wrapping it with an atomic group `(?>…)`. Given that what the nested quantifier `+` matches overlaps with what the outer group can match with its `*` quantifier, the atomic group is important here. It avoids runaway backtracking when matching long strings with unbalanced parens.
 
-Atomic groups are provided by the base `regex` package.
+Atomic groups are provided by the base `regex` library.
 
 ### Match palindromes
 
 #### Match palindroms anywhere within a string
 
 ```js
-const palindromes = rregex('gi')`(?<char>\w) ((?R=15)|\w?) \k<char>`;
+const palindromes = regex({flags: 'gi', plugins: [recursion]})`
+  (?<char> \w )
+  # Recurse, or match a lone unbalanced char in the middle
+  ( (?R=15) | \w? )
+  \k<char>
+`;
 
 'Racecar, ABBA, and redivided'.match(palindromes);
 // → ['Racecar', 'ABBA', 'edivide']
 ```
 
-In this example, the max length of matched palindromes is 31. That's because it sets the max recursion depth to 15 with `(?R=15)`. So, depth 15 × 2 chars (left + right) for each depth level + 1 optional unbalanced char in the center = 31. To match longer palindromes, the max recursion depth can be increased to a max of 100, which would enable matching palindromes up to 201 characters long.
+In the example above, the max length of matched palindromes is 31. That's because it sets the max recursion depth to 15 with `(?R=15)`. So, depth 15 × 2 chars (left + right) for each depth level + 1 optional unbalanced char in the middle = 31. To match longer palindromes, the max recursion depth can be increased to a max of 100, which would enable matching palindromes up to 201 characters long.
 
 #### Match palindromes as complete words
 
 ```js
-const palindromeWords = rregex('gi')`\b
+const palindromeWords = regex({flags: 'gi', plugins: [recursion]})`\b
   (?<palindrome>
     (?<char> \w )
-    # Recurse, or match a lone unbalanced char in the center
     ( \g<palindrome&R=15> | \w? )
     \k<char>
   )
@@ -114,13 +130,4 @@ const palindromeWords = rregex('gi')`\b
 // → ['Racecar', 'ABBA']
 ```
 
-## Sugar free
-
-Template tag `rregex` is sugar for using the base `regex` tag and adding recursion support via a plugin. You can also add recursion support the verbose way:
-
-```js
-import {regex} from 'regex';
-import {recursion} from 'regex-recursion';
-
-regex({flags: 'i', plugins: [recursion]})`a(?R=2)?b`;
-```
+Note the word boundaries (`\b`) at the beginning and end of the regex, outside of the recursive subpattern.

package-lock.json

@@ -9,7 +9,7 @@
   "browser": "./dist/regex-recursion.min.js",
   "scripts": {
     "prebuild": "rimraf --glob dist/*",
-    "build": "esbuild src/index.js --bundle --minify --outfile=dist/regex-recursion.min.js --global-name=Regex.ext",
+    "build": "esbuild src/index.js --bundle --minify --outfile=dist/regex-recursion.min.js --global-name=Regex.plugins",
     "pretest": "npm run build",
     "test": "jasmine",
     "prepare": "npm test"
@@ -28,10 +28,10 @@
     "regexp"
   ],
   "dependencies": {
-    "regex": "^4.0.0",
     "regex-utilities": "^2.1.0"
   },
   "devDependencies": {
+    "regex": "^4.0.0",
     "esbuild": "^0.23.0",
     "jasmine": "^5.2.0",
     "rimraf": "^6.0.1"

package.json

@@ -1,13 +1,14 @@
 import {regex} from 'regex';
-import {recursion, rregex} from '../src/index.js';
+import {recursion} from '../src/index.js';
 
 describe('recursion', () => {
   it('should match an equal number of two different subpatterns', () => {
-    expect(rregex`a(?R=50)?b`.exec('test aaaaaabbb')[0]).toBe('aaabbb');
+    expect(regex({plugins: [recursion]})`a(?R=50)?b`.exec('test aaaaaabbb')[0]).toBe('aaabbb');
+    expect('aAbb').toMatch(regex({flags: 'i', plugins: [recursion]})`a(?R=2)?b`);
   });
 
   it('should match an equal number of two different subpatterns, as the entire string', () => {
-    const re = rregex`^
+    const re = regex({plugins: [recursion]})`^
       (?<balanced>
         a
         # Recursively match just the specified group
@@ -20,26 +21,26 @@ describe('recursion', () => {
   });
 
   it('should match balanced parentheses', () => {
-    const parens = rregex('g')`\(
+    const parens = regex({flags: 'g', plugins: [recursion]})`\(
       ( [^\(\)] | (?R=50) )*
     \)`;
     expect('test ) (balanced ((parens))) () ((a)) ( (b)'.match(parens)).toEqual(['(balanced ((parens)))', '()', '((a))', '(b)']);
   });
 
   it('should match balanced parentheses using an atomic group', () => {
-    const parens = rregex('g')`\(
+    const parens = regex({flags: 'g', plugins: [recursion]})`\(
       ( (?> [^\(\)]+ ) | (?R=50) )*
     \)`;
     expect('test ) (balanced ((parens))) () ((a)) ( (b)'.match(parens)).toEqual(['(balanced ((parens)))', '()', '((a))', '(b)']);
   });
 
   it('should match palindromes', () => {
-    const palindromes = rregex('gi')`(?<char>\w) ((?R=15)|\w?) \k<char>`;
+    const palindromes = regex({flags: 'gi', plugins: [recursion]})`(?<char>\w) ((?R=15)|\w?) \k<char>`;
     expect('Racecar, ABBA, and redivided'.match(palindromes)).toEqual(['Racecar', 'ABBA', 'edivide']);
   });
 
   it('should match palindromes as complete words', () => {
-    const palindromeWords = rregex('gi')`\b
+    const palindromeWords = regex({flags: 'gi', plugins: [recursion]})`\b
       (?<palindrome>
         (?<char> \w )
         # Recurse, or match a lone unbalanced char in the center
@@ -51,25 +52,21 @@ describe('recursion', () => {
   });
 
   it('should not adjust named backreferences referring outside of the recursed expression', () => {
-    expect('aababbabcc').toMatch(rregex`^(?<a>a)\k<a>(?<r>(?<b>b)\k<a>\k<b>\k<c>\g<r&R=2>?)(?<c>c)\k<c>$`);
-  });
-
-  it('should allow directly using recursion as a plugin with tag regex', () => {
-    expect('aAbb').toMatch(regex({flags: 'i', plugins: [recursion]})`a(?R=2)?b`);
+    expect('aababbabcc').toMatch(regex({plugins: [recursion]})`^(?<a>a)\k<a>(?<r>(?<b>b)\k<a>\k<b>\k<c>\g<r&R=2>?)(?<c>c)\k<c>$`);
   });
 
   // Just documenting current behavior; this could be supported in the future
   it('should not allow numbered backreferences in interpolated regexes when using recursion', () => {
-    expect(() => rregex`a(?R=2)?b${/()\1/}`).toThrow();
-    expect(() => rregex`(?<n>a|\g<n&R=2>${/()\1/})`).toThrow();
-    expect(() => rregex`(?<n>a|\g<n&R=2>)${/()\1/}`).toThrow();
-    expect(() => rregex`${/()\1/}a(?R=2)?b`).toThrow();
-    expect(() => rregex`(?<n>${/()\1/}a|\g<n&R=2>)`).toThrow();
-    expect(() => rregex`${/()\1/}(?<n>a|\g<n&R=2>)`).toThrow();
+    expect(() => regex({plugins: [recursion]})`a(?R=2)?b${/()\1/}`).toThrow();
+    expect(() => regex({plugins: [recursion]})`(?<n>a|\g<n&R=2>${/()\1/})`).toThrow();
+    expect(() => regex({plugins: [recursion]})`(?<n>a|\g<n&R=2>)${/()\1/}`).toThrow();
+    expect(() => regex({plugins: [recursion]})`${/()\1/}a(?R=2)?b`).toThrow();
+    expect(() => regex({plugins: [recursion]})`(?<n>${/()\1/}a|\g<n&R=2>)`).toThrow();
+    expect(() => regex({plugins: [recursion]})`${/()\1/}(?<n>a|\g<n&R=2>)`).toThrow();
   });
 
-  it('should not allow definition groups when using recursion', () => {
-    expect(() => rregex`a(?R=2)?b(?(DEFINE))`).toThrow();
-    expect(() => rregex`(?<n>a|\g<n&R=2>)(?(DEFINE))`).toThrow();
+  it('should not allow subroutine definition groups when using recursion', () => {
+    expect(() => regex({plugins: [recursion]})`a(?R=2)?b(?(DEFINE))`).toThrow();
+    expect(() => regex({plugins: [recursion]})`(?<n>a|\g<n&R=2>)(?(DEFINE))`).toThrow();
   });
 });

spec/recursion-spec.js

@@ -1,21 +1,5 @@
-import {regex} from 'regex';
 import {Context, forEachUnescaped, getGroupContents, hasUnescaped, replaceUnescaped} from 'regex-utilities';
 
-export function rregex(first, ...values) {
-  const plugins = (first?.plugins || []).concat(recursion);
-  // Given a template
-  if (Array.isArray(first?.raw)) {
-    return regex({flags: '', plugins})(first, ...values);
-  // Given flags
-  } else if ((typeof first === 'string' || first === undefined) && !values.length) {
-    return regex({flags: first, plugins});
-  // Given an options object
-  } else if ({}.toString.call(first) === '[object Object]' && !values.length) {
-    return regex({...first, plugins});
-  }
-  throw new Error(`Unexpected arguments: ${JSON.stringify([first, ...values])}`);
-}
-
 const gRToken = String.raw`\\g<(?<gRName>[^>&]+)&R=(?<gRDepth>\d+)>`;
 const recursiveToken = String.raw`\(\?R=(?<rDepth>\d+)\)|${gRToken}`;
 const namedCapturingDelim = String.raw`\(\?<(?![=!])(?<captureName>[^>]+)>`;