Name: js-handler/node_modules/nodeunit/node_modules/tap/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.