diff options
Diffstat (limited to 'deps/node/deps/npm/node_modules/glob/README.md')
| -rw-r--r-- | deps/node/deps/npm/node_modules/glob/README.md | 368 |
1 files changed, 0 insertions, 368 deletions
diff --git a/deps/node/deps/npm/node_modules/glob/README.md b/deps/node/deps/npm/node_modules/glob/README.md deleted file mode 100644 index baa1d1ba..00000000 --- a/deps/node/deps/npm/node_modules/glob/README.md +++ /dev/null @@ -1,368 +0,0 @@ -# Glob - -Match files using the patterns the shell uses, like stars and stuff. - -[](https://travis-ci.org/isaacs/node-glob/) [](https://ci.appveyor.com/project/isaacs/node-glob) [](https://coveralls.io/github/isaacs/node-glob?branch=master) - -This is a glob implementation in JavaScript. It uses the `minimatch` -library to do its matching. - - - -## Usage - -Install with npm - -``` -npm i glob -``` - -```javascript -var glob = require("glob") - -// options is optional -glob("**/*.js", options, function (er, files) { - // files is an array of filenames. - // If the `nonull` option is set, and nothing - // was found, then files is ["**/*.js"] - // er is an error object or null. -}) -``` - -## Glob Primer - -"Globs" are the patterns you type when you do stuff like `ls *.js` on -the command line, or put `build/*` in a `.gitignore` file. - -Before parsing the path part patterns, braced sections are expanded -into a set. Braced sections start with `{` and end with `}`, with any -number of comma-delimited sections within. Braced sections may contain -slash characters, so `a{/b/c,bcd}` would expand into `a/b/c` and `abcd`. - -The following characters have special magic meaning when used in a -path portion: - -* `*` Matches 0 or more characters in a single path portion -* `?` Matches 1 character -* `[...]` Matches a range of characters, similar to a RegExp range. - If the first character of the range is `!` or `^` then it matches - any character not in the range. -* `!(pattern|pattern|pattern)` Matches anything that does not match - any of the patterns provided. -* `?(pattern|pattern|pattern)` Matches zero or one occurrence of the - patterns provided. -* `+(pattern|pattern|pattern)` Matches one or more occurrences of the - patterns provided. -* `*(a|b|c)` Matches zero or more occurrences of the patterns provided -* `@(pattern|pat*|pat?erN)` Matches exactly one of the patterns - provided -* `**` If a "globstar" is alone in a path portion, then it matches - zero or more directories and subdirectories searching for matches. - It does not crawl symlinked directories. - -### Dots - -If a file or directory path portion has a `.` as the first character, -then it will not match any glob pattern unless that pattern's -corresponding path part also has a `.` as its first character. - -For example, the pattern `a/.*/c` would match the file at `a/.b/c`. -However the pattern `a/*/c` would not, because `*` does not start with -a dot character. - -You can make glob treat dots as normal characters by setting -`dot:true` in the options. - -### Basename Matching - -If you set `matchBase:true` in the options, and the pattern has no -slashes in it, then it will seek for any file anywhere in the tree -with a matching basename. For example, `*.js` would match -`test/simple/basic.js`. - -### Empty Sets - -If no matching files are found, then an empty array is returned. This -differs from the shell, where the pattern itself is returned. For -example: - - $ echo a*s*d*f - a*s*d*f - -To get the bash-style behavior, set the `nonull:true` in the options. - -### See Also: - -* `man sh` -* `man bash` (Search for "Pattern Matching") -* `man 3 fnmatch` -* `man 5 gitignore` -* [minimatch documentation](https://github.com/isaacs/minimatch) - -## glob.hasMagic(pattern, [options]) - -Returns `true` if there are any special characters in the pattern, and -`false` otherwise. - -Note that the options affect the results. If `noext:true` is set in -the options object, then `+(a|b)` will not be considered a magic -pattern. If the pattern has a brace expansion, like `a/{b/c,x/y}` -then that is considered magical, unless `nobrace:true` is set in the -options. - -## glob(pattern, [options], cb) - -* `pattern` `{String}` Pattern to be matched -* `options` `{Object}` -* `cb` `{Function}` - * `err` `{Error | null}` - * `matches` `{Array<String>}` filenames found matching the pattern - -Perform an asynchronous glob search. - -## glob.sync(pattern, [options]) - -* `pattern` `{String}` Pattern to be matched -* `options` `{Object}` -* return: `{Array<String>}` filenames found matching the pattern - -Perform a synchronous glob search. - -## Class: glob.Glob - -Create a Glob object by instantiating the `glob.Glob` class. - -```javascript -var Glob = require("glob").Glob -var mg = new Glob(pattern, options, cb) -``` - -It's an EventEmitter, and starts walking the filesystem to find matches -immediately. - -### new glob.Glob(pattern, [options], [cb]) - -* `pattern` `{String}` pattern to search for -* `options` `{Object}` -* `cb` `{Function}` Called when an error occurs, or matches are found - * `err` `{Error | null}` - * `matches` `{Array<String>}` filenames found matching the pattern - -Note that if the `sync` flag is set in the options, then matches will -be immediately available on the `g.found` member. - -### Properties - -* `minimatch` The minimatch object that the glob uses. -* `options` The options object passed in. -* `aborted` Boolean which is set to true when calling `abort()`. There - is no way at this time to continue a glob search after aborting, but - you can re-use the statCache to avoid having to duplicate syscalls. -* `cache` Convenience object. Each field has the following possible - values: - * `false` - Path does not exist - * `true` - Path exists - * `'FILE'` - Path exists, and is not a directory - * `'DIR'` - Path exists, and is a directory - * `[file, entries, ...]` - Path exists, is a directory, and the - array value is the results of `fs.readdir` -* `statCache` Cache of `fs.stat` results, to prevent statting the same - path multiple times. -* `symlinks` A record of which paths are symbolic links, which is - relevant in resolving `**` patterns. -* `realpathCache` An optional object which is passed to `fs.realpath` - to minimize unnecessary syscalls. It is stored on the instantiated - Glob object, and may be re-used. - -### Events - -* `end` When the matching is finished, this is emitted with all the - matches found. If the `nonull` option is set, and no match was found, - then the `matches` list contains the original pattern. The matches - are sorted, unless the `nosort` flag is set. -* `match` Every time a match is found, this is emitted with the specific - thing that matched. It is not deduplicated or resolved to a realpath. -* `error` Emitted when an unexpected error is encountered, or whenever - any fs error occurs if `options.strict` is set. -* `abort` When `abort()` is called, this event is raised. - -### Methods - -* `pause` Temporarily stop the search -* `resume` Resume the search -* `abort` Stop the search forever - -### Options - -All the options that can be passed to Minimatch can also be passed to -Glob to change pattern matching behavior. Also, some have been added, -or have glob-specific ramifications. - -All options are false by default, unless otherwise noted. - -All options are added to the Glob object, as well. - -If you are running many `glob` operations, you can pass a Glob object -as the `options` argument to a subsequent operation to shortcut some -`stat` and `readdir` calls. At the very least, you may pass in shared -`symlinks`, `statCache`, `realpathCache`, and `cache` options, so that -parallel glob operations will be sped up by sharing information about -the filesystem. - -* `cwd` The current working directory in which to search. Defaults - to `process.cwd()`. -* `root` The place where patterns starting with `/` will be mounted - onto. Defaults to `path.resolve(options.cwd, "/")` (`/` on Unix - systems, and `C:\` or some such on Windows.) -* `dot` Include `.dot` files in normal matches and `globstar` matches. - Note that an explicit dot in a portion of the pattern will always - match dot files. -* `nomount` By default, a pattern starting with a forward-slash will be - "mounted" onto the root setting, so that a valid filesystem path is - returned. Set this flag to disable that behavior. -* `mark` Add a `/` character to directory matches. Note that this - requires additional stat calls. -* `nosort` Don't sort the results. -* `stat` Set to true to stat *all* results. This reduces performance - somewhat, and is completely unnecessary, unless `readdir` is presumed - to be an untrustworthy indicator of file existence. -* `silent` When an unusual error is encountered when attempting to - read a directory, a warning will be printed to stderr. Set the - `silent` option to true to suppress these warnings. -* `strict` When an unusual error is encountered when attempting to - read a directory, the process will just continue on in search of - other matches. Set the `strict` option to raise an error in these - cases. -* `cache` See `cache` property above. Pass in a previously generated - cache object to save some fs calls. -* `statCache` A cache of results of filesystem information, to prevent - unnecessary stat calls. While it should not normally be necessary - to set this, you may pass the statCache from one glob() call to the - options object of another, if you know that the filesystem will not - change between calls. (See "Race Conditions" below.) -* `symlinks` A cache of known symbolic links. You may pass in a - previously generated `symlinks` object to save `lstat` calls when - resolving `**` matches. -* `sync` DEPRECATED: use `glob.sync(pattern, opts)` instead. -* `nounique` In some cases, brace-expanded patterns can result in the - same file showing up multiple times in the result set. By default, - this implementation prevents duplicates in the result set. Set this - flag to disable that behavior. -* `nonull` Set to never return an empty set, instead returning a set - containing the pattern itself. This is the default in glob(3). -* `debug` Set to enable debug logging in minimatch and glob. -* `nobrace` Do not expand `{a,b}` and `{1..3}` brace sets. -* `noglobstar` Do not match `**` against multiple filenames. (Ie, - treat it as a normal `*` instead.) -* `noext` Do not match `+(a|b)` "extglob" patterns. -* `nocase` Perform a case-insensitive match. Note: on - case-insensitive filesystems, non-magic patterns will match by - default, since `stat` and `readdir` will not raise errors. -* `matchBase` Perform a basename-only match if the pattern does not - contain any slash characters. That is, `*.js` would be treated as - equivalent to `**/*.js`, matching all js files in all directories. -* `nodir` Do not match directories, only files. (Note: to match - *only* directories, simply put a `/` at the end of the pattern.) -* `ignore` Add a pattern or an array of glob patterns to exclude matches. - Note: `ignore` patterns are *always* in `dot:true` mode, regardless - of any other settings. -* `follow` Follow symlinked directories when expanding `**` patterns. - Note that this can result in a lot of duplicate references in the - presence of cyclic links. -* `realpath` Set to true to call `fs.realpath` on all of the results. - In the case of a symlink that cannot be resolved, the full absolute - path to the matched entry is returned (though it will usually be a - broken symlink) -* `absolute` Set to true to always receive absolute paths for matched - files. Unlike `realpath`, this also affects the values returned in - the `match` event. - -## Comparisons to other fnmatch/glob implementations - -While strict compliance with the existing standards is a worthwhile -goal, some discrepancies exist between node-glob and other -implementations, and are intentional. - -The double-star character `**` is supported by default, unless the -`noglobstar` flag is set. This is supported in the manner of bsdglob -and bash 4.3, where `**` only has special significance if it is the only -thing in a path part. That is, `a/**/b` will match `a/x/y/b`, but -`a/**b` will not. - -Note that symlinked directories are not crawled as part of a `**`, -though their contents may match against subsequent portions of the -pattern. This prevents infinite loops and duplicates and the like. - -If an escaped pattern has no matches, and the `nonull` flag is set, -then glob returns the pattern as-provided, rather than -interpreting the character escapes. For example, -`glob.match([], "\\*a\\?")` will return `"\\*a\\?"` rather than -`"*a?"`. This is akin to setting the `nullglob` option in bash, except -that it does not resolve escaped pattern characters. - -If brace expansion is not disabled, then it is performed before any -other interpretation of the glob pattern. Thus, a pattern like -`+(a|{b),c)}`, which would not be valid in bash or zsh, is expanded -**first** into the set of `+(a|b)` and `+(a|c)`, and those patterns are -checked for validity. Since those two are valid, matching proceeds. - -### Comments and Negation - -Previously, this module let you mark a pattern as a "comment" if it -started with a `#` character, or a "negated" pattern if it started -with a `!` character. - -These options were deprecated in version 5, and removed in version 6. - -To specify things that should not match, use the `ignore` option. - -## Windows - -**Please only use forward-slashes in glob expressions.** - -Though windows uses either `/` or `\` as its path separator, only `/` -characters are used by this glob implementation. You must use -forward-slashes **only** in glob expressions. Back-slashes will always -be interpreted as escape characters, not path separators. - -Results from absolute patterns such as `/foo/*` are mounted onto the -root setting using `path.join`. On windows, this will by default result -in `/foo/*` matching `C:\foo\bar.txt`. - -## Race Conditions - -Glob searching, by its very nature, is susceptible to race conditions, -since it relies on directory walking and such. - -As a result, it is possible that a file that exists when glob looks for -it may have been deleted or modified by the time it returns the result. - -As part of its internal implementation, this program caches all stat -and readdir calls that it makes, in order to cut down on system -overhead. However, this also makes it even more susceptible to races, -especially if the cache or statCache objects are reused between glob -calls. - -Users are thus advised not to use a glob result as a guarantee of -filesystem state in the face of rapid changes. For the vast majority -of operations, this is never a problem. - -## Contributing - -Any change to behavior (including bugfixes) must come with a test. - -Patches that fail tests or reduce performance will be rejected. - -``` -# to run tests -npm test - -# to re-generate test fixtures -npm run test-regen - -# to benchmark against bash/zsh -npm run bench - -# to profile javascript -npm run prof -``` |