0
# Pattern Processing
1

2
Advanced pattern manipulation functions for creating regular expressions, parsing patterns, analyzing pattern structure, and extracting captured groups from matches.
3

4
## Capabilities
5

6
### Regular Expression Creation
7

8
Creates a regular expression from a glob pattern for advanced pattern matching or integration with other regex-based tools.
9

10
```javascript { .api }
11
/**
12
 * Create a regular expression from the given glob pattern
13
 * @param {string} pattern - A glob pattern to convert to regex
14
 * @param {object} options - See available options
15
 * @returns {RegExp} Returns a regex created from the given pattern
16
 */
17
function makeRe(pattern, options);
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
const { makeRe } = require('micromatch');
24

25
// Basic regex creation
26
const regex = makeRe('*.js');
27
console.log(regex);
28
//=> /^(?:(\.[\\\/])?(?!\.)(?=.)[^\/]*?\.js)$/
29

30
// Test with created regex
31
console.log(regex.test('app.js')); //=> true
32
console.log(regex.test('app.txt')); //=> false
33

34
// With options
35
const caseInsensitive = makeRe('*.JS', { nocase: true });
36
console.log(caseInsensitive.test('app.js')); //=> true
37
```
38

39
### Pattern Parsing
40

41
Parses glob patterns to create source strings for regular expressions, with support for brace expansion preprocessing.
42

43
```javascript { .api }
44
/**
45
 * Parse a glob pattern to create the source string for a regular expression
46
 * @param {string|string[]} patterns - Glob patterns to parse
47
 * @param {object} options - See available options
48
 * @returns {object[]} Returns array of parsed pattern objects with useful properties
49
 */
50
function parse(patterns, options);
51
```
52

53
**Usage Examples:**
54

55
```javascript
56
const { parse } = require('micromatch');
57

58
// Parse single pattern
59
const parsed = parse('src/**/*.js');
60
console.log(parsed[0].output); // Regex source string
61
console.log(parsed[0].state);  // Parse state and metadata
62

63
// Parse with brace expansion
64
const bracePatterns = parse('src/{app,lib}/*.js');
65
// Returns separate parsed objects for 'src/app/*.js' and 'src/lib/*.js'
66
```
67

68
### Pattern Scanning
69

70
Scans a glob pattern to separate it into segments for detailed analysis of pattern structure.
71

72
```javascript { .api }
73
/**
74
 * Scan a glob pattern to separate the pattern into segments
75
 * @param {string} pattern - Pattern to scan
76
 * @param {object} options - See available options
77
 * @returns {object} Returns an object with pattern segments and metadata
78
 */
79
function scan(pattern, options);
80
```
81

82
**Usage Examples:**
83

84
```javascript
85
const { scan } = require('micromatch');
86

87
// Scan pattern structure  
88
const scanned = scan('src/**/*.{js,ts}');
89
console.log(scanned.parts);     // Pattern segments
90
console.log(scanned.globstar);  // Boolean: contains **
91
console.log(scanned.negated);   // Boolean: is negated pattern
92
```
93

94
### Capture Groups
95

96
Extracts captured groups from pattern matches, useful for extracting specific parts of matched strings.
97

98
```javascript { .api }
99
/**
100
 * Returns an array of matches captured by pattern in string, or null if no match
101
 * @param {string} glob - Glob pattern to use for matching
102
 * @param {string} input - String to match against
103
 * @param {object} options - See available options for changing how matches are performed
104
 * @returns {string[]|null} Returns array of captures if match found, otherwise null
105
 */
106
function capture(glob, input, options);
107
```
108

109
**Usage Examples:**
110

111
```javascript
112
const { capture } = require('micromatch');
113

114
// Basic capture
115
console.log(capture('test/*.js', 'test/foo.js'));
116
//=> ['foo']
117

118
// No match returns null
119
console.log(capture('test/*.js', 'src/bar.js'));
120
//=> null
121

122
// Multiple captures
123
console.log(capture('src/*/test/*.js', 'src/components/test/button.js'));
124
//=> ['components', 'button']
125

126
// Named directory capture
127
console.log(capture('**/docs/**/*.md', 'project/docs/api/readme.md'));
128
//=> ['project', 'api', 'readme']
129
```
130

131
## Advanced Pattern Features
132

133
### Brace Preprocessing  
134

135
The `parse()` function automatically processes brace patterns before parsing:
136

137
```javascript
138
// Input: 'src/{app,lib}/*.js'
139
// Expands to: ['src/app/*.js', 'src/lib/*.js']
140
// Then parses each expanded pattern separately
141
```
142

143
### Pattern State Information
144

145
Parsed patterns include detailed state information:
146

147
- `output` - The regex source string
148
- `state.negated` - Boolean indicating negation
149
- `state.globstar` - Boolean indicating globstar usage
150
- `state.extglob` - Boolean indicating extglob usage
151
- And many other metadata properties
152

153
### Cross-Platform Handling
154

155
Pattern processing functions handle path separator differences:
156

157
- Automatically converts Windows backslashes when needed
158
- Respects `posixSlashes` option for consistent forward slash output
159
- Handles platform-specific path patterns correctly
160

161
## Integration with Picomatch
162

163
These functions largely delegate to the underlying `picomatch` library:
164

165
- `makeRe()` calls `picomatch.makeRe()`
166
- `scan()` calls `picomatch.scan()`  
167
- `parse()` adds brace expansion preprocessing before `picomatch.parse()`
168
- `capture()` uses `picomatch.makeRe()` with capture option enabled
169

170
This ensures consistent behavior with the core matching engine while providing convenient high-level interfaces.