Pattern Building and Utilities

/**
 * Builds regexes using named subpatterns for readability and pattern reuse
 * @param pattern - XRegExp pattern using {{name}} for embedded subpatterns
 * @param subs - Lookup object for named subpatterns (values can be strings or regexes)
 * @param flags - Any combination of XRegExp flags
 * @returns Regex with interpolated subpatterns
 */
function build(pattern: string, subs: Record<string, string | RegExp>, flags?: string): RegExp;

// Basic subpattern building
const time = XRegExp.build('(?x)^ {{hours}} ({{minutes}}) $', {
  hours: XRegExp.build('{{h12}} : | {{h24}}', {
    h12: /1[0-2]|0?[1-9]/,
    h24: /2[0-3]|[01][0-9]/
  }, 'x'),
  minutes: /^[0-5][0-9]$/
});

time.test('10:59'); // true
XRegExp.exec('10:59', time).groups.minutes; // '59'

// Shorthand for named groups: ({{name}}) becomes (?<name>{{name}})
const urlPattern = XRegExp.build('({{protocol}})://({{domain}})({{path}})?', {
  protocol: 'https?',
  domain: '[\\\\w.-]+',
  path: '/.*'
});

/**
 * Creates tagged template literal handler for regex construction
 * @param flags - Any combination of XRegExp flags
 * @returns Handler for template literals that construct regexes with XRegExp syntax
 */
function tag(flags?: string): (literals: TemplateStringsArray, ...substitutions: any[]) => RegExp;

// Basic tagged template usage
XRegExp.tag()`\\\\b\\\\w+\\\\b`.test('word'); // true

// With flags and interpolation
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'

// Backreference rewriting in interpolated regexes
const backref1 = /(a)\\\\1/;
const backref2 = /(b)\\\\1/;
XRegExp.tag()`${backref1}${backref2}`.test('aabb'); // true

/**
 * Returns XRegExp object that is union of given patterns
 * @param patterns - Array of regexes and strings to combine
 * @param flags - Any combination of XRegExp flags
 * @param options - Options object with conjunction property
 * @returns Union of the provided regexes and strings
 */
function union(patterns: (string | RegExp)[], flags?: string, options?: UnionOptions): RegExp;

interface UnionOptions {
  conjunction?: 'or' | 'none';
}

// Standard union with 'or' conjunction
XRegExp.union(['a+b*c', /(dogs)\\\\1/, /(cats)\\\\1/], 'i');
// Result: /a\\+b\\*c|(dogs)\\1|(cats)\\2/i

// Concatenation with 'none' conjunction
XRegExp.union([/man/, /bear/, /pig/], 'i', {conjunction: 'none'});
// Result: /manbearpig/i

// Mixed patterns with automatic escaping
XRegExp.union([
  'literal.string',  // Escaped: literal\\.string
  /\\d+/,            // Used as-is with backreference renumbering
  '(optional)?'      // Escaped: \\(optional\\)\\?
], 'g');

/**
 * Escapes any regular expression metacharacters for literal string matching
 * @param str - String to escape
 * @returns String with regex metacharacters escaped
 */
function escape(str: string): string;

// Basic escaping
XRegExp.escape('Escaped? <.>');
// Result: 'Escaped\\?\\u0020<\\.>'

// Safe for use in any regex context
const userInput = 'user.input[special]';
const literal = XRegExp.escape(userInput);
const regex = XRegExp(`start${literal}end`);

// Useful for building dynamic patterns
const searchTerms = ['hello.world', 'test[case]', 'special?chars'];
const escapedTerms = searchTerms.map(XRegExp.escape);
const pattern = XRegExp.union(escapedTerms, 'gi');

// Basic substitution: {{name}}
const basic = XRegExp.build('{{digit}}+', {
  digit: '\\\\d'
});

// Named group shorthand: ({{name}}) becomes (?<name>{{name}})
const named = XRegExp.build('({{year}})-({{month}})', {
  year: '\\\\d{4}',
  month: '\\\\d{2}'
});
// Equivalent to: (?<year>\\d{4})-(?<month>\\d{2})

const pattern = XRegExp.build('start{{middle}}end', {
  middle: /^\\d+$/  // Anchors are stripped
});
// Result pattern can match within larger strings

const pattern = XRegExp.build('{{first}}{{second}}', {
  first: /(\\w)\\1/,    // Uses \\1
  second: /(\\d)\\1/    // \\1 becomes \\2 in final pattern
});
// Final pattern handles backreferences correctly

// No need to double-escape backslashes
const regex1 = XRegExp.tag()`\\d+\\w*`;      // Works correctly
const regex2 = XRegExp('\\\\d+\\\\w*');      // Equivalent but requires escaping

// Strings are escaped, regexes preserve structure
const userPattern = 'user.input';  // String - will be escaped
const numberPattern = /\\d+/;      // Regex - used as-is

const combined = XRegExp.tag()`${userPattern}:${numberPattern}`;
// userPattern becomes literal, numberPattern remains regex

const pattern1 = /(.)\\1/;     // Matches doubled characters
const pattern2 = /(.)\\1/;     // Another doubled character pattern

const combined = XRegExp.tag()`${pattern1}-${pattern2}`;
// Backreferences are renumbered: /(.)\\1/-(.)\\2/
combined.test('aa-bb'); // true

const timePattern = XRegExp.build('{{time}}', {
  time: XRegExp.build('{{hours}}:{{minutes}}', {
    hours: XRegExp.build('{{h12}}|{{h24}}', {
      h12: '1[0-2]|0?[1-9]',
      h24: '2[0-3]|[01][0-9]'
    }),
    minutes: '[0-5][0-9]'
  })
});

const pattern = XRegExp.build('(?xi) {{spaced}} {{pattern}}', {
  spaced: 'word1   word2',  // Spaces ignored due to x flag
  pattern: '# This is a comment\\n\\\\d+'
});

function createChoicePattern(choices, flags = '') {
  const escapedChoices = choices.map(XRegExp.escape);
  return XRegExp.union(escapedChoices, flags);
}

// Create pattern matching any of the provided options
const keywords = ['class', 'function', 'const', 'let'];
const keywordPattern = createChoicePattern(keywords, 'gi');