grunt.file

這里提供了很多用于讀寫文件、遍歷文件系統(tǒng)和通過模式匹配查找文件的方法。其中很多方法都是Node.js中的文件操作函數(shù)的封裝，但是提供了額外的錯(cuò)誤處理、日志記錄和字符編碼轉(zhuǎn)換。

注意：所有的文件路徑都是參照 Gruntfile 文件的相對(duì)路徑，除非通過 grunt.file.setBase 函數(shù)或在命令行中指定 --base 參數(shù)改變當(dāng)前工作目錄。

字符編碼

grunt.file.defaultEncoding

設(shè)置此屬性可以改變所有 grunt.file 方法的默認(rèn)編碼。默認(rèn)是 'utf8'。如果必須改變這個(gè)值，建議你在Gruntfile文件中盡可能早改變。

grunt.file.defaultEncoding = 'utf8';

grunt.file.preserveBOM

添加于 0.4.2 版本

是否在 file.read 時(shí)保留字節(jié)順序標(biāo)記（BOM）。

grunt.file.preserveBOM = false;

讀寫文件

grunt.file.read

讀取并返回文件的內(nèi)容。返回值為一個(gè)字符串，如果 options.encoding 為 null ，則返回一個(gè) Buffer。

grunt.file.read(filepath [, options])

options 對(duì)象可以設(shè)置以下屬性：

var options = {
  // If an encoding is not specified, default to grunt.file.defaultEncoding.
  // If specified as null, returns a non-decoded Buffer instead of a string.
  encoding: encodingName
};

grunt.file.readJSON

讀取一個(gè)文件的內(nèi)容，將其按照J(rèn)SON格式解析，返回結(jié)果。參見 grunt.file.read 獲取其所支持的參數(shù)列表。

grunt.file.readJSON(filepath [, options])

grunt.file.readYAML

讀取一個(gè)文件的內(nèi)容，將其按照YAML格式解析，返回結(jié)果。參見 grunt.file.read 獲取其所支持的參數(shù)列表。

grunt.file.readYAML(filepath [, options])

grunt.file.write

將指定的內(nèi)容寫入文件中，如果需要，將創(chuàng)建文件路徑中所有不存在的目錄。字符串將按照指定的字符編碼進(jìn)行編碼，Buffers 將會(huì)按照指定的方式寫入磁盤。

如果指定了 --no-write 命令行參數(shù)，將不會(huì)真正寫入文件。

grunt.file.write(filepath, contents [, options])

options 對(duì)象可設(shè)置以下屬性：

var options = {
  // If an encoding is not specified, default to grunt.file.defaultEncoding.
  // If `contents` is a Buffer, encoding is ignored.
  encoding: encodingName
};

grunt.file.copy

將原文件拷貝到指定路徑，如果需要，將創(chuàng)建文件路徑中所有不存在的目錄

如果指定了 --no-write 命令行參數(shù)，將不會(huì)真正寫入文件。

grunt.file.copy(srcpath, destpath [, options])

options 對(duì)象可設(shè)置以下屬性：

var options = {
  // If an encoding is not specified, default to grunt.file.defaultEncoding.
  // If null, the `process` function will receive a Buffer instead of String.
  encoding: encodingName,
  // The source file contents, source file path, and destination file path 
  // are passed into this function, whose return value will be used as the
  // destination file's contents. If this function returns `false`, the file
  // copy will be aborted.
  process: processFunction,
  // These optional globbing patterns will be matched against the filepath
  // (not the filename) using grunt.file.isMatch. If any specified globbing
  // pattern matches, the file won't be processed via the `process` function.
  // If `true` is specified, processing will be prevented.
  noProcess: globbingPatterns
};

grunt.file.delete

刪除指定的文件。文件和目錄會(huì)被依次遞歸刪除。

Will not delete the current working directory or files outside the current working directory unless the--force command-line option is specified.

如果指定了 --no-write 命令行參數(shù)，那么，文件路徑將不會(huì)真的被刪除。

grunt.file.delete(filepath [, options])

options 對(duì)象只可以設(shè)置以下屬性：

var options = {
  // Enable deleting outside the current working directory. This option may
  // be overridden by the --force command-line option.
  force: true
};

目錄操作

grunt.file.mkdir

工作方式類似 mkdir -p。創(chuàng)建一個(gè)目錄和所有的中間目錄。如果沒有指定 mode ，默認(rèn)是0777 & (~process.umask()).

如果沒有 --no-write 命令行參數(shù)，目錄不會(huì)被真正創(chuàng)建。

grunt.file.mkdir(dirpath [, mode])

grunt.file.recurse

遞歸遍歷整個(gè)目錄，對(duì)每個(gè)文件都執(zhí)行 callback 函數(shù)。

