0
# Core Matching
1

2
Core matcher function creation and pattern matching capabilities. The main entry point for creating efficient matcher functions from glob patterns.
3

4
## Capabilities
5

6
### Main Picomatch Function
7

8
Creates a matcher function from one or more glob patterns. The returned function takes a string to match as its first argument and returns true if the string is a match.
9

10
```javascript { .api }
11
/**
12
 * Creates a matcher function from one or more glob patterns
13
 * @param {string|string[]} glob - One or more glob patterns
14
 * @param {object} options - Configuration options
15
 * @param {boolean} returnState - Whether to return state information with matcher
16
 * @returns {function} Matcher function
17
 */
18
function picomatch(glob, options, returnState = false);
19

20
/**
21
 * Matcher function returned by picomatch()
22
 * @param {string} input - String to test against pattern
23
 * @param {boolean} returnObject - Whether to return detailed result object
24
 * @returns {boolean|object} Match result
25
 */
26
type MatcherFunction = (input: string, returnObject?: boolean) => boolean | MatchResult;
27
```
28

29
**Usage Examples:**
30

31
```javascript
32
const picomatch = require('picomatch');
33

34
// Single pattern
35
const isMatch = picomatch('*.js');
36
console.log(isMatch('file.js'));    // => true
37
console.log(isMatch('file.txt'));   // => false
38

39
// Multiple patterns - returns true if ANY pattern matches
40
const isMatchAny = picomatch(['*.js', '*.ts', '*.json']);
41
console.log(isMatchAny('config.json')); // => true
42

43
// Get detailed result object
44
const matcher = picomatch('src/**/*.js');
45
const result = matcher('src/utils/helper.js', true);
46
console.log(result.isMatch); // => true
47
console.log(result.output);  // => 'src/utils/helper.js'
48

49
// With returnState option
50
const matcherWithState = picomatch('*.js', {}, true);
51
console.log(matcherWithState.state); // => { /* parsed state object */ }
52
```
53

54
### Pattern Matching with Options
55

56
Advanced pattern matching with configuration options for fine-tuned behavior.
57

58
```javascript { .api }
59
/**
60
 * Create matcher with options
61
 * @param {string} pattern - Glob pattern
62
 * @param {PicomatchOptions} options - Configuration options
63
 * @returns {function} Configured matcher function
64
 */
65
function picomatch(pattern, options);
66
```
67

68
**Usage Examples:**
69

70
```javascript
71
// Case insensitive matching
72
const matcher = picomatch('*.JS', { nocase: true });
73
console.log(matcher('file.js')); // => true
74

75
// Ignore specific patterns
76
const isMatch = picomatch('**/*.js', { 
77
  ignore: ['**/node_modules/**', '**/test/**'] 
78
});
79
console.log(isMatch('src/app.js'));           // => true
80
console.log(isMatch('node_modules/lib.js'));  // => false
81

82
// Windows path handling
83
const winMatcher = picomatch('src\\**\\*.js', { windows: true });
84
console.log(winMatcher('src\\utils\\file.js')); // => true
85

86
// Match only basename
87
const baseMatcher = picomatch('*.js', { basename: true });
88
console.log(baseMatcher('path/to/file.js')); // => true
89

90
// Custom callbacks
91
const callbackMatcher = picomatch('*.js', {
92
  onMatch: (result) => console.log('Matched:', result.input),
93
  onResult: (result) => console.log('Tested:', result.input)
94
});
95
```
96

97
### Multi-Pattern Matching
98

99
Handle arrays of glob patterns efficiently.
100

101
```javascript { .api }
102
/**
103
 * Create matcher for multiple patterns
104
 * @param {string[]} patterns - Array of glob patterns
105
 * @param {PicomatchOptions} options - Configuration options
106
 * @returns {function} Matcher that returns true if ANY pattern matches
107
 */
108
function picomatch(patterns, options);
109
```
110

111
**Usage Examples:**
112

