grunt.file

ファイル読み込み、書き込み、ファイルシステムの横断、そしてglobパターンマッチングによるファイル検索など多くのメソッドが用意されています。これらのほとんどのメソッドが、Node.js組み込みのファイル関数をラッパーし、エラーハンドリング、ログ、文字列エンコーディングの正規化の機能を追加しています。

現在の作業ディレクトリがgrunt.file.setBaseまたは、--baseオプションによって変更されない限り、全てのファイルパスはGruntfileからの相対パスになります。

grunt.file.defaultEncoding

このプロパティを設定することで、全てのgrunt.fileメソッドに使用されるデフォルトのエンコーディングを変更します。デフォルトは、'utf8'になっています。もし、この値を変更しなければならない場合は、出来るだけ早い段階でGruntfile内で変更することをお勧めします。

grunt.file.defaultEncoding = 'utf8';

grunt.file.read

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

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

optionsオブジェクトでは、これらのプロパティが使用可能です。

var options = {
  // もし、エンコーディングが指定されていなければ、grunt.file.defaultEncodeingがデフォルトになります。
  // もし、nullが指定されると、文字列の代わりにデコードされてないBufferが返されます。
  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 = {
  // もし、エンコーディングが指定されていなければ、grunt.file.defaultEncodeingがデフォルトになります。
  // もし、`contents`がBufferであれば、エンコーディングは無視されます。
  encoding: encodingName
};

grunt.file.copy

ファイルを遷移先のパスにコピーし、必要であればディレクトリを生成します。

もし、コマンドライン上で--no-writeオプションが指定されると、実際にはファイルに書き込まれません。

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

optionsオブジェクトでは、これらのプロパティが使用可能です。

var options = {
  // もし、エンコーディングが指定されていなければ、grunt.file.defaultEncodeingがデフォルトになります。
  // もし、nullであれば、`process`関数が文字列の代わりにBufferを受け取ります。
  encoding: encodingName,
  // ソースファイルの内容とファイルパスはこの関数に渡され、その戻り値は遷移先ファイルの内容として使用されます。
  // もし、この関数がfalseを返すと、ファイルコピーは中断されます。
  process: processFunction,
  // これらのオプションのglobパターンは、ファイルパス(ファイル名ではない)に対してマッチし、
  // grunt.file.isMatchに使用されます。もし、指定されたglobパターンがマッチした場合、
  // そのファイルはprocess関数によって処理されます。
  // もし、trueが指定された場合、処理されることを防ぎます。
  noProcess: globbingPatterns
};

grunt.file.delete

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

現在の作業フォルダのディレクトリまたはファイルは、現在のフォルダの外側からコマンドライン上で--forceオプションが指定されなければ、削除されません。

もし、コマンドライン上で--no-writeオプションが指定されると、実際にはファイルは削除されません。

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

optionsオブジェクトは1つの指定可能なプロパティを持ちます。

var options = {
  // 現在の作業ディレクトリを外側から削除可能にします。
  // --forceコマンドラインオプションによって、このオプションが上書きされます。
  force: true
};

grunt.file.mkdir

mkdir -pのような処理を行います。任意の中間ディレクトリと共に、ディレクトリを作成します。 modeが指定されなければ、デフォルトは0777 & (~process.umask())になります。

If the --no-write command-line option is specified, directories won't actually be created. もし、コマンドライン上で--no-writeオプションが指定されると、実際にはフォルダは作成されません。

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

grunt.file.recurse

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

grunt.file.recurse(rootdir, callback)

callback関数は、下記の引数を受け取ります。

function callback(abspath, rootdir, subdir, filename) {
  //現在処理されているファイルの絶対パスで、rootdif + subdir + filename 引数を結合したものです。
  abspath
  // 指定されたルートディレクトリです。
  rootdir
  // 現ファイルからルートディレクトリまでのディレクトリです。
  subdir
  // 現在処理されているファイルのディレクトリ部分を除いたファイル名です。
  filename
}

全てのファイルパスを個別に指定するのは、現実的ではありません。そこで、Gruntはファイル名指定のための拡張機能(globパターンとして知られている)を、組み込みの node-glob ライブラリを通してサポートしています。

globパターンについては、タスクの設定のページの「globパターン」の項目を確認してください。

grunt.file.expand

globパターンによってマッチした全てのファイルまたはディレクトリパスの一意な配列を返します。このメソッドは、カンマ区切り、または配列によるglobパターンの指定を受け入れます。 !で始まるパターンにマッチしたパスは、戻り値の配列から除外されます。パターンは順番に処理されるので、含む、除外、の指定順は重要になります。

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

ファイルパスは作業ディレクトリでは無く、Gruntfileからの相対です。 grunt.file.setBaseまたはコマンドラインの--baseオプションによって変更することが可能です。

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

filter: 検証用の fs.Statsメソッド名、またはマッチしたソースファイルパスを渡してtrueまたはfalseを返す関数を指定します。
nonull: srcパターンをファイルのマッチに失敗したとしても保有します。 Gruntの--verboseフラグを組み合わせると、デバッグ時のファイルパス出力に便利です。
matchBase: スラッシュ無しのベース名にマッチするパターンをです。例).*.jsは**/*.jsのように作用します。
cwd: パターンは、このパスと相対的に一致されるようになり、全てのファイルパスの返り値もこのパスの相対となります。

grunt.file.expandMapping

src-destファイルマッピングオブジェクトの配列を返します。指定されたパターンにマッチした各ソースファイルに対して、指定されたdestにそのファイルパスを結びつけます。このファイルパスは指定したオプションに応じて、平らに(?)または、名前を変更されることがあります。 grunt.file.expandメソッドのドキュメントに、パターンとオプション引数の指定方法の説明があるので確認してみてください。

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

このメソッドは、マルチタスクのために動的にファイルの配列を生成するのに使用されることがあり、「タスクの設定」ガイドの"ファイルの動的ビルド"の項の宣言構文が推奨されていることに注意してください。

加えて、grunt.file.expandメソッドをサポートするので、 optionsオブジェクトはこれらのプロパティもサポートします。

var options = {
  // パターンがマッチされるディレクトリです。cwdとして指定された文字列は全て、
  // 一致した全てのパスの先頭から取り除かれます。
  cwd: String,
  // パスコンポーネントを全てのマッチしたsrcファイルから削除します。
  // srcファイルパスは指定したdestに結びついたままになります。
  flatten: Boolean,
  // 最初の"."以降の文字を削除し、遷移先パスには、この値を追加します。
  ext: String,
  // 指定された場合、この関数が最終的な遷移先ファイルパス処理を請け負います。
  // デフォルトでは、下記のようにdestとmatchedSrcPathを追加します。
  rename: function(dest, matchedSrcPath, options) {
    return path.join(dest, matchedSrcPath);
  }
};

grunt.file.match

1つ以上のファイルパスに対してマッチする、1つ以上のglobパターンです。指定したglobパターンにマッチした全てのファイルパスの一意の配列を返します。 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

与えられたパスが現在の作業ディレクトリか否かを真偽値で返します。Node.jsの path.join のようなメソッドで、すべての引数を結合し、その結果のパスを正規化します。

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

grunt.file.isPathInCwd

与えられたパスが現在の作業ディレクトリ内に含まれるか否かを真偽値で返します。(作業ディレクトリ自体は、これに含まれません)Node.jsの path.join のようなメソッドで、すべての引数を結合し、その結果のパスを正規化します。

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

grunt.file.setBase

Gruntの現在の作業ディレクトリを変更します。デフォルトでは、全てのファイルパスはGruntfileの相対になっています。これは、コマンドラインオプションに--baseを指定するのと同じ働きになります。

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

Node.jsのpath.join のようなメソッドで、すべての引数を結合し、その結果のパスを正規化します。

grunt.file.glob

glob - 汎用的なファイルglob機能です。

grunt.file.minimatch

minimatch - 汎用的なファイルマッチ機能です。

grunt.file.findup

findup-sync - 現在のディレクトリから、祖先ディレクトリに遡って最初にファイルパターンにマッチするものを検索します。