grunt.file.recurse(rootdir, callback)

callback 函數(shù)接收以下參數(shù)：

function callback(abspath, rootdir, subdir, filename) {
  // The full path to the current file, which is nothing more than
  // the rootdir + subdir + filename arguments, joined.
  abspath
  // The root director, as originally specified.
  rootdir
  // The current file's directory, relative to rootdir.
  subdir
  // The filename of the current file, without any directory parts.
  filename
}

模式匹配

有時(shí)單獨(dú)指定所有原始文件路徑是不現(xiàn)實(shí)的，因此，Grunt通過內(nèi)置的node-glob 庫(kù)支持文件名 expansion (或者叫做 globbing) 。

參見 配置任務(wù) 指南中的 "Globbing patterns" 章節(jié)以獲取 globbing pattern 實(shí)例。

grunt.file.expand

返回包含匹配給定通配符模式的文件或者目錄路徑的特殊數(shù)組。這個(gè)方法接收一個(gè)逗號(hào)分割的匹配模式或者一個(gè)匹配模式數(shù)組。如果路徑匹配模式以!開頭，它會(huì)從返回的數(shù)組排除所匹配的項(xiàng)。模式是按指定的順序進(jìn)行處理的， 因此包含和排除文件的順序是很重要的。

grunt.file.expand([options, ] patterns)

文件路徑都是參照 Gruntfile 文件的相對(duì)路徑，除非通過 grunt.file.setBase 或 --base 命令行參數(shù)修改了當(dāng)前工作目錄。

options 對(duì)象支持所有 minimatch library 的參數(shù)，也支持額外的一些，如下：

