Node Glob

根据自己的理解翻译了这篇Node Glob部分内容。第一次翻译E文，不到之处各位客官轻拍，定改之。

原文全文 —— 《Glob》

 

 

Usage

var glob = require(‘glob’);

// options is optional

glob(‘**/*.js’, options, function(er, files) {

// files 为所有匹配到的文件名数组

// 如果设置了·nonull: true·，并且没有匹配到任何文件，那么files是[‘**/*.js']

// er 为一个error对象或null

 });

 

 

Glob Primer

“Globs”是一种类似命令行命令 ls *.js这样的玩意儿，亦或是像.gitignore文件里的build/*。

在解析路径pattern时，其中花括号为扩展设置，以“{”开始，“}”结束，如果花括号里设置多个匹配项，需要用“,”作为分割符，可以包含“/”作为路径。

e.g :

a{/b/c,bcd} -> 将匹配a/b/c、abcd

 

下面的字符用在路径部分会有特殊魔法效应：

• * -> 匹配一个路径中的0或多个字符。
• ? -> 匹配1个字符。
• […] -> 匹配一个字符范围区间，类似RegExp range。如果以“ ! ”或“ ^ ”开头，将匹配除此range之外的字符。
• !(pattern|pattern|pattern) -> 匹配任何除“()”里匹配到的之外玩意儿，有点绕舌，简单点说就是只要不是“()”里pattern匹配的都符合匹配条件
• ?(pattern|pattern|pattern) -> 匹配0或1个符合pattern匹配条件的字符（少于1个）
• +(pattern|pattern|pattern) -> 匹配1个或以上的符合pattern匹配条件的字符（至少1个）
• *(pattern|pattern|pattern) -> 匹配0或多个符合pattern匹配条件的字符（任意个）
• @(pattern|pat*|pat?erN) -> 精确匹配其中一个pattern
• ** 如果（globstar）仅仅是路径的一部分，那么它将匹配任意目录，以及任意层级的子目录，但是对符号链接的目录不感兴趣（不匹配符号链接目录）

 

 

Dots - “ . ”

如果文件或目录路径的一部分含有“ . ”，并且是第一个字符，那么不匹配任何blob pattern，只匹配原字符“ . ”。

 e.g： 

pattern: .*  -> 将匹配 .filename.ext、.gitignore  etc

pattern: a/.*/c  -> 将匹配 a/.anyDirectory/c

 

可以通过options设置项“ {dot: true} ”将“ . ”设置成可通过patterns匹配的普通的

 字符。

 

Basename Matching

如果在options里设置了“ {matchBase: true} ”，并且pattern字串里不包含“ / ”，那么将会匹配目录树下任何目录里的相匹配文件。

e.g :

pattern: *.js  -> 将匹配 any/directory/path/filename.js

 

Empty Sets

如果pattern没有匹配到文件，那么将返回一个空数组。和shell有所不同，shell返回pattern本身字符串，

e.g :

$ echo a*s*d*f

a*s*d*f

如果你习惯bash风格的行为模式，设置options -> {nonull: true}

 

 

glob.hasMagic(pattern, [options])

如果pattern里含有特殊字符返回 true ，反之返回 false。

注意：options会影响结果。如果设定options -> {noext:true}，那么 +(a|b) 将不考虑magic pattern。如果pattern含有花括号，类似 a/{b/c,x/y}这样的会被考虑magical，除非设定options -> {no brace: true}。

 

 

glob(pattern,[options],cb)

• pattern {String}匹配模式
• options {Object}
• cb {Function}
• ◦ err {Error | null}
• ◦ matches {Array} 根据pattern匹配到的文件名数组 

做异步glob查寻。

 

 

glob.sync(pattern,[options])

• pattern {String}匹配模式
• options {Object}
• return:{Array} 根据pattern匹配到的文件名数组

做同步glob查寻

 

 

Class: glob.Glob

通过 glob.Glob 类，创建一个glob对象示例

var Glob = require(‘glob’).Glob;

var mg = new Glob(pattern, options, cb);

这是一个事件发射器（EventEmitter），并且会开始从文件系统立即找到匹配。

 

 

new glob.Glob(pattern,[options],[cb])

• pattern {String}搜索模式
• options {Object}
• cb {Function}每当发生错误时被调用，又或者是有被匹配到项也会被调用
• ◦ err {Error | null}
• ◦ matches {Array} 被匹配到的文件名数组

注意：如果在options 设置 sync 标记，那么匹配项将立即被 g.found一员获得。

 

 

Properties

• minimatch glob通配符使用的是minimatch对象
• options 通过options对象设置影响其结果
• aborted 设置为true 调用abort()。在呼出abort()之后不再继续glob查寻，但是可以重复使用statCache，从而避免重复系统调用。
• cache 各种对象，每个字段都可能会有以下的值：
• ◦ false -> 路径不存在
• ◦ true -> 路径存在
• ◦ ‘DIR’ -> 路径存在，并且不是目录
• ◦ ‘FILE’ -> 路径存在，并且是目录
• ◦ [file, entries, …] -> 路径存在，并且是目录，此数组的值是fs.readdir的结果
• statCache fs.stat产生的结果的缓存，防止多次相同路径的缓存
• symlinks 在解析有关 ** 模式的时候，记录路径的符号链接
• realpathCache 能过fs.realpath 减少不必要的系统调用的可选对象。这存储在一个实例化的glob对象上，并且可以重复使用。

 

 

Events

• end 当匹配结束时，并且所有匹配项被发现时触发。

如果options设置了nonull 并且没有匹配到，那么 matches 列表包含原始pattern。

匹配项被排序，除非options设置了 nosort。

• match 每一次匹配项被匹配到后触发。
• error 每当遭遇到意外错误或 fs 错误出现（如果设置了options.strict）时触发。
• abort 每当abort() 被调用时，事件被触发。

 

 

Methods

• pause 暂时停止查寻
• resume 查寻的摘要
• abort 停止查寻

 

 

Options

所有配置项都可以通过Minimatch，也可以通过Glob改变匹配模式。此外，有些已经被添加或有特定glob的后果。

所有配置项的默认值为false，除非另外告知。

所有配置项被添加到Glob对象。

如果你运行了许多glob操作，你可以通过Glob对象传递options参数，后续快速操作一些 stat 和 readdir 调用。

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 topath.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 symlinksobject 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 patterns to exclude matches.
• 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)
• nonegate Suppress deprecated negate behavior. (See below.) Default=true
• nocomment Suppress deprecated comment behavior. (See below.) Default=true