0
# Pattern Parsing
1

2
Low-level pattern parsing and regex compilation utilities for advanced use cases and custom implementations.
3

4
## Capabilities
5

6
### Parse Method
7

8
Parse a glob pattern to create the source string for a regular expression.
9

10
```javascript { .api }
11
/**
12
 * Parse a glob pattern to create source string for regex
13
 * @param {string|string[]} pattern - Glob pattern(s) to parse
14
 * @param {object} options - Configuration options
15
 * @returns {object|object[]} Parsed pattern object(s) with tokens and metadata
16
 */
17
picomatch.parse(pattern, options);
18

19
interface ParseResult {
20
  input: string;
21
  tokens: Token[];
22
  output: string;
23
  regex: RegExp;
24
  negated: boolean;
25
  fastpaths: boolean;
26
  // Additional parsing metadata
27
}
28

29
interface Token {
30
  type: string;
31
  value: string;
32
  output?: string;
33
  // Token-specific properties
34
}
35
```
36

37
**Usage Examples:**
38

39
```javascript
40
const picomatch = require('picomatch');
41

42
// Parse single pattern
43
const result = picomatch.parse('*.js');
44
console.log(result.input);    // => '*.js'
45
console.log(result.output);   // => '(?:(?!\.)(?=.)[^/]*?\.js)'
46
console.log(result.tokens);   // => [{ type: 'star', value: '*' }, ...]
47

48
// Parse multiple patterns
49
const results = picomatch.parse(['*.js', '*.ts']);
50
console.log(results[0].output); // => parsed output for *.js
51
console.log(results[1].output); // => parsed output for *.ts
52

53
// Parse with options
54
const parsed = picomatch.parse('src/**/*.js', {
55
  fastpaths: false,
56
  strictSlashes: true
57
});
58
console.log(parsed.tokens); // => detailed token array
59
```
60

61
### Scan Method
62

63
Scan a glob pattern to separate the pattern into segments and analyze its structure.
64

65
```javascript { .api }
66
/**
67
 * Scan glob pattern to separate into segments
68
 * @param {string} input - Glob pattern to scan
69
 * @param {object} options - Configuration options
70
 * @returns {object} Scan result with pattern analysis
71
 */
72
picomatch.scan(input, options);
73

74
interface ScanResult {
75
  prefix: string;
76
  input: string;
77
  start: number;
78
  base: string;
79
  glob: string;
80
  isBrace: boolean;
81
  isBracket: boolean;
82
  isGlob: boolean;
83
  isExtglob: boolean;
84
  isGlobstar: boolean;
85
  negated: boolean;
86
  // Additional scan metadata
87
}
88
```
89

90
**Usage Examples:**
91

92
```javascript
93
// Scan basic pattern
94
const scan1 = picomatch.scan('*.js');
95
console.log(scan1.isGlob);      // => true
96
console.log(scan1.base);        // => ''
97
console.log(scan1.glob);        // => '*.js'
98

99
// Scan complex pattern
100
const scan2 = picomatch.scan('!./src/**/*.js');
101
console.log(scan2.negated);     // => true
102
console.log(scan2.prefix);      // => '!./'
103
console.log(scan2.base);        // => 'src'
104
console.log(scan2.glob);        // => '**/*.js'
105
console.log(scan2.isGlobstar);  // => true
106

107
// Scan brace pattern
108
const scan3 = picomatch.scan('*.{js,ts}');
109
console.log(scan3.isBrace);     // => true
110
console.log(scan3.isGlob);      // => true
111

112
// Scan extglob pattern
113
const scan4 = picomatch.scan('*.+(js|ts)');
114
console.log(scan4.isExtglob);   // => true
115

116
// Scan with options
117
const scanResult = picomatch.scan('/path/to/*.js', {
118
  parts: true
119
});
120
```
121

122
### MakeRe Method
123

124
Create a regular expression from a glob pattern.
125

126
```javascript { .api }
127
/**
128
 * Create regular expression from glob pattern
129
 * @param {string} input - Glob pattern
130
 * @param {object} options - Configuration options
131
 * @param {boolean} returnOutput - Return output string instead of regex
132
 * @param {boolean} returnState - Include state in result
133
 * @returns {RegExp|string} Compiled regular expression or source string
134
 */
135
picomatch.makeRe(input, options, returnOutput, returnState);
136
```
137

138
**Usage Examples:**
139

