Option tmGrammar -> overrides.allowOrphanBackrefs

README.md

@@ -77,8 +77,10 @@ type OnigurumaToEsOptions = {
   global?: boolean;
   hasIndices?: boolean;
   maxRecursionDepth?: number | null;
+  overrides?: {
+    allowOrphanBackrefs?: boolean;
+  };
   target?: 'auto' | 'ES2025' | 'ES2024' | 'ES2018';
-  tmGrammar?: boolean;
   verbose?: boolean;
 };
 ```
@@ -215,6 +217,12 @@ Since recursion isn't infinite-depth like in Oniguruma, use of recursion also re
 Using a high limit has a small impact on performance. Generally, this is only a problem if the regex has an existing issue with runaway backtracking that recursion exacerbates. Higher limits have no effect on regexes that don't use recursion, so you should feel free to increase this if helpful.
 </details>
 
+### `overrides`
+
+Advanced options that take precedence over standard error checking and flags.
+
+- `allowOrphanBackrefs`: Useful with TextMate grammar processors that merge backreferences across `begin` and `end` patterns.
+
 ### `target`
 
 One of `'auto'` *(default)*, `'ES2025'`, `'ES2024'`, or `'ES2018'`.
@@ -235,12 +243,6 @@ JavaScript version used for generated regexes. Using `auto` detects the best val
   - Generated regexes might use features that require Node.js 23 or a 2024-era browser (except Safari, which lacks support for flag groups).
 </details>
 
-### `tmGrammar`
-
-*Default: `false`.*
-
-Leave disabled unless the regex will be used in a TextMate grammar processor that merges backreferences across `begin` and `end` patterns.
-
 ### `verbose`
 
 *Default: `false`.*
@@ -940,7 +942,7 @@ The following features don't yet have any support, and throw errors. They're all
 - Grapheme boundaries: <code>\y</code>, <code>\Y</code>.
 - Grapheme boundary options (flags <code>y{g}</code>, <code>y{w}</code>).
 - Whole-pattern options: don't capture <code>(?C)</code>, ignore-care is ASCII <code>(?I)</code>, find longest <code>(?L)</code>.
-- Absent repeater <code>(?~…)</code>, expression <code>(?~|…|…)</code>, and range cutter <code>(?~|…)</code>.
+- Absent repeater <code>(?\~…)</code>, expression <code>(?\~|…|…)</code>, and range cutter <code>(?\~|…)</code>.
 - Conditionals: <code>(?(…)…)</code>, <code>(?(…)…|…)</code>.
 - Code point sequences: <code>\x{H H …H}</code>, <code>\o{O O …O}</code>.
 - Additional, extremely rare ways to specify characters.

demo/demo.css

@@ -111,8 +111,8 @@ label .tip-lg {
 }
 
 label .tip-xl {
-  width: 320px;
-  margin-left: -160px;
+  width: 300px;
+  margin-left: -150px;
 }
 
 label .tip :is(code, kbd) {

demo/demo.js

@@ -20,6 +20,9 @@ const state = {
     global: getValue('option-global'),
     hasIndices: getValue('option-hasIndices'),
     maxRecursionDepth: getValue('option-maxRecursionDepth'),
+    overrides: {
+      allowOrphanBackrefs: getValue('option-allowOrphanBackrefs'),
+    },
     target: getValue('option-target'),
     verbose: getValue('option-verbose'),
   },
@@ -218,3 +221,8 @@ function setOption(option, value) {
   state.opts[option] = value;
   showTranspiled();
 }
+
+function setOverride(option, value) {
+  state.opts.overrides[option] = value;
+  showTranspiled();
+}

demo/index.html

@@ -118,9 +118,9 @@ <h2>Try it</h2>
           </p>
           <p>
             <label>
-              <input type="checkbox" id="option-tmGrammar" onchange="setOption('tmGrammar', this.checked)">
-              <code>tmGrammar</code>
-              <span class="tip tip-xl">Leave disabled unless the regex will be used in a TextMate grammar processor that merges backrefs across <code>begin</code> and <code>end</code> patterns</span>
+              <input type="checkbox" id="option-allowOrphanBackrefs" onchange="setOverride('allowOrphanBackrefs', this.checked)">
+              <code>allowOrphanBackrefs</code>
+              <span class="tip tip-xl">Useful with TextMate grammar processors that merge backrefs across <code>begin</code> and <code>end</code> patterns</span>
             </label>
           </p>
         </div>

src/index.js

@@ -28,8 +28,10 @@ import {recursion} from 'regex-recursion';
   global?: boolean;
   hasIndices?: boolean;
   maxRecursionDepth?: number | null;
+  overrides?: {
+    allowOrphanBackrefs?: boolean;
+  };
   target?: keyof Target;
-  tmGrammar?: boolean;
   verbose?: boolean;
 }} OnigurumaToEsOptions
 */
@@ -48,7 +50,7 @@ function toDetails(pattern, options) {
   const opts = getOptions(options);
   const tokenized = tokenize(pattern, opts.flags);
   const onigurumaAst = parse(tokenized, {
-    skipBackrefValidation: opts.tmGrammar,
+    skipBackrefValidation: opts.overrides.allowOrphanBackrefs,
     verbose: opts.verbose,
   });
   const regexAst = transform(onigurumaAst, {

src/options.js

@@ -49,12 +49,16 @@ function getOptions(options) {
     // your environment. Later targets allow faster processing, simpler generated source, and
     // support for additional features.
     target: 'auto',
-    // Leave disabled unless the regex will be used in a TextMate grammar processor that merges
-    // backreferences across `begin` and `end` patterns.
-    tmGrammar: false,
     // Disables optimizations that simplify the pattern when it doesn't change the meaning.
     verbose: false,
     ...options,
+    // Advanced options that take precedence over standard error checking and flags.
+    overrides: {
+      // Useful with TextMate grammar processors that merge backreferences across `begin` and `end`
+      // patterns.
+      allowOrphanBackrefs: false,
+      ...(options?.overrides),
+    },
   };
   if (opts.target === 'auto') {
     opts.target = (envSupportsDuplicateNames && envSupportsFlagGroups) ?

src/transform.js

@@ -505,7 +505,7 @@ const ThirdPassVisitor = {
   Backreference({node, replaceWith}, state) {
     if (node.orphan) {
       state.highestOrphanBackref = Math.max(state.highestOrphanBackref, node.ref);
-      // Don't renumber; used with option `tmGrammar`
+      // Don't renumber; used with `allowOrphanBackrefs`
       return;
     }
     const reffedNodes = state.reffedNodesByReferencer.get(node);
@@ -566,7 +566,7 @@ const ThirdPassVisitor = {
       // exist within `end`. This presents a dilemma since both Oniguruma and JS (with flag u/v)
       // error for backrefs to undefined captures. So adding captures to the end is a solution that
       // doesn't change what the regex matches, and lets invalid numbered backrefs through. Note:
-      // Orphan backrefs are only allowed if the `tmGrammar` option is used
+      // Orphan backrefs are only allowed if `allowOrphanBackrefs` is enabled
       const numCapsNeeded = Math.max(state.highestOrphanBackref - state.numCapturesToLeft, 0);
       for (let i = 0; i < numCapsNeeded; i++) {
         const emptyCapture = createCapturingGroup();