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