Skip to content

Commit

Permalink
run verb to generate readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@jonschlinkert
jonschlinkert committed May 29, 2017
1 parent c3bc209 commit 914059f
Show file tree
Hide file tree
Showing 2 changed files with 211 additions and 233 deletions.
177 changes: 82 additions & 95 deletions .verb.md
View file
@@ -1,5 +1,6 @@
## Quickstart


```js
var mm = require('micromatch');
mm(list, patterns[, options]);
Expand All @@ -8,84 +9,66 @@ mm(list, patterns[, options]);
The [main export](#micromatch) takes a list of strings and one or more glob patterns:

```js
console.log(mm(['foo', 'bar', 'qux'], ['f*', 'b*'])); // ['foo', 'bar']
console.log(mm(['foo', 'bar', 'qux'], ['f*', 'b*']));
//=> ['foo', 'bar']
```

Use [.isMatch](#ismatch) to get true/false:
Use [.isMatch()](#ismatch) to get true/false:

```js
console.log(mm.isMatch('foo', 'f*')); // true
console.log(mm.isMatch('foo', 'f*'));
//=> true
```

**Switching from [minimatch](#switching-from-minimatch) and [multimatch](#switching-from-multimatch) is easy**:

* use [mm.isMatch()](#ismatch) instead of `minimatch()`
* [mm.match()](#match) is the same as `minimatch.match()`
* [mm()](#usage) is the same as `multimatch()`
[Switching](#switching-to-micromatch) from minimatch and multimatch is easy!

**Heads up!**

There is one notable difference between micromatch and minimatch in regards to how backslashes are handled. See [the notes about backslashes](#backslashes) for more information.

## Why use micromatch?

> micromatch is a [drop-in replacement][switch] for minimatch and multimatch
**Speed and accuracy**
> micromatch is a [drop-in replacement](#switching-to-micromatch) for minimatch and multimatch
Micromatch uses [snapdragon][] for parsing and compiling globs, which results in:
- Supports all of the same matching features as [minimatch][] and [multimatch][]
- Micromatch uses [snapdragon][] for parsing and compiling globs, which provides granular control over the entire conversion process in a way that is easy to understand, reason about, and maintain.
- More accurate, with more than 36,000 [test assertions](./test) to prove it.
- More complete support for the Bash 4.3 specification than minimatch and multimatch. Micromatch passes _all of the spec tests_ from bash, including some that bash still fails.
- [Faster matching](#benchmarks), from a combination of optimized glob patterns, faster algorithms, and regex caching.
- [Micromatch is safer][braces]{#braces-is-safe}, and is not subject to DoS with brace patterns, like minimatch and multimatch.
- More reliable windows support than minimatch and multimatch.

- Granular control over the entire conversion process in a way that is easy to understand, reason about, and customize.
- Faster matching, from a combination of optimized glob patterns and (optional) caching.
- Much greater accuracy than minimatch. In fact, nanomatch passes _all of the spec tests_ from bash, including some that bash still fails. However, since there is no real specification for globs, if you encounter a pattern that yields unexpected match results [after researching previous issues](../../issues), [please let us know](../../issues/new).
### Matching features


- [Micromatch is safer](https://github.com/jonschlinkert/braces#braces-is-safe), and is not subject to DoS with brace patterns, like minimatch and multimatch.
- [faster](#benchmarks) matching
- More accurate, with more than 36,000 [unit tests](./test) - and thousands more patterns tested - to prove it. _(minimatch and multimatch fail a great number of the tests)_.
- More complete support for the Bash 4.3 specification than minimatch and multimatch
- More reliable windows support than minimatch and multimatch
- Supports all of the same matching features as [minimatch](https://github.com/isaacs/minimatch) and [multimatch](https://github.com/sindresorhus/multimatch)
- Micromatch uses real parsers and compilers. Although edge cases are inevitable, micromatch is better equipped to handle them.


### Features

* Native support for multiple glob patterns (no need for wrappers like multimatch)
* Basic wildcard support (`**/*`, `a/b/*.js`, or `['a/*.js', '*b.js']`)
* Negation support (`['!a/*.js', '*!(b).js']`)
* [extglob][] support (`+(x|y)`, `!(a|b)`, etc)
* [POSIX character class][brackets] support (`**/[[:alpha:][:digit:]]/`)
* [brace expansion][braces] support (`a/b-{1..5}.md`, `one/{two,three}/four.md`)
* regex character classes (`a/b/baz-[1-5].js`)
* regex logical or (`a/b/(abc|xyz).js`)
* Support for multiple glob patterns (no need for wrappers like multimatch)
* Wildcards (`**`, `*.js`)
* Negation (`'!a/*.js'`, `'*!(b).js']`)
* [extglobs][extglob] (`+(x|y)`, `!(a|b)`)
* [POSIX character classes][brackets] (`[[:alpha:][:digit:]]`)
* [brace expansion][braces] (`foo/{1..5}.md`, `bar/{a,b,c}.js`)
* regex character classes (`foo-[1-5].js`)
* regex logical "or" (`foo/(abc|xyz).js`)

You can mix and match these features to create whatever patterns you need!

**Example**
## Switching to micromatch

```js
mm(['a/b.js', 'a/b.md'], 'a/*.!(js)');
//=> ['a/b.md']
```
There is one notable difference between micromatch and minimatch in regards to how backslashes are handled. See [the notes about backslashes](#backslashes) for more information.

## Switching from minimatch
### From minimatch

Use `mm.isMatch()` instead of `minimatch()`:
Use [mm.isMatch()](#ismatch) instead of `minimatch()`:

```js
mm.isMatch('foo', 'b*');
//=> false
```

Use `mm.match()` instead of `minimatch.match()`:
Use [mm.match()](#match) instead of `minimatch.match()`:

```js
mm.match(['foo', 'bar'], 'b*');
//=> 'bar'
```

## Switching from multimatch
### From multimatch

Same signature:

Expand All @@ -99,24 +82,24 @@ mm(['foo', 'bar', 'baz'], ['f*', '*z']);

## Options

- [basename](#options-basename)
- [bash](#options-bash)
- [cache](#options-cache)
- [dot](#options-dot)
- [failglob](#options-failglob)
- [ignore](#options-ignore)
- [matchBase](#options-matchBase)
- [nobrace](#options-nobrace)
- [nocase](#options-nocase)
- [nodupes](#options-nodupes)
- [noext](#options-noext)
- [noglobstar](#options-noglobstar)
- [nonull](#options-nonull)
- [nullglob](#options-nullglob)
- [snapdragon](#options-snapdragon)
- [sourcemap](#options-sourcemap)
- [unescape](#options-unescape)
- [unixify](#options-unixify)
- [basename](#optionsbasename)
- [bash](#optionsbash)
- [cache](#optionscache)
- [dot](#optionsdot)
- [failglob](#optionsfailglob)
- [ignore](#optionsignore)
- [matchBase](#optionsmatchBase)
- [nobrace](#optionsnobrace)
- [nocase](#optionsnocase)
- [nodupes](#optionsnodupes)
- [noext](#optionsnoext)
- [noglobstar](#optionsnoglobstar)
- [nonull](#optionsnonull)
- [nullglob](#optionsnullglob)
- [snapdragon](#optionssnapdragon)
- [sourcemap](#optionssourcemap)
- [unescape](#optionsunescape)
- [unixify](#optionsunixify)

### options.basename

Expand Down Expand Up @@ -389,30 +372,30 @@ Extended globbing, as described by the bash man page:

| **pattern** | **regex equivalent** | **description** |
| --- | --- | --- |
| `?(pattern-list)` | `(foo|bar)?` | Matches zero or one occurrence of the given patterns |
| `*(pattern-list)` | `(foo|bar)*` | Matches zero or more occurrences of the given patterns |
| `+(pattern-list)` | `(foo|bar)+` | Matches one or more occurrences of the given patterns |
| `@(pattern-list)` | `(foo|bar)` <sup>*</sup> | Matches one of the given patterns |
| `!(pattern-list)` | N/A (equivalent regex is much more complicated) | Matches anything except one of the given patterns |
| `?(pattern)` | `(pattern)?` | Matches zero or one occurrence of the given patterns |
| `*(pattern)` | `(pattern)*` | Matches zero or more occurrences of the given patterns |
| `+(pattern)` | `(pattern)+` | Matches one or more occurrences of the given patterns |
| `@(pattern)` | `(pattern)` <sup>*</sup> | Matches one of the given patterns |
| `!(pattern)` | N/A (equivalent regex is much more complicated) | Matches anything except one of the given patterns |

<sup><strong>*</strong></sup> Note that `@` isn't a RegEx character.

Powered by [extglob](https://github.com/jonschlinkert/extglob). Visit that library for the full range of options or to report extglob related issues.
Powered by [extglob][]. Visit that library for the full range of options or to report extglob related issues.

### braces

**Expanded braces**

Braces are expanded when ``

* range expansion: `a{1..3}b/*.js` expands to: `['a1b/*.js', 'a2b/*.js', 'a3b/*.js']`
* nesting: `a{c,{d,e}}b/*.js` expands to: `['acb/*.js', 'adb/*.js', 'aeb/*.js']`

**Optimized braces (not expanded)**
Brace patterns can be used to match specific ranges or sets of characters. For example, the pattern `*/{1..3}/*` would match any of following strings:

By default, brace patterns work the same way regex logical `OR` operators. For example, `(a|b)` will achieve the same result as `{a,b}`.
```
foo/1/bar
foo/2/bar
foo/3/bar
baz/1/qux
baz/2/qux
baz/3/qux
```

Visit [braces](https://github.com/jonschlinkert/braces) to see the full range of features and options related to brace expansion, or to create brace matching or expansion related issues.
Visit [braces][] to see the full range of features and options related to brace expansion, or to create brace matching or expansion related issues.

### regex character classes

Expand All @@ -423,7 +406,7 @@ Given the list: `['a.js', 'b.js', 'c.js', 'd.js', 'E.js']`:
* `[b-d].js`: matches from `b` to `d`, returning `['b.js', 'c.js', 'd.js']`
* `a/[A-Z].js`: matches and uppercase letter, returning `['a/E.md']`

Learn about [regex character classes](http://www.regular-expressions.info/charclass.html).
Learn about [regex character classes][charclass].

### regex groups

Expand All @@ -449,7 +432,7 @@ mm.isMatch('a1', '[[:alpha:][:alpha:]]');
//=> false
```

See [expand-brackets](https://github.com/jonschlinkert/expand-brackets) for more information about bracket expressions.
See [expand-brackets][] for more information about bracket expressions.

***

Expand All @@ -472,7 +455,7 @@ There is an important, notable difference between minimatch and micromatch _in r
We made this decision for micromatch for a couple of reasons:

- consistency with bash conventions.
- glob patterns are not filepaths. They are a type of [regular language](https://en.wikipedia.org/wiki/Regular_language) that is converted to a JavaScript regular expression. Thus, when forward slashes are defined in a glob pattern, the resulting regular expression will match windows or POSIX path separators just fine.
- glob patterns are not filepaths. They are a type of [regular language][regular-language] that is converted to a JavaScript regular expression. Thus, when forward slashes are defined in a glob pattern, the resulting regular expression will match windows or POSIX path separators just fine.

**A note about joining paths to globs**

Expand All @@ -486,11 +469,16 @@ All contributions are welcome! Please read [the contributing guide](.github/cont

**Bug reports**

Please feel free to create an issue if you find something that you think isn't right. However, if you find a matching-related issue, please try do the following first:
Please create an issue if you encounter a bug or matching behavior that doesn't seem correct. If you find a matching-related issue, please:

- [research existing issues first](../../issues) (open and closed)
- visit the [GNU Bash documentation][bash] to see how Bash deals with the pattern
- visit the [minimatch][] documentation to cross-check expected behavior in node.js
- if all else fails, since there is no real specification for globs we will probably need to discuss expected behavior and decide how to resolve it. which means any detail you can provide to help with this discussion would be greatly appreciated.

- research existing issues first
- visit the [GNU Bash documentation](https://www.gnu.org/software/bash/manual/) to see how Bash deals with the pattern
- visit the [minimatch][] documentation to cross-check expected behavior
**Platform issues**

It's important to us that micromatch work consistently on all platforms. If you encounter any platform-specific matching or path related issues, please let us know (pull requests are also greatly appreciated).

## Benchmarks

Expand All @@ -499,7 +487,7 @@ Please feel free to create an issue if you find something that you think isn't r
Install dev dependencies:

```bash
npm i -d && npm benchmark
npm i -d && npm run benchmark
```

### Latest results
Expand All @@ -510,10 +498,9 @@ As of {%= date() %} (longer bars are better):
{%= bench() %}
```


[switch]: #switch-from-minimatch
[expand]: #expand
[character-classes]: http://www.regular-expressions.info/charclass.html
[regular-language]: https://en.wikipedia.org/wiki/Regular_language
[bash]: https://www.gnu.org/software/bash/manual/
[charclass]: http://www.regular-expressions.info/charclass.html
[extended]: http://mywiki.wooledge.org/BashGuide/Patterns#Extended_Globs
[brackets]: https://github.com/jonschlinkert/expand-brackets
[braces]: https://github.com/jonschlinkert/braces
[brackets]: https://github.com/micromatch/expand-brackets
[braces]: https://github.com/micromatch/braces

0 comments on commit 914059f

Please sign in to comment.