grunt.file

这里提供了很多用来读取或者编辑文件,通过匹配模式遍历文件系统或者查找文件的方法。其中很多方法都是对Node.js中文件操作功能的一次包装,但是在这里标准化了额外的错误处理,日志记录和字符编码相关的行为。

注意:通常情况下所有的文件路径都是相对于Gruntfile所在目录来确定,除非当前工作目录使用grunt.file.setBase或者命令行选项--base改变过。

字符编码

grunt.file.defaultEncoding

用于通过所有的grunt.file方法设置这个属性来改变默认的字符编码。默认情况下为'utf8'。如果你改变了这个值,推荐你尽早在你项目Gruntfile中改变它。

  1. grunt.file.defaultEncoding = 'utf8'

读写文件

grunt.file.read

读取并返回指定文件内容。它会返回一个字符串,通常这种情况下它会返回一个Buffer(缓冲区),除非options.encodingnull

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

options对象可以指定下面这些属性:

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

grunt.file.readJSON

读取指定文件的内容,它会将数据作为JSON信息解析并返回结果。可以查看grunt.file.read来了解它所支持的选项列表。

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

grunt.file.readYAML

读取指定文件的内容,它会将数据作为YAML解析并返回结果。 同样可以查看grunt.file.read来了解它所支持的选项。

grunt.file.write

写入指定的内容到一个文件中,必要的情况下它会创建一个中介目录。字符串会使用指定字符编码进行编码,Buffters会按照其指定的方式写入磁盘。

如果指定了--no-write命令行选项,不会真正写入文件中。

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

options对象可以指定下面这些属性:

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

grunt.file.copy

复制一个源文件到目标路径指向的目录中,必要的情况下它也会创建一个中介目录。

如果指定了--no-write命令行选项,它不会真正写入文件中。

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

options对象可以指定下面这些属性:

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

grunt.file.delete

删除指定文件路径,它会以递归的方式删除指定的文件和目录。

它不会删除当前工作目录或者当前工作目录之外的文件,除非指定了--force命令行选项。

如果指定了--no-write命令行选项,文件路径不会真正删除。

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

options对象可以指定下面这些属性:

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

目录操作

grunt.file.mkdir

类似mkdir -p操作。可以使用任意参考目录创建一个新目录。如果没有指定mode选项,则默认为0777 & (~process.umask())

如果指定了--no-write命令行选项,则不会真正创建目录。

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

grunt.file.recurse

在目录中以递归方式执行为每个文件指定的回调函数。

  1. grunt.file.recurse(rootdir, callback)

回调函数可以接收以下参数:

  1. function callback(abspath, rootdir, subdir, filename) {
  2. // The full path to the current file, which is nothing more than
  3. // the rootdir + subdir + filename arguments, joined.
  4. abspath
  5. // The root director, as originally specified.
  6. rootdir
  7. // The current file's directory, relative to rootdir.
  8. subdir
  9. // The filename of the current file, without any directory parts.
  10. filename
  11. }

匹配模式

原文为Globbing Patterns,主要是指使用一些匹配模式来操作,因而译作匹配模式。

通常单独指定所有的源文件的路径往往是不切实际的,因此Grunt支持通过内置的node-glob库来根据文件扩展名来选择文件(也就通配符)。

配置任务指南的”通配符模式”一节可以查看更多匹配模式的例子。

grunt.file.expand

返回包含匹配给定通配符模式的文件或者目录路径的特殊数组。这个方法接收一个逗号分割的匹配模式或者一个匹配模式数组。如果路径匹配模式以!开头,它会从返回的数组排除所匹配的项。模式是按指定的顺序进行处理的, 因此包含和排除文件的顺序是明显的。

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

通常文件路径都是相对于Gruntfile所在目录的路径,除非当前工作目录使用grunt.file.setBase或者命令行选项--base改变了。

