grunt.file

grunt.file

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

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

字符編碼

grunt.file.defaultEncoding

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

grunt.file.defaultEncoding = 'utf8';

grunt.file.preserveBOM

添加于 0.4.2 版本

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

grunt.file.preserveBOM = false;

讀寫文件

grunt.file.read

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

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

options 對象可以設(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

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

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

grunt.file.readYAML

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

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

grunt.file.write

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

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

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

options 對象可設(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ù)，將不會真正寫入文件。

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

options 對象可設(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

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

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ù)，那么，文件路徑將不會真的被刪除。

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

options 對象只可以設(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)建一個目錄和所有的中間目錄。如果沒有指定 mode ，默認是0777 & (~process.umask()).

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

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

grunt.file.recurse

遞歸遍歷整個目錄，對每個文件都執(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
}

模式匹配

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

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

grunt.file.expand

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

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

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

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

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

grunt.file.expandMapping

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

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

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

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

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

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

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

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

grunt.file.isMatch

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

判斷文件類型

grunt.file.exists

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

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

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

grunt.file.isLink

給定的路徑是否是符號鏈接，返回boolean類型的值。

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

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

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

grunt.file.isDir

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

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

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

如果路徑不存在它也會返回false。

grunt.file.isFile

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

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

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

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

路徑

grunt.file.isPathAbsolute

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

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

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

grunt.file.arePathsEquivalent

所有給出的路徑是否都是同一個路徑？返回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ù)連接在一起，并對結(jié)果做規(guī)范化。

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

grunt.file.isPathInCwd

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

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

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

grunt.file.setBase

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

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

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

外部工具庫

不建議使用

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

請使用 npm 管理項目中對第三方工具庫的依賴。

例如，如果你需要使用 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.