grunt.file

ファイルの読み書き、ファイルシステムの走査、グロビングパターンによるファイルの検索など、多くのメソッドが提供されています。これらのメソッドの多くは、組み込みのNode.jsファイル機能のラッパーですが、追加のエラー処理、ロギング、文字エンコーディングの正規化が施されています。

注：カレントワーキングディレクトリがgrunt.file.setBaseまたは--baseコマンドラインオプションで変更されない限り、すべてのファイルパスはGruntfileからの相対パスです。

文字エンコーディング

grunt.file.defaultEncoding

このプロパティを設定すると、すべてのgrunt.fileメソッドで使用されるデフォルトのエンコーディングが変更されます。デフォルトは'utf8'です。この値を変更する必要がある場合は、Gruntfile内でできるだけ早く変更することをお勧めします。

grunt.file.defaultEncoding = 'utf8';

grunt.file.preserveBOM

バージョン 0.4.2 で追加

file.readでバイトオーダーマーク（BOM）を取り除くのではなく、保持するかどうか。

grunt.file.preserveBOM = false;

ファイルの読み書き

grunt.file.read

ファイルの内容を読み込んで返します。文字列を返しますが、options.encodingがnullの場合はBufferを返します。

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

optionsオブジェクトには、以下のプロパティを設定できます。

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

ファイルの内容を読み込み、データをJSONとして解析して結果を返します。サポートされているオプションの一覧については、grunt.file.readを参照してください。

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

grunt.file.readYAML

ファイルの内容を読み込み、データをYAMLとして解析して結果を返します。サポートされているオプションの一覧については、grunt.file.readを参照してください。

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

grunt.file.write

指定された内容をファイルに書き込みます。必要に応じて中間ディレクトリを作成します。文字列は指定された文字エンコーディングを使用してエンコードされ、Bufferは指定されたとおりにディスクに書き込まれます。

--no-writeコマンドラインオプションが指定されている場合、ファイルは実際に書き込まれません。

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

optionsオブジェクトには、以下のプロパティを設定できます。

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

ソースファイルを宛先パスにコピーします。必要に応じて中間ディレクトリを作成します。

--no-writeコマンドラインオプションが指定されている場合、ファイルは実際に書き込まれません。

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

optionsオブジェクトには、以下のプロパティを設定できます。

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

指定されたファイルパスを削除します。ファイルとフォルダを再帰的に削除します。

--forceコマンドラインオプションが指定されていない限り、カレントワーキングディレクトリまたはカレントワーキングディレクトリ外のファイルは削除されません。

--no-writeコマンドラインオプションが指定されている場合、ファイルパスは実際に削除されません。

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

optionsオブジェクトには、以下のプロパティを設定できます。

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のように動作します。中間ディレクトリと共にディレクトリを作成します。modeが指定されていない場合、デフォルトは0777 & (~process.umask())です。

--no-writeコマンドラインオプションが指定されている場合、ディレクトリは実際に作成されません。

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

grunt.file.recurse

ディレクトリを再帰的に処理し、各ファイルに対してcallbackを実行します。

grunt.file.recurse(rootdir, callback)

コールバック関数は以下の引数を受け取ります。

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
}

グロビングパターン

すべてのソースファイルパスを個別に指定することはしばしば実用的ではないため、Gruntは組み込みのnode-globライブラリを介してファイル名展開（グロビングとも呼ばれます）をサポートしています。

グロビングパターンの例については、タスクの設定ガイドの「グロビングパターン」セクションを参照してください。

grunt.file.expand

指定されたグロビングパターンに一致するすべてのファイルまたはディレクトリパスの重複のない配列を返します。このメソッドは、カンマ区切りのグロビングパターンまたはグロビングパターンの配列を受け入れます。!で始まるパターンに一致するパスは、返される配列から除外されます。パターンは順番に処理されるため、包含と除外の順序は重要です。

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

カレントワーキングディレクトリがgrunt.file.setBaseまたは--baseコマンドラインオプションで変更されない限り、ファイルパスはGruntfileからの相対パスです。

optionsオブジェクトは、すべてのminimatchライブラリオプションといくつかの他のオプションをサポートしています。例えば

