0
# XRegExp
1

2
XRegExp provides augmented and extensible JavaScript regular expressions. You get modern syntax and flags beyond what browsers support natively, including named capture groups, Unicode property matching, free-spacing syntax with comments, and cross-browser compatibility fixes. XRegExp compiles to native RegExp objects for optimal performance while extending functionality with additional features.
3

4
## Package Information
5

6
- **Package Name**: xregexp
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES6+ with TypeScript definitions)
9
- **Installation**: `npm install xregexp`
10

11
## Core Imports
12

13
```javascript
14
import XRegExp from "xregexp";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const XRegExp = require("xregexp");
21
```
22

23
## Basic Usage
24

25
```javascript
26
import XRegExp from "xregexp";
27

28
// Named capture groups with free-spacing mode
29
const date = XRegExp(`
30
  (?<year>  [0-9]{4} ) -?  # year
31
  (?<month> [0-9]{2} ) -?  # month  
32
  (?<day>   [0-9]{2} )     # day
33
`, 'x');
34

35
// Enhanced exec with named captures
36
const match = XRegExp.exec('2021-02-22', date);
37
console.log(match.groups.year);  // '2021'
38

39
// Enhanced replace with named backreferences
40
const formatted = XRegExp.replace('2021-02-22', date, '$<month>/$<day>/$<year>');
41
console.log(formatted); // '02/22/2021'
42

43
// Unicode property matching
44
const identifier = XRegExp('\\p{Letter}[\\p{Letter}\\p{Number}]*', 'A');
45
identifier.test('變數名'); // true
46
```
47

48
## Architecture
49

50
XRegExp is built around several key components:
51

52
- **Core Constructor**: Enhanced RegExp constructor with extended syntax and flags
53
- **Static Methods**: Enhanced versions of String methods (exec, match, replace, etc.) with named capture support
54
- **Token System**: Extensible syntax system allowing custom tokens and flags via addons
55
- **Unicode Support**: Comprehensive Unicode property, category, and script matching
56
- **Cross-browser Fixes**: Consistent behavior across different JavaScript engines
57
- **Addon Architecture**: Modular extensions for additional functionality
58

59
## Capabilities
60

61
### Regular Expression Construction
62

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

65
```javascript { .api }
66
/**
67
 * Creates an extended regular expression object with additional syntax and flags
68
 * @param pattern - Regex pattern string or existing regex to copy
69
 * @param flags - Any combination of flags (native: dgimsuy, XRegExp: nxsA)
70
 * @returns Extended regular expression object
71
 */
72
function XRegExp(pattern: string | RegExp, flags?: string): RegExp;
73

74
/** XRegExp version number */
75
const version: string;
76
```
77

78
[Regular Expression Construction](./construction.md)
79

80
### Enhanced Execution Methods
81

82
Improved regex execution methods with named capture support, position control, and cross-browser consistency.
83

84
```javascript { .api }
85
/**
86
 * Enhanced exec with named capture support and position/sticky options
87
 * @param str - String to search
88
 * @param regex - Regex to search with
89
 * @param pos - Zero-based index to start search
90
 * @param sticky - Whether match must start at specified position only
91
 * @returns Match array with named capture properties or null
92
 */
93
function exec(str: string, regex: RegExp, pos?: number, sticky?: boolean | 'sticky'): ExecArray | null;
94

95
/**
96
 * Enhanced test with position/sticky support
97
 * @param str - String to search
98
 * @param regex - Regex to search with
99
 * @param pos - Zero-based index to start search
100
 * @param sticky - Whether match must start at specified position only
101
 * @returns Whether the regex matched
102
 */
103
function test(str: string, regex: RegExp, pos?: number, sticky?: boolean | 'sticky'): boolean;
104
```
105

106
[Enhanced Execution Methods](./execution.md)
107

108
### String Processing Methods
109

110
Enhanced string methods with named backreference support and cross-browser fixes.
111

112
```javascript { .api }
113
/**
114
 * Enhanced match method with scope control
115
 * @param str - String to search
116
 * @param regex - Regex to search with
117
 * @param scope - Use 'one' for first match or 'all' for all matches
118
 * @returns First match string, array of matches, or null
119
 */
120
function match(str: string, regex: RegExp, scope?: 'one' | 'all'): string | string[] | null;
121

122
/**
123
 * Enhanced replace with named backreference support
124
 * @param str - String to search
125
 * @param search - Search pattern to replace
126
 * @param replacement - Replacement string or function
127
 * @param scope - Use 'one' to replace first match only or 'all'
128
 * @returns New string with matches replaced
129
 */
130
function replace(str: string, search: RegExp | string, replacement: string | Function, scope?: 'one' | 'all'): string;
131
```
132

133
[String Processing Methods](./string-processing.md)
134

135
### Pattern Building and Utilities
136

