0
# Core Functions
1

2
The three main convenience functions provide simple access to RegexPP's most common regex processing operations without requiring class instantiation.
3

4
## Capabilities
5

6
### Parse RegExp Literal
7

8
Parses a regular expression literal string or RegExp object into an Abstract Syntax Tree.
9

10
```typescript { .api }
11
/**
12
 * Parse a given regular expression literal then make AST object.
13
 * This is equivalent to `new RegExpParser(options).parseLiteral(String(source))`
14
 * @param source - The source code to parse (string like "/abc/gi" or RegExp object)
15
 * @param options - The parsing options
16
 * @returns The AST of the regular expression
17
 */
18
function parseRegExpLiteral(
19
  source: string | RegExp,
20
  options?: RegExpParser.Options,
21
): AST.RegExpLiteral;
22
```
23

24
**Usage Examples:**
25

26
```typescript
27
import { parseRegExpLiteral } from "regexpp";
28

29
// Parse from string literal
30
const ast1 = parseRegExpLiteral("/[a-z]+/gi");
31
console.log(ast1.pattern.alternatives[0].elements.length); // Number of elements
32

33
// Parse from RegExp object  
34
const ast2 = parseRegExpLiteral(new RegExp("[0-9]+", "g"));
35
console.log(ast2.flags.global); // true
36

37
// Parse with options
38
const ast3 = parseRegExpLiteral("/(?<=\\w)\\d+/", {
39
  ecmaVersion: 2018,  // Enable lookbehind assertions
40
  strict: false
41
});
42
```
43

44
### Validate RegExp Literal
45

46
Validates the syntax of a regular expression literal string without generating an AST.
47

48
```typescript { .api }
49
/**
50
 * Validate a given regular expression literal.
51
 * This is equivalent to `new RegExpValidator(options).validateLiteral(source)`
52
 * @param source - The source code to validate (string like "/abc/gi")
53
 * @param options - The validation options
54
 * @throws {RegExpSyntaxError} If the regex has invalid syntax
55
 */
56
function validateRegExpLiteral(
57
  source: string,
58
  options?: RegExpValidator.Options,
59
): void;
60
```
61

62
**Usage Examples:**
63

64
```typescript
65
import { validateRegExpLiteral } from "regexpp";
66

67
// Basic validation
68
try {
69
  validateRegExpLiteral("/[a-z]+/gi");
70
  console.log("Valid regex");
71
} catch (error) {
72
  console.log("Invalid regex:", error.message);
73
}
74

75
// Validation with specific ECMAScript version
76
try {
77
  validateRegExpLiteral("/(?<=\\w)\\d+/", {
78
    ecmaVersion: 2017  // This will throw - lookbehind requires ES2018
79
  });
80
} catch (error) {
81
  console.log("Feature not supported in ES2017");
82
}
83

84
// Strict mode validation (disables Annex B features)
85
try {
86
  validateRegExpLiteral("/\\8/", {
87
    strict: true  // This will throw - \\8 is Annex B syntax
88
  });
89
} catch (error) {
90
  console.log("Annex B syntax not allowed in strict mode");
91
}
92
```
93

94
### Visit RegExp AST
95

96
Traverses an Abstract Syntax Tree using the visitor pattern with custom callbacks.
97

98
```typescript { .api }
99
/**
100
 * Visit each node of a given AST.
101
 * This is equivalent to `new RegExpVisitor(handlers).visit(node)`
102
 * @param node - The AST node to visit (typically the root RegExpLiteral)
103
 * @param handlers - The visitor callbacks for different node types
104
 */
105
function visitRegExpAST(
106
  node: AST.Node,
107
  handlers: RegExpVisitor.Handlers,
108
): void;
109
```
110

111
**Usage Examples:**
112

113
```typescript
114
import { parseRegExpLiteral, visitRegExpAST } from "regexpp";
115

116
const ast = parseRegExpLiteral("/[a-z]+(\\d{2,4})?/gi");
117

118
// Count different node types
119
let counts = { characters: 0, quantifiers: 0, groups: 0 };
120

121
visitRegExpAST(ast, {
122
  onCharacterEnter(node) {
123
    counts.characters++;
124
  },
125
  onQuantifierEnter(node) {
126
    counts.quantifiers++;
127
    console.log(`Found quantifier: ${node.raw} (min: ${node.min}, max: ${node.max})`);
128
  },
129
  onCapturingGroupEnter(node) {
130
    counts.groups++;
131
    console.log(`Found capturing group: ${node.name || 'unnamed'}`);
132
  }
133
});
134

135
console.log(counts); // { characters: X, quantifiers: Y, groups: Z }
136

137
// Extract all character classes
138
const characterClasses: string[] = [];
139
visitRegExpAST(ast, {
140
  onCharacterClassEnter(node) {
141
    characterClasses.push(node.raw);
142
  }
143
});
144
console.log(characterClasses); // ["[a-z]"]
145
```
146

147
## Types
148

149
```typescript { .api }
150
// Options interfaces used by core functions
151
interface RegExpParser.Options {
152
  /** The flag to disable Annex B syntax. Default is false */
153
  strict?: boolean;
154
  /** ECMAScript version. Default is 2022 */
155
  ecmaVersion?: EcmaVersion;
156
}
157

158
interface RegExpValidator.Options {
159
  /** The flag to disable Annex B syntax. Default is false */
160
  strict?: boolean;
161
  /** ECMAScript version. Default is 2022 */
162
  ecmaVersion?: EcmaVersion;
163
  // Plus many optional validation callback functions
164
}
165

166
interface RegExpVisitor.Handlers {
167
  // Optional callback functions for each AST node type
168
  onRegExpLiteralEnter?(node: AST.RegExpLiteral): void;
169
  onRegExpLiteralLeave?(node: AST.RegExpLiteral): void;
170
  onPatternEnter?(node: AST.Pattern): void;
171
  onPatternLeave?(node: AST.Pattern): void;
172
  // ... many more callback options for all node types
173
}
174

175
type EcmaVersion = 5 | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022;
176
```