0
# Regular Expression Construction
1

2
Core functionality for creating extended regular expressions with additional syntax and flags beyond native JavaScript support.
3

4
## Capabilities
5

6
### XRegExp Constructor
7

8
Creates an extended regular expression object with additional syntax and flags.
9

10
```javascript { .api }
11
/**
12
 * Creates an extended regular expression object with additional syntax and flags
13
 * @param pattern - Regex pattern string or existing regex object to copy
14
 * @param flags - Any combination of flags
15
 * @returns Extended regular expression object
16
 */
17
function XRegExp(pattern: string | RegExp, flags?: string): RegExp;
18
```
19

20
**Supported Flags:**
21
- Native flags: `d` (indices), `g` (global), `i` (ignore case), `m` (multiline), `u` (unicode), `y` (sticky)
22
- XRegExp flags: `n` (named capture only), `s` (dot matches all), `x` (free-spacing), `A` (astral Unicode)
23

24
**Usage Examples:**
25

26
```javascript
27
// Basic usage with named capture
28
const regex = XRegExp('(?<word>\\w+)', 'g');
29

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

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

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

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

47
### Cache Function
48

49
Caches and returns cached XRegExp objects for performance.
50

51
```javascript { .api }
52
/**
53
 * Caches and returns the result of calling XRegExp(pattern, flags)
54
 * @param pattern - Regex pattern string
55
 * @param flags - Any combination of XRegExp flags
56
 * @returns Cached XRegExp object
57
 */
58
function cache(pattern: string, flags?: string): RegExp;
59
```
60

61
**Usage Examples:**
62

63
```javascript
64
// Compiled once, reused multiple times
65
let match;
66
while (match = XRegExp.cache('.', 'gs').exec('abc')) {
67
  // The regex is compiled once only
68
}
69
```
70

71
### Utility Functions
72

73
Helper functions for regex manipulation and inspection.
74

75
```javascript { .api }
76
/**
77
 * Copies a regex object and adds global flag
78
 * @param regex - Regex to globalize
79
 * @returns Copy of regex with global flag added
80
 */
81
function globalize(regex: RegExp): RegExp;
82

83
/**
84
 * Cross-frame regex detection
85
 * @param value - Object to check
86
 * @returns Whether the object is a RegExp
87
 */
88
function isRegExp(value: any): value is RegExp;
89

90
/**
91
 * XRegExp version number
92
 */
93
const version: string;
94
```
95

96
**Usage Examples:**
97

98
```javascript
99
// Add global flag to existing regex
100
const globalRegex = XRegExp.globalize(/test/i);
101
console.log(globalRegex.global); // true
102

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

107
// Get version
108
console.log(XRegExp.version); // '5.1.2'
109
```
110

111
## Named Capture Groups
112

113
XRegExp provides enhanced named capture group support:
114

115
**Named Capture Syntax:**
116
- `(?<name>pattern)` - Create named capture group
117
- `\\k<name>` - Named backreference
118
- `$<name>` or `${name}` - Named replacement
119

120
**Usage Examples:**
121

122
```javascript
123
// Named capture groups
124
const nameRegex = XRegExp('(?<first>\\w+) (?<last>\\w+)');
125
const match = XRegExp.exec('John Smith', nameRegex);
126
console.log(match.groups.first); // 'John'
127
console.log(match.groups.last);  // 'Smith'
128

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

133
// Named replacements
134
XRegExp.replace('John Smith', nameRegex, '$<last>, $<first>');
135
// Result: 'Smith, John'
136
```
137

138
## Extended Syntax Features
139

140
### Free-spacing Mode (Flag x)
141

142
Allows whitespace and comments in regex patterns:
143

144
```javascript
145
const complexRegex = XRegExp(`
146
  ^                    # Start of string
147
  (?<protocol> https?) # Protocol (http or https)
148
  ://                  # Separator
149
  (?<domain>           # Domain group
150
    [\\w.-]+           # Domain characters
151
  )
152
  (?<path> /.*)?       # Optional path
153
  $                    # End of string
154
`, 'x');
155
```
156

157
### Dot Matches All (Flag s)
158

159
Makes dot (.) match newline characters:
160

161
```javascript
162
const multilineRegex = XRegExp('start.*end', 's');
163
multilineRegex.test('start\\nend'); // true
164
```
165

166
### Named Capture Only (Flag n)
167

168
Converts all capturing groups to non-capturing except named ones:
169

170
```javascript
171
const namedOnly = XRegExp('(\\d+)(?<name>\\w+)(\\d+)', 'n');
172
// Equivalent to: (?:\\d+)(?<name>\\w+)(?:\\d+)
173
```