113
```javascript
114
// Multiple file extensions
115
const isSourceFile = picomatch(['*.js', '*.ts', '*.jsx', '*.tsx']);
116
console.log(isSourceFile('component.jsx')); // => true
117

118
// Complex pattern combinations
119
const isTestFile = picomatch([
120
  '**/*.test.js',
121
  '**/*.spec.js', 
122
  '**/test/**/*.js',
123
  '**/__tests__/**/*.js'
124
]);
125
console.log(isTestFile('src/utils.test.js')); // => true
126
console.log(isTestFile('__tests__/app.js'));  // => true
127

128
// Mixed patterns with options
129
const matcher = picomatch(['src/**/*.js', 'lib/**/*.ts'], {
130
  ignore: '**/node_modules/**'
131
});
132
```
133

134
## Types
135

136
```javascript { .api }
137
interface PicomatchOptions {
138
  /** Force Windows-style path handling */
139
  windows?: boolean;
140
  /** Patterns to ignore */
141
  ignore?: string | string[];
142
  /** Callback for match events */
143
  onMatch?: (result: MatchResult) => void;
144
  /** Callback for all results */
145
  onResult?: (result: MatchResult) => void;
146
  /** Callback for ignored matches */
147
  onIgnore?: (result: MatchResult) => void;
148
  /** Enable/disable fast path optimizations */
149
  fastpaths?: boolean;
150
  /** Custom path format function */
151
  format?: (path: string) => string;
152
  /** Enable capture groups */
153
  capture?: boolean;
154
  /** Match anywhere in string (not anchored) */
155
  contains?: boolean;
156
  /** Match only basename (equivalent to basename) */
157
  basename?: boolean;
158
  /** Match only basename */
159
  matchBase?: boolean;
160
  /** Case insensitive matching */
161
  nocase?: boolean;
162
  /** Enable debug mode */
163
  debug?: boolean;
164
  /** Custom regex flags */
165
  flags?: string;
166
  /** Disable globstars (**) */
167
  noglobstar?: boolean;
168
  /** Disable extglobs (+(a|b)) */
169
  noextglob?: boolean;
170
  /** Disable braces ({a,b}) */
171
  nobrace?: boolean;
172
  /** Disable brackets ([abc]) */
173
  nobracket?: boolean;
174
  /** Custom expand range function for brackets */
175
  expandRange?: (left: string, right: string, options: object) => string;
176
  /** Strict slash handling */
177
  strictSlashes?: boolean;
178
  /** Unescape regex characters */
179
  unescape?: boolean;
180
  /** Maximum regex length */
181
  maxLength?: number;
182
  /** POSIX character classes */
183
  posix?: boolean;
184
  /** Dot handling in patterns */
185
  dot?: boolean;
186
  /** Custom star replacement */
187
  star?: string;
188
  /** Bash compatibility mode */
189
  bash?: boolean;
190
}
191

192
interface MatchResult {
193
  /** Original glob pattern */
194
  glob: string;
195
  /** Parsed state object */
196
  state: {
197
    input: string;
198
    tokens: Token[];
199
    output: string;
200
    negated: boolean;
201
    fastpaths: boolean;
202
  };
203
  /** Compiled regular expression */
204
  regex: RegExp;
205
  /** Whether POSIX mode is enabled */
206
  posix: boolean;
207
  /** Input string being tested */
208
  input: string;
209
  /** Formatted output string */
210
  output: string;
211
  /** Regex match result */
212
  match: RegExpExecArray | null;
213
  /** Whether the pattern matched */
214
  isMatch: boolean;
215
}
216

217
interface Token {
218
  /** Token type (star, text, globstar, etc.) */
219
  type: string;
220
  /** Token value */
221
  value: string;
222
  /** Compiled output for token */
223
  output?: string;
224
  /** Whether token is escaped */
225
  escaped?: boolean;
226
  /** Whether token is negated */
227
  negated?: boolean;
228
}
229
```