Skip to content
Small and simple matching library using glob patterns.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github
benchmark
library
test
.editorconfig
.eslintrc.json
.gitignore
.travis.yml
CHANGELOG.md
DCO
LICENSE
README.md
match.js
package-lock.json
package.json
parse.js

README.md

npm package @latest npm package @next

Travis-ci build master branch CodeCov coverage master branch

License agreement Open issues on GitHub

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 or Array of strings
    • Required: true
  • patterns: An extended glob pattern or array of extended glob patterns.
    • Type: String or Array of strings
    • Required: true
  • options: Options for conversion of glob pattern to regular expression.
    • Type: Object
    • Default: {}
  • path: Whether to use platform specific path separators in the expression. For instance when set to true, path/to/file will be treated as path/to/file on Unix and as path\\to\\file on Windows.
    • Type: Boolean
    • Default: false

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 or Array of strings
    • Required: true
  • options: Options for conversion of glob pattern to regular expression.
    • Type: Object
    • Default: {}
  • path: Whether to use platform specific path separators in the expression. For instance when set to true, path/to/file will be treated as path/to/file on Unix and as path\\to\\file on Windows.
    • Type: Boolean
    • Default: false

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 or Array of strings
    • Required: true
  • expressions: A RegExp or array of RegExp used to match with.
    • Type: RegExp or Array of RegExps
    • Required: true

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 from extglob.
    • Type: Boolean
    • Default: false
  • options.flags: RegExp flags (e.g. 'i' ) to pass to the RegExp constructor.
    • Type: String
    • Default: ''
  • options.globstar: If false the pattern 'path/*' will match any string beginning with 'path/', for example it will match 'path/file.txt' and 'path/to/file.txt'. If true 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'. If true 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
  • 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

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` ]

License

ISC license

You can’t perform that action at this time.