• filter E接受一個(gè)有效的 fs.Stats 方法名 或者一個(gè)已經(jīng)通過了src文件路徑匹配的函數(shù)，這個(gè)函數(shù)會(huì)返回true或false。
• nonull 會(huì)保留src匹配模式，即使文件匹配失敗。結(jié)合Grunt的-verbose標(biāo)志，這個(gè)選項(xiàng)有助于文件路徑問題的調(diào)試。
• matchBase 不帶斜線的模式只會(huì)匹配基本的名稱部分。例如，這會(huì)使*.js就像**/*.js一樣。
• cwd 會(huì)讓模式相對(duì)于當(dāng)前路徑進(jìn)行模式匹配，所有返回的文件路徑也是相對(duì)于當(dāng)前路徑的。

grunt.file.expandMapping

返回一個(gè)src-dest文件映射對(duì)象的數(shù)組。通過所指定的模式來匹配每一個(gè)源文件，然后將匹配的文件路徑加入指定的dest中(dest存放匹配的文件路徑)。這個(gè)文件路徑會(huì)按照指定的選項(xiàng)加工或者重命名過。 查看grunt.file.expand方法文檔可以了解如何指定patterns和options

grunt.file.expandMapping(patterns, dest [, options])

注意：這個(gè)方法可以用于以編程的方式針對(duì)多任務(wù)的情況生成一個(gè)files數(shù)組，它會(huì)優(yōu)先使用在配置任務(wù)指南中"動(dòng)態(tài)構(gòu)建文件對(duì)象"一節(jié)所描述的語(yǔ)法。

除了支持那些grunt.file.expand方法之外，options對(duì)象還支持下面這些屬性:

var options = {
  // The directory from which patterns are matched. Any string specified as
  // cwd is effectively stripped from the beginning of all matched paths.
  cwd: String,
  // Remove the path component from all matched src files. The src file path
  // is still joined to the specified dest.
  flatten: Boolean,
  // Remove anything after (and including) either the first or last "." in the 
  // destination path (indicated by options.extDot), then append this value.
  ext: String,
  // *Added in 0.4.3*
  // Indicates where the period demarcating the extension is located. Can take:
  // - 'first' (extension begins after the first period in the file name) 
  // - 'last' (extension begins after the last period)
  // Default: 'first'
  extDot: String,
  // If specified, this function will be responsible for returning the final
  // dest filepath. By default, it joins dest and matchedSrcPath like so:
  rename: function(dest, matchedSrcPath, options) {
    return path.join(dest, matchedSrcPath);
  }
};

grunt.file.match

針對(duì)一個(gè)或者多個(gè)文件路徑來匹配一個(gè)或者多個(gè)匹配模式。返回一個(gè)特殊的數(shù)組，這個(gè)數(shù)組包含與指定的通配符模式任意匹配的所有文件路徑。patterns和filepaths參數(shù)可以是一個(gè)單一的字符串或者也可以是一個(gè)字符串?dāng)?shù)組.如果匹配模式以!開頭，就會(huì)從返回的數(shù)組從排除模式匹配的路徑。模式會(huì)按指定的順序進(jìn)行處理，因此包含和排除文件的順序是重要的。

grunt.file.match([options, ] patterns, filepaths)

options對(duì)象也支持minimatch庫(kù)提供的所有選項(xiàng)。例如：如果options.matchBase為true，即使模式中不帶斜線，這個(gè)模式也會(huì)匹配包含斜線的基本名稱。例如：*.js模式將匹配path/to/file.js文件路徑。

grunt.file.isMatch

這個(gè)方法與grunt.file.match方法包含同樣的簽名和邏輯，但是如果它匹配任意文件，就會(huì)簡(jiǎn)單的返回ture，否則返回false。

判斷文件類型

grunt.file.exists

檢測(cè)給定的路徑是否存在，返回boolean類型的值。

和Node.js 中的 path.join 方法一樣，此方法將所有參數(shù)連接在一起，并對(duì)結(jié)果做規(guī)范化。

grunt.file.exists(path1 [, path2 [, ...]])

grunt.file.isLink

給定的路徑是否是符號(hào)鏈接，返回boolean類型的值。

和 Node.js 中的 path.join 方法一樣，此方法此方法將所有參數(shù)連接在一起，并對(duì)結(jié)果做規(guī)范化。

grunt.file.isLink(path1 [, path2 [, ...]])

如果路徑不存在則返回false。

grunt.file.isDir

指定的路徑是否是一個(gè)目錄？返回boolean類型的值。

和 Node.js 中的 path.join 方法一樣，此方法此方法將所有參數(shù)連接在一起，并對(duì)結(jié)果做規(guī)范化。

grunt.file.isDir(path1 [, path2 [, ...]])

如果路徑不存在它也會(huì)返回false。

grunt.file.isFile

指定的路徑是否是一個(gè)文件？ 返回boolean類型的值。

和 Node.js 中的 path.join 方法一樣，此方法此方法將所有參數(shù)連接在一起，并對(duì)結(jié)果做規(guī)范化。

grunt.file.isFile(path1 [, path2 [, ...]])

如果路徑不存在將返回false。

路徑

grunt.file.isPathAbsolute

指定的文件路徑是否是絕對(duì)路徑？ 返回boolean類型的值。

和 Node.js 中的 path.join 方法一樣，此方法此方法將所有參數(shù)連接在一起，并對(duì)結(jié)果做規(guī)范化。

grunt.file.isPathAbsolute(path1 [, path2 [, ...]])

grunt.file.arePathsEquivalent

所有給出的路徑是否都是同一個(gè)路徑？返回boolean類型的值。

grunt.file.arePathsEquivalent(path1 [, path2 [, ...]])

grunt.file.doesPathContain

所有descendant路徑是否全部包含在指定的ancestor路徑中？返回boolean類型的值。

注意：不需要檢查路徑是否真的存在。

grunt.file.doesPathContain(ancestorPath, descendantPath1 [, descendantPath2 [, ...]])

grunt.file.isPathCwd

指定的文件路徑是否是CWD？返回boolean類型的值。

和 Node.js 中的 path.join 方法一樣，此方法此方法將所有參數(shù)連接在一起，并對(duì)結(jié)果做規(guī)范化。

grunt.file.isPathCwd(path1 [, path2 [, ...]])

grunt.file.isPathInCwd

指定的文件路徑是否在在CWD中？注意：CWD不在CWD中 。返回boolean類型的值。

和 Node.js 中的 path.join 方法一樣，此方法此方法將所有參數(shù)連接在一起，并對(duì)結(jié)果做規(guī)范化。

grunt.file.isPathInCwd(path1 [, path2 [, ...]])

grunt.file.setBase

改變Grunt的當(dāng)前工作目錄(CWD)。默認(rèn)情況下，所有文件路徑都是參照 Gruntfile 文件的相對(duì)路徑。此函數(shù)和 --base 命令行參數(shù)的工作方式一致。

grunt.file.setBase(path1 [, path2 [, ...]])

和 Node.js 中的 path.join 方法一樣，此方法此方法將所有參數(shù)連接在一起，并對(duì)結(jié)果做規(guī)范化。

外部工具庫(kù)

不建議使用

下面列出的所有外部工具庫(kù)已經(jīng)不再建議使用了。

請(qǐng)使用 npm 管理項(xiàng)目中對(duì)第三方工具庫(kù)的依賴。

例如，如果你需要使用 Lo-Dash，首先通過 npm install lodash 安裝，然后在 Gruntfile 文件中使用即可： var _ = require('lodash');

grunt.file.glob

不建議使用

glob - File globbing utility.

grunt.file.minimatch

不建議使用

minimatch - File pattern matching utility.

grunt.file.findup

不建議使用

findup-sync - Search upwards for matching file patterns.