0
# Core Pattern Matching
1

2
Primary glob pattern matching functionality for filtering arrays of strings against one or more patterns. These functions form the foundation of nanomatch's pattern matching capabilities.
3

4
## Capabilities
5

6
### Main Function
7

8
The primary entry point for nanomatch pattern matching operations.
9

10
```javascript { .api }
11
/**
12
 * Match array of strings against one or more glob patterns
13
 * @param {Array} list - Array of strings to match against patterns
14
 * @param {String|Array} patterns - One or more glob patterns for matching
15
 * @param {Object} options - Optional configuration object
16
 * @returns {Array} Array of strings that match the patterns
17
 */
18
function nanomatch(list, patterns, options);
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
const nanomatch = require('nanomatch');
25

26
// Single pattern matching
27
const files = ['a.js', 'b.txt', 'c.js'];
28
console.log(nanomatch(files, '*.js'));
29
//=> ['a.js', 'c.js']
30

31
// Multiple patterns with negation
32
console.log(nanomatch(files, ['*.js', '!a.js']));
33
//=> ['c.js']
34

35
// Globstar patterns for nested paths
36
const paths = ['src/index.js', 'lib/utils.js', 'docs/readme.md'];
37
console.log(nanomatch(paths, 'src/**'));
38
//=> ['src/index.js']
39

40
// Empty results for non-matching patterns
41
console.log(nanomatch(files, '*.php'));
42
//=> []
43
```
44

45
### Single Pattern Matching
46

47
Match an array of strings against a single glob pattern.
48

49
```javascript { .api }
50
/**
51
 * Match array of strings against a single glob pattern
52
 * @param {Array} list - Array of strings to match
53
 * @param {String} pattern - Single glob pattern (not array)
54
 * @param {Object} options - Optional configuration object
55
 * @returns {Array} Array of strings matching the pattern
56
 */
57
nanomatch.match(list, pattern, options);
58
```
59

60
**Usage Examples:**
61

62
```javascript
63
const nanomatch = require('nanomatch');
64

65
// Basic pattern matching
66
const items = ['foo.js', 'bar.txt', 'baz.js'];
67
console.log(nanomatch.match(items, '*.js'));
68
//=> ['foo.js', 'baz.js']
69

70
// Question mark patterns
71
console.log(nanomatch.match(['a1', 'a2', 'ab'], 'a?'));
72
//=> ['a1', 'a2']
73

74
// Bracket patterns
75
console.log(nanomatch.match(['a1', 'b2', 'c3'], '[ab]*'));
76
//=> ['a1', 'b2']
77

78
// With options
79
console.log(nanomatch.match(['Foo.JS', 'bar.txt'], '*.js', { nocase: true }));
80
//=> ['Foo.JS']
81
```
82

83
### String Pattern Testing
84

85
Test whether a single string matches a glob pattern.
86

87
```javascript { .api }
88
/**
89
 * Test if a string matches a glob pattern
90
 * @param {String} string - String to test against pattern
91
 * @param {String} pattern - Glob pattern to match against
92
 * @param {Object} options - Optional configuration object
93
 * @returns {Boolean} True if string matches pattern, false otherwise
94
 */
95
nanomatch.isMatch(string, pattern, options);
96
```
97

98
**Usage Examples:**
99

100
```javascript
101
const nanomatch = require('nanomatch');
102

103
// Basic matching
104
console.log(nanomatch.isMatch('foo.js', '*.js'));
105
//=> true
106

107
console.log(nanomatch.isMatch('foo.txt', '*.js'));
108
//=> false
109

110
// Globstar matching
111
console.log(nanomatch.isMatch('src/lib/utils.js', '**/utils.js'));
112
//=> true
113

114
console.log(nanomatch.isMatch('docs/readme.md', 'src/**'));
115
//=> false
116

117
// Negation patterns
118
console.log(nanomatch.isMatch('test.js', '!*.js'));
119
//=> false
120

121
// Case sensitivity
122
console.log(nanomatch.isMatch('Foo.JS', '*.js'));
123
//=> false
124

125
console.log(nanomatch.isMatch('Foo.JS', '*.js', { nocase: true }));
126
//=> true
127

128
// Dotfile matching
129
console.log(nanomatch.isMatch('.gitignore', '*'));
130
//=> false
131

132
console.log(nanomatch.isMatch('.gitignore', '*', { dot: true }));
133
//=> true
134
```
135

136
## Pattern Syntax
137

138
### Wildcards
139

140
- `*` - Matches zero or more characters except path separators
141
- `**` - Matches zero or more directories and subdirectories  
142
- `?` - Matches exactly one character except path separators
143
- `[abc]` - Matches any character in the bracket set
144
- `[a-z]` - Matches any character in the range
145
- `[!abc]` or `[^abc]` - Matches any character not in the set
146

147
### Special Behaviors
148

149
- **Negation**: Patterns starting with `!` exclude matches
150
- **Dotfiles**: Hidden files (starting with `.`) require explicit matching or `dot: true` option
151
- **Path Separators**: Patterns handle both forward and backslashes on Windows
152
- **Case Sensitivity**: Matching is case-sensitive by default, use `nocase: true` for insensitive matching
153

154
## Error Handling
155

156
```javascript
157
// TypeError for invalid inputs
158
try {
159
  nanomatch.isMatch(123, '*.js');
160
} catch (error) {
161
  console.log(error.message);
162
  //=> 'expected a string: "123"'
163
}
164

165
// TypeError for array pattern in match()
166
try {
167
  nanomatch.match(['foo.js'], ['*.js']);
168
} catch (error) {
169
  console.log(error.message); 
170
  //=> 'expected pattern to be a string'
171
}
172

173
// Empty string handling
174
console.log(nanomatch.isMatch('', ''));
175
//=> false
176

177
console.log(nanomatch.isMatch('foo', ''));
178
//=> false
179
```