PageRenderTime 44ms CodeModel.GetById 19ms app.highlight 20ms RepoModel.GetById 1ms app.codeStats 1ms

/node_modules/minimatch/README.md

https://bitbucket.org/coleman333/smartsite
Markdown | 218 lines | 147 code | 71 blank | 0 comment | 0 complexity | 4a533f04622a9f84dc0a9782f3b8e2b4 MD5 | raw file
  1# minimatch
  2
  3A minimal matching utility.
  4
  5[![Build Status](https://secure.travis-ci.org/isaacs/minimatch.png)](http://travis-ci.org/isaacs/minimatch)
  6
  7
  8This is the matching library used internally by npm.
  9
 10Eventually, it will replace the C binding in node-glob.
 11
 12It works by converting glob expressions into JavaScript `RegExp`
 13objects.
 14
 15## Usage
 16
 17```javascript
 18var minimatch = require("minimatch")
 19
 20minimatch("bar.foo", "*.foo") // true!
 21minimatch("bar.foo", "*.bar") // false!
 22minimatch("bar.foo", "*.+(bar|foo)", { debug: true }) // true, and noisy!
 23```
 24
 25## Features
 26
 27Supports these glob features:
 28
 29* Brace Expansion
 30* Extended glob matching
 31* "Globstar" `**` matching
 32
 33See:
 34
 35* `man sh`
 36* `man bash`
 37* `man 3 fnmatch`
 38* `man 5 gitignore`
 39
 40## Minimatch Class
 41
 42Create a minimatch object by instanting the `minimatch.Minimatch` class.
 43
 44```javascript
 45var Minimatch = require("minimatch").Minimatch
 46var mm = new Minimatch(pattern, options)
 47```
 48
 49### Properties
 50
 51* `pattern` The original pattern the minimatch object represents.
 52* `options` The options supplied to the constructor.
 53* `set` A 2-dimensional array of regexp or string expressions.
 54  Each row in the
 55  array corresponds to a brace-expanded pattern.  Each item in the row
 56  corresponds to a single path-part.  For example, the pattern
 57  `{a,b/c}/d` would expand to a set of patterns like:
 58
 59        [ [ a, d ]
 60        , [ b, c, d ] ]
 61
 62    If a portion of the pattern doesn't have any "magic" in it
 63    (that is, it's something like `"foo"` rather than `fo*o?`), then it
 64    will be left as a string rather than converted to a regular
 65    expression.
 66
 67* `regexp` Created by the `makeRe` method.  A single regular expression
 68  expressing the entire pattern.  This is useful in cases where you wish
 69  to use the pattern somewhat like `fnmatch(3)` with `FNM_PATH` enabled.
 70* `negate` True if the pattern is negated.
 71* `comment` True if the pattern is a comment.
 72* `empty` True if the pattern is `""`.
 73
 74### Methods
 75
 76* `makeRe` Generate the `regexp` member if necessary, and return it.
 77  Will return `false` if the pattern is invalid.
 78* `match(fname)` Return true if the filename matches the pattern, or
 79  false otherwise.
 80* `matchOne(fileArray, patternArray, partial)` Take a `/`-split
 81  filename, and match it against a single row in the `regExpSet`.  This
 82  method is mainly for internal use, but is exposed so that it can be
 83  used by a glob-walker that needs to avoid excessive filesystem calls.
 84
 85All other methods are internal, and will be called as necessary.
 86
 87## Functions
 88
 89The top-level exported function has a `cache` property, which is an LRU
 90cache set to store 100 items.  So, calling these methods repeatedly
 91with the same pattern and options will use the same Minimatch object,
 92saving the cost of parsing it multiple times.
 93
 94### minimatch(path, pattern, options)
 95
 96Main export.  Tests a path against the pattern using the options.
 97
 98```javascript
 99var isJS = minimatch(file, "*.js", { matchBase: true })
100```
101
102### minimatch.filter(pattern, options)
103
104Returns a function that tests its
105supplied argument, suitable for use with `Array.filter`.  Example:
106
107```javascript
108var javascripts = fileList.filter(minimatch.filter("*.js", {matchBase: true}))
109```
110
111### minimatch.match(list, pattern, options)
112
113Match against the list of
114files, in the style of fnmatch or glob.  If nothing is matched, and
115options.nonull is set, then return a list containing the pattern itself.
116
117```javascript
118var javascripts = minimatch.match(fileList, "*.js", {matchBase: true}))
119```
120
121### minimatch.makeRe(pattern, options)
122
123Make a regular expression object from the pattern.
124
125## Options
126
127All options are `false` by default.
128
129### debug
130
131Dump a ton of stuff to stderr.
132
133### nobrace
134
135Do not expand `{a,b}` and `{1..3}` brace sets.
136
137### noglobstar
138
139Disable `**` matching against multiple folder names.
140
141### dot
142
143Allow patterns to match filenames starting with a period, even if
144the pattern does not explicitly have a period in that spot.
145
146Note that by default, `a/**/b` will **not** match `a/.d/b`, unless `dot`
147is set.
148
149### noext
150
151Disable "extglob" style patterns like `+(a|b)`.
152
153### nocase
154
155Perform a case-insensitive match.
156
157### nonull
158
159When a match is not found by `minimatch.match`, return a list containing
160the pattern itself if this option is set.  When not set, an empty list
161is returned if there are no matches.
162
163### matchBase
164
165If set, then patterns without slashes will be matched
166against the basename of the path if it contains slashes.  For example,
167`a?b` would match the path `/xyz/123/acb`, but not `/xyz/acb/123`.
168
169### nocomment
170
171Suppress the behavior of treating `#` at the start of a pattern as a
172comment.
173
174### nonegate
175
176Suppress the behavior of treating a leading `!` character as negation.
177
178### flipNegate
179
180Returns from negate expressions the same as if they were not negated.
181(Ie, true on a hit, false on a miss.)
182
183
184## Comparisons to other fnmatch/glob implementations
185
186While strict compliance with the existing standards is a worthwhile
187goal, some discrepancies exist between minimatch and other
188implementations, and are intentional.
189
190If the pattern starts with a `!` character, then it is negated.  Set the
191`nonegate` flag to suppress this behavior, and treat leading `!`
192characters normally.  This is perhaps relevant if you wish to start the
193pattern with a negative extglob pattern like `!(a|B)`.  Multiple `!`
194characters at the start of a pattern will negate the pattern multiple
195times.
196
197If a pattern starts with `#`, then it is treated as a comment, and
198will not match anything.  Use `\#` to match a literal `#` at the
199start of a line, or set the `nocomment` flag to suppress this behavior.
200
201The double-star character `**` is supported by default, unless the
202`noglobstar` flag is set.  This is supported in the manner of bsdglob
203and bash 4.1, where `**` only has special significance if it is the only
204thing in a path part.  That is, `a/**/b` will match `a/x/y/b`, but
205`a/**b` will not.
206
207If an escaped pattern has no matches, and the `nonull` flag is set,
208then minimatch.match returns the pattern as-provided, rather than
209interpreting the character escapes.  For example,
210`minimatch.match([], "\\*a\\?")` will return `"\\*a\\?"` rather than
211`"*a?"`.  This is akin to setting the `nullglob` option in bash, except
212that it does not resolve escaped pattern characters.
213
214If brace expansion is not disabled, then it is performed before any
215other interpretation of the glob pattern.  Thus, a pattern like
216`+(a|{b),c)}`, which would not be valid in bash or zsh, is expanded
217**first** into the set of `+(a|b)` and `+(a|c)`, and those patterns are
218checked for validity.  Since those two are valid, matching proceeds.