Regular Expression Construction

/**
 * Creates an extended regular expression object with additional syntax and flags
 * @param pattern - Regex pattern string or existing regex object to copy
 * @param flags - Any combination of flags
 * @returns Extended regular expression object
 */
function XRegExp(pattern: string | RegExp, flags?: string): RegExp;

// Basic usage with named capture
const regex = XRegExp('(?<word>\\w+)', 'g');

// Free-spacing mode with comments
const date = XRegExp(`
  (?<year>  [0-9]{4} ) -?  # year
  (?<month> [0-9]{2} ) -?  # month
  (?<day>   [0-9]{2} )     # day
`, 'x');

// Copy existing regex
const copy = XRegExp(/test/gi);

// Dot matches all (including newlines)
const multiline = XRegExp('start.*end', 's');

// Unicode property matching
const unicode = XRegExp('\\p{Letter}+', 'A');

/**
 * Caches and returns the result of calling XRegExp(pattern, flags)
 * @param pattern - Regex pattern string
 * @param flags - Any combination of XRegExp flags
 * @returns Cached XRegExp object
 */
function cache(pattern: string, flags?: string): RegExp;

// Compiled once, reused multiple times
let match;
while (match = XRegExp.cache('.', 'gs').exec('abc')) {
  // The regex is compiled once only
}

/**
 * Copies a regex object and adds global flag
 * @param regex - Regex to globalize
 * @returns Copy of regex with global flag added
 */
function globalize(regex: RegExp): RegExp;

/**
 * Cross-frame regex detection
 * @param value - Object to check
 * @returns Whether the object is a RegExp
 */
function isRegExp(value: any): value is RegExp;

/**
 * XRegExp version number
 */
const version: string;

// Add global flag to existing regex
const globalRegex = XRegExp.globalize(/test/i);
console.log(globalRegex.global); // true

// Safe regex detection across frames
XRegExp.isRegExp(/test/); // true
XRegExp.isRegExp('string'); // false

// Get version
console.log(XRegExp.version); // '5.1.2'

// Named capture groups
const nameRegex = XRegExp('(?<first>\\w+) (?<last>\\w+)');
const match = XRegExp.exec('John Smith', nameRegex);
console.log(match.groups.first); // 'John'
console.log(match.groups.last);  // 'Smith'

// Named backreferences
const doubled = XRegExp('(?<word>\\w+)\\s+\\k<word>', 'i');
doubled.test('hello hello'); // true

// Named replacements
XRegExp.replace('John Smith', nameRegex, '$<last>, $<first>');
// Result: 'Smith, John'

const complexRegex = XRegExp(`
  ^                    # Start of string
  (?<protocol> https?) # Protocol (http or https)
  ://                  # Separator
  (?<domain>           # Domain group
    [\\w.-]+           # Domain characters
  )
  (?<path> /.*)?       # Optional path
  $                    # End of string
`, 'x');

const multilineRegex = XRegExp('start.*end', 's');
multilineRegex.test('start\\nend'); // true

const namedOnly = XRegExp('(\\d+)(?<name>\\w+)(\\d+)', 'n');
// Equivalent to: (?:\\d+)(?<name>\\w+)(?:\\d+)