137
Advanced pattern construction tools including named subpatterns, template literals, and pattern combination.
138

139
```javascript { .api }
140
/**
141
 * Builds regexes using named subpatterns with automatic backreference renumbering
142
 * @param pattern - XRegExp pattern using {{name}} for embedded subpatterns
143
 * @param subs - Lookup object for named subpatterns (strings or regexes)
144
 * @param flags - Any combination of XRegExp flags
145
 * @returns Regex with interpolated subpatterns
146
 */
147
function build(pattern: string, subs: Record<string, string | RegExp>, flags?: string): RegExp;
148

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

156
/**
157
 * Escapes regex metacharacters for literal matching
158
 * @param str - String to escape
159
 * @returns String with regex metacharacters escaped
160
 */
161
function escape(str: string): string;
162
```
163

164
[Pattern Building and Utilities](./pattern-building.md)
165

166
### Advanced Matching Features
167

168
Specialized matching capabilities including recursive/balanced delimiters and chained matching.
169

170
```javascript { .api }
171
/**
172
 * Matches balanced delimiters with configurable options
173
 * @param str - String to search
174
 * @param left - Left delimiter as XRegExp pattern
175
 * @param right - Right delimiter as XRegExp pattern
176
 * @param flags - Any combination of XRegExp flags
177
 * @param options - Options for value names, escape chars, unbalanced handling
178
 * @returns Array of matches or detailed match objects
179
 */
180
function matchRecursive(str: string, left: string, right: string, flags?: string, options?: MatchRecursiveOptions): string[] | MatchRecursiveValueNameMatch[];
181

182
/**
183
 * Chains regexes for successive matching within previous results
184
 * @param str - String to search
185
 * @param chain - Array of regexes or objects with regex and backref properties
186
 * @returns Matches by the last regex in the chain
187
 */
188
function matchChain(str: string, chain: (RegExp | ChainArrayElement)[]): string[];
189
```
190

191
[Advanced Matching Features](./advanced-matching.md)
192

193
### Unicode Support
194

195
Comprehensive Unicode property, category, and script matching with astral plane support.
196

197
```javascript { .api }
198
/**
199
 * Adds Unicode character data for \\p{} and \\P{} tokens
200
 * @param data - Array of objects with Unicode character ranges
201
 * @param typePrefix - Optional type prefix for all provided tokens
202
 */
203
function addUnicodeData(data: UnicodeCharacterRange[], typePrefix?: string): void;
204
```
205

206
[Unicode Support](./unicode-support.md)
207

208
### Extensibility and Configuration
209

210
Tools for extending XRegExp syntax and managing optional features.
211

212
```javascript { .api }
213
/**
214
 * Extends XRegExp syntax with custom tokens and flags
215
 * @param regex - Regex that matches the new token
216
 * @param handler - Function that returns replacement pattern
217
 * @param options - Options for scope, flags, and behavior
218
 */
219
function addToken(regex: RegExp, handler: Function, options?: TokenOptions): void;
220

221
/**
222
 * Installs or uninstalls optional features
223
 * @param options - Features to install: 'astral', 'namespacing'
224
 */
225
function install(options: string | FeatureOptions): void;
226
function uninstall(options: string | FeatureOptions): void;
227

228
/**
229
 * Checks if optional features are installed
230
 * @param feature - Feature name to check
231
 * @returns Whether the feature is installed
232
 */
233
function isInstalled(feature: 'astral' | 'namespacing'): boolean;
234
```
235

236
[Extensibility and Configuration](./extensibility.md)
237

238
## Types
239

240
```javascript { .api }
241
interface ExecArray extends Array<string> {
242
  index: number;
243
  input: string;
244
  groups?: NamedGroupsArray;
245
  [propName: string]: any;
246
}
247

248
interface NamedGroupsArray {
249
  [key: string]: string;
250
}
251

252
interface ChainArrayElement {
253
  regex: RegExp;
254
  backref: number | string;
255
}
256

257
interface MatchRecursiveOptions {
258
  escapeChar?: string;
259
  valueNames?: [string, string, string, string];
260
  unbalanced?: 'error' | 'skip' | 'skip-lazy';
261
}
262

263
interface MatchRecursiveValueNameMatch {
264
  name: string;
265
  value: string;
266
  start: number;
267
  end: number;
268
}
269

270
interface TokenOptions {
271
  scope?: 'default' | 'class' | 'all';
272
  flag?: string;
273
  optionalFlags?: string;
274
  reparse?: boolean;
275
  leadChar?: string;
276
}
277

278
interface FeatureOptions {
279
  astral?: boolean;
280
  namespacing?: boolean;
281
}
282

283
interface UnicodeCharacterRange {
284
  name: string;
285
  alias?: string;
286
  isBmpLast?: boolean;
287
  inverseOf?: string;
288
  bmp?: string;
289
  astral?: string;
290
}
291
```