README
Planckmatch
Small and simple matching library using glob patterns.
Install
$ npm install planckmatch
Functions
planckmatch(value, patterns, options, path)
Matches extended glob patterns with a given value.
Returns: Boolean
or Array of Booleans
value
: A value to match to.- Type:
String
orArray of strings
- Required:
true
- Type:
patterns
: An extended glob pattern or array of extended glob patterns.- Type:
String
orArray of strings
- Required:
true
- Type:
options
: Options for conversion of glob pattern to regular expression.- Type:
Object
- Default:
{}
- Type:
path
: Whether to use platform specific path separators in the expression. For instance when set to true,path/to/file
will be treated aspath/to/file
on Unix and aspath\\to\\file
on Windows.- Type:
Boolean
- Default:
false
- Type:
planckmatch.all(value, patterns, options, path)
Same as planckmatch(value, patterns, options, path)
except it always returns a single boolean with whether all of the patterns matched.
Returns: Boolean
planckmatch.any(value, patterns, options, path)
Same as planckmatch(value, patterns, options, path)
except it always returns a single boolean with whether any of the patterns matched.
Returns: Boolean
planckmatch.parse(patterns, options, path)
Parses extended glob patterns into regular expressions.
Returns: RegExp
or Array of RegExps
patterns
: An extended glob pattern or array of extended glob patterns.- Type:
String
orArray of strings
- Required:
true
- Type:
options
: Options for conversion of glob pattern to regular expression.- Type:
Object
- Default:
{}
- Type:
path
: Whether to use platform specific path separators in the expression. For instance when set to true,path/to/file
will be treated aspath/to/file
on Unix and aspath\\to\\file
on Windows.- Type:
Boolean
- Default:
false
- Type:
planckmatch.match(value, expressions)
Matches regular expressions with a given value.
Returns: Boolean
or Array of Booleans
value
: A value to match to.- Type:
String
orArray of strings
- Required:
true
- Type:
expressions
: A RegExp or array of RegExp used to match with.- Type:
RegExp
orArray of RegExps
- Required:
true
- Type:
planckmatch.match.all(value, expressions)
Same as planckmatch.match(value, expressions)
except it always returns a single boolean with whether all of the patterns matched.
Returns: Boolean
planckmatch.match.any(value, expressions)
Same as planckmatch.match(value, expressions)
except it always returns a single boolean with whether any of the patterns matched.
Returns: Boolean
Options
Options for conversion of glob pattern to regular expression.
options.extended
: Enable all advanced features fromextglob
.- Type:
Boolean
- Default:
false
- Type:
options.flags
: RegExp flags (e.g.'i'
) to pass to the RegExp constructor.- Type:
String
- Default:
''
- Type:
options.globstar
: Iffalse
the pattern'path/*'
will match any string beginning with'path/'
, for example it will match'path/file.txt'
and'path/to/file.txt'
. Iftrue
the same'path/*'
will match any string beginning with'path/'
that does not have a'/'
to the right of it, for example it will match'path/file.txt'
but not'path/to/file.txt'
. Iftrue
the pattern'path/**'
will match any string beginning with'path/'
, which is equal to the'path/*'
with globstar set to false.- Type:
Boolean
- Default:
false
- Type:
options.strict
: Be forgiving about multiple slashes, such as///
and make everything after the first/
optional. Like how bash glob works.- Type:
Boolean
- Default:
false
- Type:
Usage
The most basic example using a single path and pattern.
const planckmatch = require(`planckmatch`);
planckmatch(`path/to/file.css`, `**/*.css`); // true
planckmatch(`path/to/file.css`, `**/*.js`); // false
Multiple patterns
The pattern can also be an array, therefor the returned results will also be an array of equal length.
const planckmatch = require(`planckmatch`);
planckmatch(`path/to/file.css`, [
`*.css`,
`*.js`
]); // [ true, false ]
Re-use patterns
If you re-use patterns I highly recommend parsing the patterns and matching the values direct instead of using the all-in-one function for it, as it parses the patterns each time.
const planckmatch = require(`planckmatch`);
const expression = planckmatch.parse(`*.css`);
planckmatch.match(`path/to/file.css`, expression); // true
planckmatch.match(`path/to/file.js`, expression); // false
Match all
Check if all patterns match.
const planckmatch = require(`planckmatch`);
planckmatch.all(`path/to/file.css`, [ `*.html`, `*/to/*` ]); // false, since `*.html` does not match.
planckmatch.all(`path/to/file.css`, [ `*.css`, `*/to/*` ]); // true, since all patterns match.
Match any
Check if any pattern matches.
const planckmatch = require(`planckmatch`);
planckmatch.any(`path/to/file.css`, [ `*.html`, `to/*` ]); // false, since no pattern matches.
planckmatch.any(`path/to/file.css`, [ `*.css`, `to/*` ]); // true, since the first pattern matches.
planckmatch.any(`path/to/file.css`, [ `*.css`, `*/to/*` ]); // true, since both patterns match.
Filter array
Use the module to filter an array.
const planckmatch = require(`planckmatch`);
let expressions = planckmatch.parse([
`a.*`,
`*.html`
]);
// Match all.
[ `a.css`, `b.html`, `c.js` ].filter(function(value) {
return planckmatch.match.all(value, expressions);
}); // []
// Match any.
[ `a.css`, `b.html`, `c.js` ].filter(function(value) {
return planckmatch.match.any(value, expressions);
}); // [ `a.css`, `b.html` ]
// Filter out any '.css' files.
expressions = planckmatch.parse([
`*`,
`!(*.css)`
], { extended: true });
[ `a.css`, `b.html`, `c.js` ].filter(function(value) {
return planckmatch.match.all(value, expressions);
}); // [ `b.html`, `c.js` ]