options对象支持所有的minimatch库提供的选项,它还支持其他的一些选项。例如:

  • filter 接受一个有效的fs.Stats方法名或者一个已经通过了src文件路径匹配的函数,这个函数会返回truefalse
  • nonull 会保留src匹配模式,即使文件匹配失败。结合Grunt的-verbose标志,这个选项有助于文件路径问题的调试;
  • matchBase 不带斜线的模式只会匹配基本的名称部分。例如,这会使*.js就像**/*.js一样;
  • cwd 会让模式相对于当前路径进行模式匹配,所有返回的文件路径也是相对于当前路径的。

grunt.file.expandMapping

返回一个src-dest文件映射对象的数组。通过所指定的模式来匹配每一个源文件,然后将匹配的文件路径加入指定的dest中(dest存放匹配的文件路径)。这个文件路径会按照指定的选项加工或者重命名过。 查看grunt.file.expand方法文档可以了解如何指定patternsoptions参数。

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

注意这个方法可以用于以编程的方式针对多任务的情况生成一个files数组,它会优先使用在配置任务指南中”动态构建文件对象”一节所描述的语法。

除了支持那些grunt.file.expand方法之外,options对象还支持下面这些属性:

  1. var options = {
  2. // The directory from which patterns are matched. Any string specified as
  3. // cwd is effectively stripped from the beginning of all matched paths.
  4. cwd: String,
  5. // Remove the path component from all matched src files. The src file path
  6. // is still joined to the specified dest.
  7. flatten: Boolean,
  8. // Remove anything after (and including) the first "." in the destination
  9. // path, then append this value.
  10. ext: String,
  11. // If specified, this function will be responsible for returning the final
  12. // dest filepath. By default, it joins dest and matchedSrcPath like so:
  13. rename: function(dest, matchedSrcPath, options) {
  14. return path.join(dest, matchedSrcPath);
  15. }
  16. };

grunt.file.match

针对一个或者多个文件路径来匹配一个或者多个匹配模式。返回一个特殊的数组,这个数组包含与指定的通配符模式任意匹配的所有文件路径。patternsfilepaths参数可以是一个单一的字符串或者也可以是一个字符串数组.如果匹配模式以!开头,就会从返回的数组从排除模式匹配的路径。模式会按指定的顺序进行处理,因此包含和排除文件的顺序是明显的。

  1. 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

给定的路径是否存在?返回一个布尔值。

就像Node.js的path.join方法,这个方法会连接所有的参数并标准化返回的路径。

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

给定的路径是否表示链接?返回一个布尔值。

就像Node.js的path.join方法,这个方法也会连接所有的参数并标准化返回的路径。

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

如果路径不存在它会返回false。

gruntfile.isDir

给定的路径是否是一个目录?返回一个布尔值。

就像Node.js的path.join方法,这个方法也会连接所有的参数并标准化返回的路径。

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

如果路径不存在它也会返回false。

grunt.file.isFile

给定的路径是否是一个文件?返回一个布尔值。

就像Node.js的path.join方法,这个方法也会连接所有的参数并标准化返回的路径。

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

如果给定路径不存在它也会返回false。

路径

grunt.file.isPathAbsolute

给定文件路径是否是绝对路径?返回一个布尔值。

就像Node.js的path.join方法,这个方法也会连接所有的参数并标准化返回的路径。

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

grunt.file.arePathsEquivalent

所有指定的路径是否引用同一路径?返回布尔值。

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

grunt.file.doesPathContain

所有指定的子路径都是否属于指定的父路径?返回布尔值。

注意:它并不会检查路径是否真实存在。

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

grunt.file.isPathCwd

给定文件路径是否是CWD目录[Current Working Directory -> 当前工作目录]?返回一个布尔值。

就像Node.js的path.join方法,这个方法也会连接所有的参数并标准化返回的路径。

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

grunt.file.isPathInCwd

给定的文件路径是否在CWD中的?注意:CWD并不在CWD中。返回一个布尔值。

就像Node.js的path.join方法,这个方法也会连接所有的参数并标准化返回的路径。

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

grunt.file.setBase

改变Grunt的当前工作目录(CWD)。默认情况下,所有的文件路径都是相对于Gruntfile所在目录的。就像--base命令行选项。

就像Node.js的path.join方法,这个方法也会连接所有的参数并标准化返回的路径。

外部库

来自第三方的库

grunt.file.glob

glob - 文件通配符工具。

grunt.file.minimatch

minimatch - 文件匹配模式工具。

grunt.file.findup

findup-sync - 向上搜索的文件匹配模式。