Picomatch

<h1 align="center">Picomatch</h1> <p align="center"> <a href="https://npmjs.org/package/picomatch"> <img src="https://img.shields.io/npm/v/picomatch.svg" alt="version"> </a> <a href="https://github.com/micromatch/picomatch/actions/workflows/test.yml"> <img src="https://github.com/micromatch/picomatch/actions/workflows/test.yml/badge.svg?branch=master" alt="test status"> </a> <a href="https://coveralls.io/github/micromatch/picomatch"> <img src="https://img.shields.io/coveralls/github/micromatch/picomatch/master.svg" alt="coverage status"> </a> <a href="https://npmjs.org/package/picomatch"> <img src="https://img.shields.io/npm/dw/picomatch" alt="downloads"> </a> </p> <br> <br> <p align="center"> <strong>Blazing fast and accurate glob matcher written in JavaScript.</strong></br> <em>No dependencies and full support for standard and extended Bash glob features, including braces, extglobs, POSIX brackets, and regular expressions.</em> </p> <br> <br>

Why picomatch?

• Lightweight - No dependencies
• Minimal - Tiny API surface. Main export is a function that takes a glob pattern and returns a matcher function.
• Fast - Loads in about 2ms (that's several times faster than a single frame of a HD movie at 60fps)
• Performant - Use the returned matcher function to speed up repeat matching (like when watching files)
• Accurate matching - Using wildcards (* and ?), globstars (**) for nested directories, advanced globbing with extglobs, braces, and POSIX brackets, and support for escaping special characters with \ or quotes.
• Well tested - Thousands of unit tests

See the library comparison to other libraries.

<br> <br>

Table of Contents

<details><summary> Click to expand </summary>

• Install
• Usage
• API
  • picomatch
  • .test
  • .matchBase
  • .isMatch
  • .parse
  • .scan
  • .compileRe
  • .makeRe
  • .toRegex
• Options
  • Picomatch options
  • Scan Options
  • Options Examples
• Globbing features
  • Basic globbing
  • Advanced globbing
  • Braces
  • Matching special characters as literals
• Library Comparisons
• Benchmarks
• Philosophies
• About
  • Author
  • License

(TOC generated by verb using markdown-toc)

</details> <br> <br>

Install

Install with npm:

npm install --save picomatch

<br>

Usage

The main export is a function that takes a glob pattern and an options object and returns a function for matching strings.

const pm = require('picomatch');
const isMatch = pm('*.js');

console.log(isMatch('abcd')); //=> false
console.log(isMatch('a.js')); //=> true
console.log(isMatch('a.md')); //=> false
console.log(isMatch('a/b.js')); //=> false

<br>

API

picomatch

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. The returned matcher function also takes a boolean as the second argument that, when true, returns an object with additional information.

Params

• globs {String|Array}: One or more glob patterns.
• options {Object=}
• returns {Function=}: Returns a matcher function.

Example

const picomatch = require('picomatch');
// picomatch(glob[, options]);

const isMatch = picomatch('*.!(*a)');
console.log(isMatch('a.a')); //=> false
console.log(isMatch('a.b')); //=> true

Example without node.js

For environments without node.js, picomatch/posix provides you a dependency-free matcher, without automatic OS detection.

const picomatch = require('picomatch/posix');
// the same API, defaulting to posix paths
const isMatch = picomatch('a/*');
console.log(isMatch('a\\b')); //=> false
console.log(isMatch('a/b')); //=> true

// you can still configure the matcher function to accept windows paths
const isMatch = picomatch('a/*', { options: windows });
console.log(isMatch('a\\b')); //=> true
console.log(isMatch('a/b')); //=> true

.test

Test input with the given regex. This is used by the main picomatch() function to test the input string.

Params

• input {String}: String to test.
• regex {RegExp}
• returns {Object}: Returns an object with matching info.

Example

const picomatch = require('picomatch');
// picomatch.test(input, regex[, options]);

console.log(picomatch.test('foo/bar', /^(?:([^/]*?)\/([^/]*?))$/));
// { isMatch: true, match: [ 'foo/', 'foo', 'bar' ], output: 'foo/bar' }

.matchBase

Match the basename of a filepath.

Params

• input {String}: String to test.
• glob {RegExp|String}: Glob pattern or regex created by .makeRe.
• returns {Boolean}

Example

const picomatch = require('picomatch');
// picomatch.matchBase(input, glob[, options]);
console.log(picomatch.matchBase('foo/bar.js', '*.js'); // true

.isMatch

Returns true if any of the given glob patterns match the specified string.

Params

• {String|Array}: str The string to test.
• {String|Array}: patterns One or more glob patterns to use for matching.
• {Object}: See available options.
• returns {Boolean}: Returns true if any patterns match str

Example

const picomatch = require('picomatch');
// picomatch.isMatch(string, patterns[, options]);

console.log(picomatch.isMatch('a.a', ['b.*', '*.a'])); //=> true
console.log(picomatch.isMatch('a.a', 'b.*')); //=> false

.parse

Parse a glob pattern to create the source string for a regular expression.

Params

• pattern {String}
• options {Object}
• returns {Object}: Returns an object with useful properties and output to be used as a regex source string.

Example

const picomatch = require('picomatch');
const result = picomatch.parse(pattern[, options]);

.scan

Scan a glob pattern to separate the pattern into segments.

Params

• input {String}: Glob pattern to scan.
• options {Object}
• returns {Object}: Returns an object with

Example

const picomatch = require('picomatch');
// picomatch.scan(input[, options]);

const result = picomatch.scan('!./foo/*.js');
console.log(result);
{ prefix: '!./',
  input: '!./foo/*.js',
  start: 3,
  base: 'foo',
  glob: '*.js',
  isBrace: false,
  isBracket: false,
  isGlob: true,
  isExtglob: false,
  isGlobstar: false,
  negated: true }

.compileRe

Compile a regular expression from the state object returned by the parse() method.

Params

• state {Object}
• options {Object}
• returnOutput {Boolean}: Intended for implementors, this argument allows you to return the raw output from the parser.
• returnState {Boolean}: Adds the state to a state property on the returned regex. Useful for implementors and debugging.
• returns {RegExp}

Example

const picomatch = require('picomatch');
const state = picomatch.parse('*.js');
// picomatch.compileRe(state[, options]);

console.log(picomatch.compileRe(state));
//=> /^(?:(?!\.)(?=.)[^/]*?\.js)$/

.makeRe

Create a regular expression from a parsed glob pattern.

Params

• state {String}: The object returned from the .parse method.
• options {Object}
• returnOutput {Boolean}: Implementors may use this argument to return the compiled output, instead of a regular expression. This is not exposed on the options to prevent end-users from mutating the result.
• returnState {Boolean}: Implementors may use this argument to return the state from the parsed glob with the returned regular expression.
• returns {RegExp}: Returns a regex created from the given pattern.

Example

const picomatch = require('picomatch');
// picomatch.makeRe(state[, options]);

const result = picomatch.makeRe('*.js');
console.log(result);
//=> /^(?:(?!\.)(?=.)[^/]*?\.js)$/

.toRegex

Create a regular expression from the given regex source string.

Params

• source {String}: Regular expression source string.
• options {Object}
• returns {RegExp}

Example

const picomatch = require('picomatch');
// picomatch.toRegex(source[, options]);

const { output } = picomatch.parse('*.js');
console.log(picomatch.toRegex(output));
//=> /^(?:(?!\.)(?=.)[^/]*?\.js)$/

<br>

Options

Picomatch options

The following options may be used with the main picomatch() function or any of the methods on the picomatch API.

| Option | Type | Default value | Description | | --- | --- | --- | --- | | basename | boolean | false | If set, then patterns without slashes will be matched against the basename of the path if it contains slashes. For example, a?b would match the path /xyz/123/acb, but not /xyz/acb/123. | | bash | boolean | false | Follow bash matching rules more strictly - disallows backslashes as escape characters, and treats single stars as globstars (**). | | capture | boolean | undefined | Return regex matches in supporting methods. | | contains | `bo