vnfmarket/src/main/webapp/vnfmarket/node_modules/fileset/node_modules/glob/README.md

   1 # Glob
   2
   3 Match files using the patterns the shell uses, like stars and stuff.
   4
   5 This is a glob implementation in JavaScript.  It uses the `minimatch`
   6 library to do its matching.
   7
   8 ## Attention: node-glob users!
   9
  10 The API has changed dramatically between 2.x and 3.x. This library is
  11 now 100% JavaScript, and the integer flags have been replaced with an
  12 options object.
  13
  14 Also, there's an event emitter class, proper tests, and all the other
  15 things you've come to expect from node modules.
  16
  17 And best of all, no compilation!
  18
  19 ## Usage
  20
  21 ```javascript
  22 var glob = require("glob")
  23
  24 // options is optional
  25 glob("**/*.js", options, function (er, files) {
  26   // files is an array of filenames.
  27   // If the `nonull` option is set, and nothing
  28   // was found, then files is ["**/*.js"]
  29   // er is an error object or null.
  30 })
  31 ```
  32
  33 ## Features
  34
  35 Please see the [minimatch
  36 documentation](https://github.com/isaacs/minimatch) for more details.
  37
  38 Supports these glob features:
  39
  40 * Brace Expansion
  41 * Extended glob matching
  42 * "Globstar" `**` matching
  43
  44 See:
  45
  46 * `man sh`
  47 * `man bash`
  48 * `man 3 fnmatch`
  49 * `man 5 gitignore`
  50 * [minimatch documentation](https://github.com/isaacs/minimatch)
  51
  52 ## glob(pattern, [options], cb)
  53
  54 * `pattern` {String} Pattern to be matched
  55 * `options` {Object}
  56 * `cb` {Function}
  57   * `err` {Error | null}
  58   * `matches` {Array<String>} filenames found matching the pattern
  59
  60 Perform an asynchronous glob search.
  61
  62 ## glob.sync(pattern, [options])
  63
  64 * `pattern` {String} Pattern to be matched
  65 * `options` {Object}
  66 * return: {Array<String>} filenames found matching the pattern
  67
  68 Perform a synchronous glob search.
  69
  70 ## Class: glob.Glob
  71
  72 Create a Glob object by instanting the `glob.Glob` class.
  73
  74 ```javascript
  75 var Glob = require("glob").Glob
  76 var mg = new Glob(pattern, options, cb)
  77 ```
  78
  79 It's an EventEmitter, and starts walking the filesystem to find matches
  80 immediately.
  81
  82 ### new glob.Glob(pattern, [options], [cb])
  83
  84 * `pattern` {String} pattern to search for
  85 * `options` {Object}
  86 * `cb` {Function} Called when an error occurs, or matches are found
  87   * `err` {Error | null}
  88   * `matches` {Array<String>} filenames found matching the pattern
  89
  90 Note that if the `sync` flag is set in the options, then matches will
  91 be immediately available on the `g.found` member.
  92
  93 ### Properties
  94
  95 * `minimatch` The minimatch object that the glob uses.
  96 * `options` The options object passed in.
  97 * `error` The error encountered.  When an error is encountered, the
  98   glob object is in an undefined state, and should be discarded.
  99 * `aborted` Boolean which is set to true when calling `abort()`.  There
 100   is no way at this time to continue a glob search after aborting, but
 101   you can re-use the statCache to avoid having to duplicate syscalls.
 102 * `statCache` Collection of all the stat results the glob search
 103   performed.
 104 * `cache` Convenience object.  Each field has the following possible
 105   values:
 106   * `false` - Path does not exist
 107   * `true` - Path exists
 108   * `1` - Path exists, and is not a directory
 109   * `2` - Path exists, and is a directory
 110   * `[file, entries, ...]` - Path exists, is a directory, and the
 111     array value is the results of `fs.readdir`
 112
 113 ### Events
 114
 115 * `end` When the matching is finished, this is emitted with all the
 116   matches found.  If the `nonull` option is set, and no match was found,
 117   then the `matches` list contains the original pattern.  The matches
 118   are sorted, unless the `nosort` flag is set.
 119 * `match` Every time a match is found, this is emitted with the matched.
 120 * `error` Emitted when an unexpected error is encountered, or whenever
 121   any fs error occurs if `options.strict` is set.
 122 * `abort` When `abort()` is called, this event is raised.
 123
 124 ### Methods
 125
 126 * `abort` Stop the search.
 127
 128 ### Options
 129
 130 All the options that can be passed to Minimatch can also be passed to
 131 Glob to change pattern matching behavior.  Also, some have been added,
 132 or have glob-specific ramifications.
 133
 134 All options are false by default, unless otherwise noted.
 135
 136 All options are added to the glob object, as well.
 137
 138 * `cwd` The current working directory in which to search.  Defaults
 139   to `process.cwd()`.
 140 * `root` The place where patterns starting with `/` will be mounted
 141   onto.  Defaults to `path.resolve(options.cwd, "/")` (`/` on Unix
 142   systems, and `C:\` or some such on Windows.)
 143 * `dot` Include `.dot` files in normal matches and `globstar` matches.
 144   Note that an explicit dot in a portion of the pattern will always
 145   match dot files.
 146 * `nomount` By default, a pattern starting with a forward-slash will be
 147   "mounted" onto the root setting, so that a valid filesystem path is
 148   returned.  Set this flag to disable that behavior.
 149 * `mark` Add a `/` character to directory matches.  Note that this
 150   requires additional stat calls.
 151 * `nosort` Don't sort the results.
 152 * `stat` Set to true to stat *all* results.  This reduces performance
 153   somewhat, and is completely unnecessary, unless `readdir` is presumed
 154   to be an untrustworthy indicator of file existence.  It will cause
 155   ELOOP to be triggered one level sooner in the case of cyclical
 156   symbolic links.
 157 * `silent` When an unusual error is encountered
 158   when attempting to read a directory, a warning will be printed to
 159   stderr.  Set the `silent` option to true to suppress these warnings.
 160 * `strict` When an unusual error is encountered
 161   when attempting to read a directory, the process will just continue on
 162   in search of other matches.  Set the `strict` option to raise an error
 163   in these cases.
 164 * `cache` See `cache` property above.  Pass in a previously generated
 165   cache object to save some fs calls.
 166 * `statCache` A cache of results of filesystem information, to prevent
 167   unnecessary stat calls.  While it should not normally be necessary to
 168   set this, you may pass the statCache from one glob() call to the
 169   options object of another, if you know that the filesystem will not
 170   change between calls.  (See "Race Conditions" below.)
 171 * `sync` Perform a synchronous glob search.
 172 * `nounique` In some cases, brace-expanded patterns can result in the
 173   same file showing up multiple times in the result set.  By default,
 174   this implementation prevents duplicates in the result set.
 175   Set this flag to disable that behavior.
 176 * `nonull` Set to never return an empty set, instead returning a set
 177   containing the pattern itself.  This is the default in glob(3).
 178 * `nocase` Perform a case-insensitive match.  Note that case-insensitive
 179   filesystems will sometimes result in glob returning results that are
 180   case-insensitively matched anyway, since readdir and stat will not
 181   raise an error.
 182 * `debug` Set to enable debug logging in minimatch and glob.
 183 * `globDebug` Set to enable debug logging in glob, but not minimatch.
 184
 185 ## Comparisons to other fnmatch/glob implementations
 186
 187 While strict compliance with the existing standards is a worthwhile
 188 goal, some discrepancies exist between node-glob and other
 189 implementations, and are intentional.
 190
 191 If the pattern starts with a `!` character, then it is negated.  Set the
 192 `nonegate` flag to suppress this behavior, and treat leading `!`
 193 characters normally.  This is perhaps relevant if you wish to start the
 194 pattern with a negative extglob pattern like `!(a|B)`.  Multiple `!`
 195 characters at the start of a pattern will negate the pattern multiple
 196 times.
 197
 198 If a pattern starts with `#`, then it is treated as a comment, and
 199 will not match anything.  Use `\#` to match a literal `#` at the
 200 start of a line, or set the `nocomment` flag to suppress this behavior.
 201
 202 The double-star character `**` is supported by default, unless the
 203 `noglobstar` flag is set.  This is supported in the manner of bsdglob
 204 and bash 4.1, where `**` only has special significance if it is the only
 205 thing in a path part.  That is, `a/**/b` will match `a/x/y/b`, but
 206 `a/**b` will not.
 207
 208 If an escaped pattern has no matches, and the `nonull` flag is set,
 209 then glob returns the pattern as-provided, rather than
 210 interpreting the character escapes.  For example,
 211 `glob.match([], "\\*a\\?")` will return `"\\*a\\?"` rather than
 212 `"*a?"`.  This is akin to setting the `nullglob` option in bash, except
 213 that it does not resolve escaped pattern characters.
 214
 215 If brace expansion is not disabled, then it is performed before any
 216 other interpretation of the glob pattern.  Thus, a pattern like
 217 `+(a|{b),c)}`, which would not be valid in bash or zsh, is expanded
 218 **first** into the set of `+(a|b)` and `+(a|c)`, and those patterns are
 219 checked for validity.  Since those two are valid, matching proceeds.
 220
 221 ## Windows
 222
 223 **Please only use forward-slashes in glob expressions.**
 224
 225 Though windows uses either `/` or `\` as its path separator, only `/`
 226 characters are used by this glob implementation.  You must use
 227 forward-slashes **only** in glob expressions.  Back-slashes will always
 228 be interpreted as escape characters, not path separators.
 229
 230 Results from absolute patterns such as `/foo/*` are mounted onto the
 231 root setting using `path.join`.  On windows, this will by default result
 232 in `/foo/*` matching `C:\foo\bar.txt`.
 233
 234 ## Race Conditions
 235
 236 Glob searching, by its very nature, is susceptible to race conditions,
 237 since it relies on directory walking and such.
 238
 239 As a result, it is possible that a file that exists when glob looks for
 240 it may have been deleted or modified by the time it returns the result.
 241
 242 As part of its internal implementation, this program caches all stat
 243 and readdir calls that it makes, in order to cut down on system
 244 overhead.  However, this also makes it even more susceptible to races,
 245 especially if the cache or statCache objects are reused between glob
 246 calls.
 247
 248 Users are thus advised not to use a glob result as a guarantee of
 249 filesystem state in the face of rapid changes.  For the vast majority
 250 of operations, this is never a problem.