140
```javascript
141
// Create regex
142
const regex1 = picomatch.makeRe('*.js');
143
console.log(regex1.test('file.js'));   // => true
144
console.log(regex1.test('file.txt'));  // => false
145

146
// Get regex source string
147
const source = picomatch.makeRe('*.js', {}, true);
148
console.log(source); // => '^(?:(?!\.)(?=.)[^/]*?\.js)$'
149

150
// With returnState option
151
const regexWithState = picomatch.makeRe('*.js', {}, false, true);
152
console.log(regexWithState.state); // => { /* parsing state */ }
153

154
// Complex patterns
155
const complexRegex = picomatch.makeRe('src/**/*.{js,ts}');
156
console.log(complexRegex.test('src/utils/helper.js')); // => true
157
console.log(complexRegex.test('src/deep/nested/app.ts')); // => true
158

159
// With options
160
const winRegex = picomatch.makeRe('src\\**\\*.js', { windows: true });
161
const nocaseRegex = picomatch.makeRe('*.JS', { nocase: true });
162
console.log(nocaseRegex.test('file.js')); // => true
163
```
164

165
### CompileRe Method
166

167
Compile a regular expression from a parsed state object.
168

169
```javascript { .api }
170
/**
171
 * Compile regex from parsed state object
172
 * @param {object} state - Parsed state from parse() method
173
 * @param {object} options - Configuration options
174
 * @param {boolean} returnOutput - Return output string instead of regex
175
 * @param {boolean} returnState - Include state in result
176
 * @returns {RegExp|string} Compiled regular expression or source string
177
 */
178
picomatch.compileRe(state, options, returnOutput, returnState);
179
```
180

181
**Usage Examples:**
182

183
```javascript
184
// Two-step compilation
185
const state = picomatch.parse('*.js');
186
const regex = picomatch.compileRe(state);
187
console.log(regex.test('file.js')); // => true
188

189
// Get compiled output string
190
const output = picomatch.compileRe(state, {}, true);
191
console.log(output); // => '^(?:(?!\.)(?=.)[^/]*?\.js)$'
192

193
// Compile with options
194
const compiledRegex = picomatch.compileRe(state, {
195
  contains: true  // Remove anchors
196
});
197

198
// Compile with state
199
const regexWithState = picomatch.compileRe(state, {}, false, true);
200
console.log(regexWithState.state === state); // => true
201
```
202

203
### ToRegex Method
204

205
Create a regular expression from a regex source string.
206

207
```javascript { .api }
208
/**
209
 * Create regex from source string
210
 * @param {string} source - Regular expression source string
211
 * @param {object} options - Configuration options
212
 * @returns {RegExp} Regular expression object
213
 */
214
picomatch.toRegex(source, options);
215
```
216

217
**Usage Examples:**
218

219
```javascript
220
// Create regex from source
221
const regex1 = picomatch.toRegex('^(?:.*\\.js)$');
222
console.log(regex1.test('file.js')); // => true
223

224
// With flags
225
const regex2 = picomatch.toRegex('.*\\.js', { flags: 'i' });
226
console.log(regex2.test('FILE.JS')); // => true
227

228
// Case insensitive option
229
const regex3 = picomatch.toRegex('.*\\.JS', { nocase: true });
230
console.log(regex3.test('file.js')); // => true
231

232
// Error handling with debug
233
try {
234
  const badRegex = picomatch.toRegex('[invalid regex', { debug: true });
235
} catch (error) {
236
  console.log('Invalid regex pattern');
237
}
238

239
// Without debug (returns fallback regex)
240
const fallbackRegex = picomatch.toRegex('[invalid', { debug: false });
241
console.log(fallbackRegex.test('anything')); // => false (/$^/ fallback)
242
```
243

244
## Advanced Parsing Examples
245

246
**Working with Tokens:**
247

248
```javascript
249
// Analyze pattern structure
250
const parsed = picomatch.parse('src/**/+(*.js|*.ts)');
251
parsed.tokens.forEach(token => {
252
  console.log(`${token.type}: ${token.value}`);
253
});
254
// Output shows: text, globstar, text, extglob tokens
255

256
// Custom token processing
257
const customParsed = picomatch.parse('*.{js,ts,json}');
258
const braceTokens = customParsed.tokens.filter(t => t.type === 'brace');
259
console.log(braceTokens); // => brace expansion tokens
260
```
261

262
**Pattern Optimization:**
263

264
```javascript
265
// Fast path detection
266
const fastPattern = picomatch.parse('*.js');
267
console.log(fastPattern.fastpaths); // => true (optimized)
268

269
const complexPattern = picomatch.parse('src/**/+(*.js|*.ts)');
270
console.log(complexPattern.fastpaths); // => false (complex parsing)
271

272
// Disable fast paths for consistent parsing
273
const slowParsed = picomatch.parse('*.js', { fastpaths: false });
274
console.log(slowParsed.tokens.length); // => more detailed tokens
275
```