0
# Boolean Testing
1

2
Functions that return boolean values for pattern matching tests, including single string tests, collection-based tests, and partial matching capabilities.
3

4
## Capabilities
5

6
### String Matching Test
7

8
Tests if a single string matches any of the given glob patterns.
9

10
```javascript { .api }
11
/**
12
 * Returns true if any of the given glob patterns match the specified string
13
 * @param {string} str - The string to test
14
 * @param {string|string[]} patterns - One or more glob patterns to use for matching
15
 * @param {object} options - See available options for changing how matches are performed
16
 * @returns {boolean} Returns true if any patterns match str
17
 */
18
function isMatch(str, patterns, options);
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
const { isMatch } = require('micromatch');
25

26
// Basic string matching
27
console.log(isMatch('foo.js', '*.js')); //=> true
28
console.log(isMatch('foo.txt', '*.js')); //=> false
29

30
// Multiple patterns
31
console.log(isMatch('a.a', ['b.*', '*.a'])); //=> true
32

33
// With options
34
console.log(isMatch('Foo.JS', '*.js', { nocase: true })); //=> true
35
```
36

37
### Any Method (Alias)
38

39
Backwards compatibility alias for `isMatch`.
40

41
```javascript { .api }
42
/**
43
 * Alias for isMatch() - backwards compatibility
44
 * @param {string} str - The string to test
45
 * @param {string|string[]} patterns - One or more glob patterns
46
 * @param {object} options - See available options
47
 * @returns {boolean} Returns true if any patterns match str
48
 */
49
micromatch.any = isMatch;
50
```
51

52
### Matcher Function Creation
53

54
Creates a reusable matcher function from a glob pattern for efficient repeated testing.
55

56
```javascript { .api }
57
/**
58
 * Returns a matcher function from the given glob pattern and options
59
 * @param {string} pattern - Glob pattern
60
 * @param {object} options - See available options
61
 * @returns {function} Returns a matcher function that takes a string and returns boolean
62
 */
63
function matcher(pattern, options);
64
```
65

66
**Usage Examples:**
67

68
```javascript
69
const { matcher } = require('micromatch');
70

71
// Create reusable matcher
72
const isJavaScript = matcher('*.js');
73
console.log(isJavaScript('app.js')); //=> true
74
console.log(isJavaScript('style.css')); //=> false
75

76
// With negation
77
const isNotTest = matcher('!*.test.js');
78
console.log(isNotTest('app.js')); //=> true
79
console.log(isNotTest('app.test.js')); //=> false
80
```
81

82
### Partial String Matching
83

84
Tests if a string contains a pattern anywhere within it (not just exact matching).
85

86
```javascript { .api }
87
/**
88
 * Returns true if the given string contains the given pattern
89
 * @param {string} str - The string to match
90
 * @param {string|string[]} patterns - Glob pattern to use for matching
91
 * @param {object} options - See available options for changing how matches are performed
92
 * @returns {boolean} Returns true if any of the patterns matches any part of str
93
 */
94
function contains(str, pattern, options);
95
```
96

97
**Usage Examples:**
98

99
```javascript
100
const { contains } = require('micromatch');
101

102
// Partial matching
103
console.log(contains('aa/bb/cc', '*b')); //=> true
104
console.log(contains('aa/bb/cc', '*d')); //=> false
105

106
// Path segments
107
console.log(contains('path/to/file.js', 'to')); //=> true
108
```
109

110
### Collection Testing - Some
111

112
Tests if some strings in a collection match any of the given patterns.
113

114
```javascript { .api }
115
/**
116
 * Returns true if some of the strings in the given list match any of the given glob patterns
117
 * @param {string|string[]} list - The string or array of strings to test
118
 * @param {string|string[]} patterns - One or more glob patterns to use for matching
119
 * @param {object} options - See available options for changing how matches are performed
120
 * @returns {boolean} Returns true if any patterns matches any of the strings in list
121
 */
122
function some(list, patterns, options);
123
```
124

125
**Usage Examples:**
126

127
```javascript
128
const { some } = require('micromatch');
129

130
console.log(some(['foo.js', 'bar.js'], ['*.js', '!foo.js'])); //=> true
131
console.log(some(['foo.js'], ['*.js', '!foo.js'])); //=> false
132
```
133

134
### Collection Testing - Every
135

136
Tests if every string in a collection matches any of the given patterns.
137

138
```javascript { .api }
139
/**
140
 * Returns true if every string in the given list matches any of the given glob patterns
141
 * @param {string|string[]} list - The string or array of strings to test
142
 * @param {string|string[]} patterns - One or more glob patterns to use for matching
143
 * @param {object} options - See available options for changing how matches are performed
144
 * @returns {boolean} Returns true if all patterns matches all of the strings in list
145
 */
146
function every(list, patterns, options);
147
```
148

149
**Usage Examples:**
150

151
```javascript
152
const { every } = require('micromatch');
153

154
console.log(every('foo.js', ['foo.js'])); //=> true
155
console.log(every(['foo.js', 'bar.js'], ['*.js'])); //=> true
156
console.log(every(['foo.js', 'bar.js'], ['*.js', '!foo.js'])); //=> false
157
```
158

159
### All Patterns Matching
160

161
Tests if ALL given patterns match a single string (stricter than `isMatch` which tests if ANY pattern matches).
162

163
```javascript { .api }
164
/**
165
 * Returns true if all of the given patterns match the specified string
166
 * @param {string} str - The string to test
167
 * @param {string|string[]} patterns - One or more glob patterns to use for matching
168
 * @param {object} options - See available options for changing how matches are performed
169
 * @returns {boolean} Returns true if all patterns match str
170
 */
171
function all(str, patterns, options);
172
```
173

174
**Usage Examples:**
175

176
```javascript
177
const { all } = require('micromatch');
178

179
console.log(all('foo.js', ['foo.js'])); //=> true
180
console.log(all('foo.js', ['*.js', '!foo.js'])); //=> false
181
console.log(all('foo.js', ['*.js', 'foo.js'])); //=> true
182
console.log(all('foo.js', ['*.js', 'f*', '*o*', '*o.js'])); //=> true
183
```
184

185
## Error Handling
186

187
- Throws `TypeError` for invalid string input in `contains()` function
188
- Returns `false` for non-matching patterns (does not throw)
189
- Handles empty strings and patterns gracefully