• filter 有効なfs.Statsメソッド名または、一致したsrcファイルパスを渡されてtrueまたはfalseを返す関数のいずれか。
• nonull ファイルと一致しなくてもsrcパターンを保持します。gruntの--verboseフラグと組み合わせることで、このオプションはファイルパスの問題のデバッグに役立ちます。
• matchBaseスラッシュのないパターンは、ベース名部分のみに一致します。たとえば、これにより*.jsは**/*.jsのように機能します。
• cwdパターンはこのパスを基準に照合され、返されるすべてのファイルパスもこのパスを基準にします。

grunt.file.expandMapping

src-destファイルマッピングオブジェクトの配列を返します。指定されたパターンに一致する各ソースファイルについて、そのファイルパスを指定されたdestに結合します。このファイルパスは、指定されたオプションに応じて、フラット化または名前変更される場合があります。patternsおよびoptions引数を指定する方法の説明については、grunt.file.expandメソッドのドキュメントを参照してください。

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

このメソッドを使用して、マルチタスクのfiles配列をプログラムで生成できますが、タスクの設定ガイドの「ファイルオブジェクトの動的構築」セクションで説明されている宣言型の構文が推奨されます。

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

1つ以上のグロビングパターンを1つ以上のファイルパスと照合します。指定されたグロビングパターンのいずれかに一致するすべてのファイルパスの重複のない配列を返します。patterns引数とfilepaths引数の両方が、単一の文字列または文字列の配列にすることができます。!で始まるパターンに一致するパスは、返される配列から除外されます。パターンは順番に処理されるため、包含と除外の順序は重要です。

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

optionsオブジェクトは、すべてのminimatchライブラリオプションをサポートしています。たとえば、options.matchBaseがtrueの場合、スラッシュのないパターンは、スラッシュが含まれている場合でもパスのベース名と一致します。たとえば、パターン*.jsはファイルパスpath/to/file.jsと一致します。

grunt.file.isMatch

このメソッドは、grunt.file.matchメソッドと同じシグネチャとロジックを含みますが、ファイルが一致した場合は単にtrueを返し、そうでない場合はfalseを返します。

ファイルタイプ

grunt.file.exists

指定されたパスは存在しますか？ブール値を返します。

Node.jsのpath.joinメソッドと同様に、このメソッドはすべての引数を結合し、結果のパスを正規化します。

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

grunt.file.isLink

指定されたパスはシンボリックリンクですか？ブール値を返します。

Node.jsのpath.joinメソッドと同様に、このメソッドはすべての引数を結合し、結果のパスを正規化します。

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

パスが存在しない場合はfalseを返します。

grunt.file.isDir

指定されたパスはディレクトリですか？ブール値を返します。

Node.jsのpath.joinメソッドと同様に、このメソッドはすべての引数を結合し、結果のパスを正規化します。

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

パスが存在しない場合はfalseを返します。

grunt.file.isFile

指定されたパスはファイルですか？ブール値を返します。

Node.jsのpath.joinメソッドと同様に、このメソッドはすべての引数を結合し、結果のパスを正規化します。

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

パスが存在しない場合はfalseを返します。

パス

grunt.file.isPathAbsolute

指定されたファイルパスは絶対パスですか？ブール値を返します。

Node.jsのpath.joinメソッドと同様に、このメソッドはすべての引数を結合し、結果のパスを正規化します。

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

grunt.file.arePathsEquivalent

指定されたすべてのパスが同じパスを参照していますか？ブール値を返します。

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

grunt.file.doesPathContain

すべての子孫パスが指定された祖先パス内に含まれていますか？ブール値を返します。

注：パスが実際に存在するかどうかはチェックしません。

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

grunt.file.isPathCwd

指定されたファイルパスはCWDですか？ブール値を返します。

Node.jsのpath.joinメソッドと同様に、このメソッドはすべての引数を結合し、結果のパスを正規化します。

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

grunt.file.isPathInCwd

指定されたファイルパスはCWD内にありますか？注：CWDはCWDの*内部*にはありません。ブール値を返します。

Node.jsのpath.joinメソッドと同様に、このメソッドはすべての引数を結合し、結果のパスを正規化します。

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

grunt.file.setBase

gruntのカレントワーキングディレクトリ（CWD）を変更します。デフォルトでは、すべてのファイルパスはGruntfileからの相対パスです。これは、--baseコマンドラインオプションと同様に機能します。

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

Node.jsのpath.joinメソッドと同様に、このメソッドはすべての引数を結合し、結果のパスを正規化します。

外部ライブラリ

非推奨

以下にリストされているすべての外部ライブラリは、現在非推奨となっています。

プロジェクトの依存関係でこれらの外部ライブラリを管理するには、**npm**を使用してください。

たとえば、Lo-Dashを使用する場合、最初にnpm install lodashをインストールしてから、Gruntfileで次のように使用します。var _ = require('lodash');

grunt.file.glob

非推奨

glob - ファイルグロビングユーティリティ。

grunt.file.minimatch

非推奨

minimatch - ファイルパターンマッチングユーティリティ。

grunt.file.findup

非推奨

findup-sync - 一致するファイルパターンを上方向に検索します。