www.aleph1.co.uk Git - yaffs-website/blob - node_modules/globule/node_modules/minimatch/README.md

   1 # minimatch
   2
   3 A minimal matching utility.
   4
   5 [![Build Status](https://secure.travis-ci.org/isaacs/minimatch.png)](http://travis-ci.org/isaacs/minimatch)
   6
   7
   8 This is the matching library used internally by npm.
   9
  10 Eventually, it will replace the C binding in node-glob.
  11
  12 It works by converting glob expressions into JavaScript `RegExp`
  13 objects.
  14
  15 ## Usage
  16
  17 ```javascript
  18 var minimatch = require("minimatch")
  19
  20 minimatch("bar.foo", "*.foo") // true!
  21 minimatch("bar.foo", "*.bar") // false!
  22 minimatch("bar.foo", "*.+(bar|foo)", { debug: true }) // true, and noisy!
  23 ```
  24
  25 ## Features
  26
  27 Supports these glob features:
  28
  29 * Brace Expansion
  30 * Extended glob matching
  31 * "Globstar" `**` matching
  32
  33 See:
  34
  35 * `man sh`
  36 * `man bash`
  37 * `man 3 fnmatch`
  38 * `man 5 gitignore`
  39
  40 ## Minimatch Class
  41
  42 Create a minimatch object by instanting the `minimatch.Minimatch` class.
  43
  44 ```javascript
  45 var Minimatch = require("minimatch").Minimatch
  46 var 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
  85 All other methods are internal, and will be called as necessary.
  86
  87 ## Functions
  88
  89 The top-level exported function has a `cache` property, which is an LRU
  90 cache set to store 100 items.  So, calling these methods repeatedly
  91 with the same pattern and options will use the same Minimatch object,
  92 saving the cost of parsing it multiple times.
  93
  94 ### minimatch(path, pattern, options)
  95
  96 Main export.  Tests a path against the pattern using the options.
  97
  98 ```javascript
  99 var isJS = minimatch(file, "*.js", { matchBase: true })
 100 ```
 101
 102 ### minimatch.filter(pattern, options)
 103
 104 Returns a function that tests its
 105 supplied argument, suitable for use with `Array.filter`.  Example:
 106
 107 ```javascript
 108 var javascripts = fileList.filter(minimatch.filter("*.js", {matchBase: true}))
 109 ```
 110
 111 ### minimatch.match(list, pattern, options)
 112
 113 Match against the list of
 114 files, in the style of fnmatch or glob.  If nothing is matched, and
 115 options.nonull is set, then return a list containing the pattern itself.
 116
 117 ```javascript
 118 var javascripts = minimatch.match(fileList, "*.js", {matchBase: true}))
 119 ```
 120
 121 ### minimatch.makeRe(pattern, options)
 122
 123 Make a regular expression object from the pattern.
 124
 125 ## Options
 126
 127 All options are `false` by default.
 128
 129 ### debug
 130
 131 Dump a ton of stuff to stderr.
 132
 133 ### nobrace
 134
 135 Do not expand `{a,b}` and `{1..3}` brace sets.
 136
 137 ### noglobstar
 138
 139 Disable `**` matching against multiple folder names.
 140
 141 ### dot
 142
 143 Allow patterns to match filenames starting with a period, even if
 144 the pattern does not explicitly have a period in that spot.
 145
 146 Note that by default, `a/**/b` will **not** match `a/.d/b`, unless `dot`
 147 is set.
 148
 149 ### noext
 150
 151 Disable "extglob" style patterns like `+(a|b)`.
 152
 153 ### nocase
 154
 155 Perform a case-insensitive match.
 156
 157 ### nonull
 158
 159 When a match is not found by `minimatch.match`, return a list containing
 160 the pattern itself.  When set, an empty list is returned if there are
 161 no matches.
 162
 163 ### matchBase
 164
 165 If set, then patterns without slashes will be matched
 166 against 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
 171 Suppress the behavior of treating `#` at the start of a pattern as a
 172 comment.
 173
 174 ### nonegate
 175
 176 Suppress the behavior of treating a leading `!` character as negation.
 177
 178 ### flipNegate
 179
 180 Returns 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
 186 While strict compliance with the existing standards is a worthwhile
 187 goal, some discrepancies exist between minimatch and other
 188 implementations, and are intentional.
 189
 190 If the pattern starts with a `!` character, then it is negated.  Set the
 191 `nonegate` flag to suppress this behavior, and treat leading `!`
 192 characters normally.  This is perhaps relevant if you wish to start the
 193 pattern with a negative extglob pattern like `!(a|B)`.  Multiple `!`
 194 characters at the start of a pattern will negate the pattern multiple
 195 times.
 196
 197 If a pattern starts with `#`, then it is treated as a comment, and
 198 will not match anything.  Use `\#` to match a literal `#` at the
 199 start of a line, or set the `nocomment` flag to suppress this behavior.
 200
 201 The double-star character `**` is supported by default, unless the
 202 `noglobstar` flag is set.  This is supported in the manner of bsdglob
 203 and bash 4.1, where `**` only has special significance if it is the only
 204 thing in a path part.  That is, `a/**/b` will match `a/x/y/b`, but
 205 `a/**b` will not.
 206
 207 If an escaped pattern has no matches, and the `nonull` flag is set,
 208 then minimatch.match returns the pattern as-provided, rather than
 209 interpreting 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
 212 that it does not resolve escaped pattern characters.
 213
 214 If brace expansion is not disabled, then it is performed before any
 215 other 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
 218 checked for validity.  Since those two are valid, matching proceeds.