プロジェクトのScaffolding

grunt-init
インストール
使用方法
テンプレートのインストール
テンプレートのカスタマイズ
デフォルトのプロンプト回答の指定
initテンプレートの定義
initテンプレートの内部
組み込みプロンプト

grunt-init

Grunt-initはプロジェクトを自動生成するのに使用されるScaffoldingツールです。現在の環境といくつかの質問への回答を元に、全体のディレクトリ構造が生成されます。質問への回答に沿って選択されたテンプレートによって、ファイルとその内容が作成されます。

このスタンドアローン機能は、Gruntの"init"タスクとして組み込まれています。 Upgrading from 0.3 to 0.4 を参照して、詳細と変更点を確認してください。

インストール

grunt-initを使用するには、グローバル上にそれをインストールします。

npm install -g grunt-init

grunt-initコマンドをシステムパスに加え、どこからでも実行できるようにしておいてください。これを実行するには、sudoまたは管理者として実行する必要があるかもしれません。

使用方法

grunt-init --helpにより、プログラムのヘルプと利用可能なテンプレートを参照することが出来ます。
grunt-init TEMPLATEにより、利用可能なテンプレートを元にプロジェクトを作成します。
grunt-init /path/to/TEMPLATEにより、任意の位置のテンプレートを元にプロジェクトを作成します。

現在のディレクトリに多くのファイルが生成されるため、もしファイルを上書きされたくない場合は、最初に新しいディレクトリを作成し、移動していから実行するようにしてください。

テンプレートのインストール

~/.grunt-init/(Windowsであれば、%USERPROFILE%\.grunt-init\)に一度、テンプレートがインストールされ、grunt-initを通して使用することが出来るようになります。 gitを使ってテンプレートを、そのディレクトリにcloneすることが推奨されています。例えば、 grunt-init-jquery テンプレートは、次のようにしてインストールすることが出来ます。

git clone [email protected]:gruntjs/grunt-init-jquery.git ~/.grunt-init/jquery

もし、ローカルで"foobarbaz"として利用できるテンプレートを作成したい場合、 ~/.grunt-init/foobarbazを指定することで、クローンされます(翻訳に自信無し) Grunt-initは、~/.grunt-init/内に存在するものとして、テンプレートディレクトリ名を使用します。

いくつかのgrunt-initテンプレートが公式によってメンテナンスされています。

grunt-init-commonjs: Nodeunitのユニットテストを含む、commonjsモジュールを生成します。
( sample "generated" repo | creation transcript )
grunt-init-gruntfile: 基本的なGruntfileを生成します。
( sample "generated" repo | creation transcript )
grunt-init-gruntplugin: Nodeunitのユニットテストを含む、Gruntプラグインを生成します。
( sample "generated" repo | creation transcript )
grunt-init-jquery: Nodeunitのユニットテストを含む、jQueryプラグインを生成します。
( sample "generated" repo | creation transcript )
grunt-init-node: Nodeunitのユニットテストを含む、Node.jsモジュールを生成します。
( sample "generated" repo | creation transcript )

テンプレートのカスタマイズ

テンプレートは作成してそのカスタムテンプレートを使用することが可能です。テンプレートは前述のテンプレートと同じ構造に沿って作られなければいけません。

my-templateという名前のサンプルのテンプレートは、この一般的なファイル構造に従っています。

my-template/template.js - メインのテンプレートファイルです。
my-template/rename.json - テンプレート処理中の、テンプレート固有の名称変更ルールです。
my-template/root/ - ファイルをコピーする場所です。

/path/to/my-templateにこれらのファイルが存在するとして、grunt-init /path/to/my-templateコマンドはこのテンプレートを使って処理を行います。複数の一意な名前がつけられた、[built-in templates][]のようなテンプレートが、同じディレクトリ内に存在することもあるかもしれません。

もし、カスタムテンプレートを~/.grunt-init/(Windowsなら%USERPROFILE%\.grunt-init\ on Windows)に、配置したいのであれば、grunt-init my-templateとすれば、自動的にその場所が利用されます。

ファイルのコピー

テンプレートの初期化が実行している間、init.filesToCopyとinit.copyAndProcessメソッドを使用して、 root/サブディレクトリ内のいずれかのファイルは、現在のディレクトリにコピーされます。

コピーされた全てのファイルは、テンプレートとして処理され、{% %}付きのテンプレートであれば、 noProcessオプションが指定されていなければ、相当するデータオブジェクトのプロパティ値が割り当てられます。例として、jquery template を確認してみてください。

テンプレートファイルの名称変更、または除外

rename.jsonには、sourcepathからdestpathへのマッピングの名称変更について記述します。 sourcepathは、root/フォルダからの相対的なコピーされるファイルへのパスにしなければいけないのに対し、 destpath値は、遷移先ファイルの記述に{% %}テンプレートを含めることができます。

もし、falseがdestpathに指定されると、ファイルのコピーは行われません。また、globパータンはsrcpathのためにサポートされています。

デフォルトのプロンプト回答の指定

各初期プロンプトは、デフォルト値がハードコーディングされているか、現在の環境を調べて、それに沿ってデフォルト値が決定されています。もし、個別のプロンプトのデフォルト値を上書きしたければ、OS XまたはLinuxなら~/.grunt-init/defaults.json、 Windowsであれば%USERPROFILE%\.grunt-init\defaults.jsonから、それを行うことが可能です。

例えば、私(Gruntの開発者自身)のdefaults.jsonファイルはこのようになっています。これは、デフォルトの名前とは少し異なる名前の使用、自分のメールアドレスの除外、著作者URLの自動的指定を行いたいためです。

{
  "author_name": ""Cowboy" Ben Alman",
  "author_email": "none",
  "author_url": "http://benalman.com/"
}

組み込みプロンプトはドキュメント化されているため、ソースコードから、それらの名前とデフォルト値を探すことが可能です。

initテンプレートの定義

exports.description

この短いテンプレートの説明は、ユーザーがgrunt initまたは、grunt-initを実行して利用可能な全てのinitテンプレートの一覧が表示される際に、テンプレート名と一緒に表示されます。

exports.description = descriptionString;

exports.notes

指定された場合、この拡張された説明はプロンプトが表示される前に表示されます。これは、ユーザーに対して命名規則、プロンプトが必須か任意か、または、その他の説明をする手助けになります。

exports.notes = notesString;

exports.warnOn

もし、この任意(ですが、推奨)のワイルドカードパターン、またはワイルドカードパターンの配列にマッチすると、 Gruntは、ユーザーが--forceによって上書き可能な警告を発して中断します。これは存在するファイルをinitテンプレートが上書きしてしまうかもしれないようなケースで非常に便利です。

exports.warnOn = wildcardPattern;

最も一般的に知られている値'*'は、任意のファイルまたはディレクトリにマッチし、そのワイルドカードパターンは柔軟な記法を用いることが可能です。例えば、

exports.warnOn = 'Gruntfile.js';    // Gruntfile.jsを警告
exports.warnOn = '*.js';            // .jsファイルを警告
exports.warnOn = '*';               // ドット無しのファイル、またはドット無しのディレクトリを警告
exports.warnOn = '.*';              // ドット有りのファイル、またはドット有りのディレクトリを警告
exports.warnOn = '{.*,*}';          // ファイルまたはディレクトリを警告(ドット有り、無し)
exports.warnOn = '!*/**';           // ファイルを警告 (ディレクトリを無視)
exports.warnOn = '*.{png,gif,jpg}'; // 画像ファイルを警告

// これは最後の例の別の書き方です。
exports.warnOn = ['*.png', '*.gif', '*.jpg'];

exports.template

exportsプロパティはこの関数の外側で定義されていますが、実質的な全ての初期化コードは内側に指定されています。この関数は3つの引数を受け取ります。 grunt引数は、gruntを参照します。それは、全てのGruntのメソッドとライブラリを含みます。 init引数は、メソッドとこのinitテンプレートを指し示すプロパティを含むオブジェクトです。 done引数は、initテンプレートの実行が完了した際に呼び出されるべき関数です。

exports.template = function(grunt, init, done) {
  // "initテンプレートの内側"を参照してください。
};

initテンプレートの内部

init.addLicenseFiles

ファイルオブジェクトに適切な名前のライセンスファイルを追加します。

var files = {};
var licenses = ['MIT'];
init.addLicenseFiles(files, licenses);
// files === {'LICENSE-MIT': 'licenses/LICENSE-MIT'}

init.availableLicenses

利用可能なライセンスの配列を返します。

var licenses = init.availableLicenses();
// licenses === [ 'Apache-2.0', 'GPL-2.0', 'MIT', 'MPL-2.0' ]

init.copy

絶対、または相対のソース(source)パスと任意で相対の遷移先パスを与え、渡されたコールバックを介して任意の処理を行い、ファイルをコピーします。

init.copy(srcpath[, destpath], options)

init.copyAndProcess

ソースから遷移先へのファイルのコピー、内容の処理を渡されたオブジェクト内の全てのファイルに対して繰り返し処理します。(翻訳に自信無し)

init.copyAndProcess(files, props[, options])

init.defaults

defaults.jsonによるユーザー定義の初期値です。

init.defaults

init.destpath

遷移先の絶対パス。

init.destpath()

init.expand

grunt.file.expand と同じです。

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

init.expand([options, ] patterns)

init.filesToCopy

絶対ソースパスと相対遷移先パスにコピーするファイルを含むオブジェクトを返し、 rename.jsonが存在する場合、そのルールに従って名前を変更(または省略)します。

var files = init.filesToCopy(props);
/* files === { '.gitignore': 'template/root/.gitignore',
  '.jshintrc': 'template/root/.jshintrc',
  'Gruntfile.js': 'template/root/Gruntfile.js',
  'README.md': 'template/root/README.md',
  'test/test_test.js': 'template/root/test/name_test.js' } */

init.getFile

単一のタスクのファイルパスを取得します。

init.getFile(filepath[, ...])

init.getTemplates

利用可能な全てのテンプレートのオブジェクトを返します。

init.getTemplates()

init.initSearchDirs

initテンプレートを探すディレクトリの初期化を行います。templateは、テンプレートの場所です。また、~/.grunt-init/も含み、コアの初期化タスクはgrunt-init内にあります(翻訳に自信無し)

init.initSearchDirs([filename])

init.process

プロンプトの入力を求める処理を開始します。

  init.process(options, prompts, done)

init.process({}, [
  // これらの値のためのプロンプト
  init.prompt('name'),
  init.prompt('description'),
  init.prompt('version')
], function(err, props) {
  // 全てが完了した後に、プロパティを使って行いたいことを指定します
});

init.prompt

値の入力をユーザーに求めます。

init.prompt(name[, default])

init.prompts

全てのプロンプトのオブジェクトです。

var prompts = init.prompts;

init.readDefaults

タスクファイル(存在すれば)からjsonの初期値を読み込み、オブジェクトにマージします。

init.readDefaults(filepath[, ...])

init.renames

テンプレート用の名前変更ルールです。

var renames = init.renames;
// renames === { 'test/name_test.js': 'test/{%= name %}_test.js' }

init.searchDirs

テンプレートを検索するためのディレクトリの配列です。

var dirs = init.searchDirs;
/* dirs === [ '/Users/shama/.grunt-init',
  '/usr/local/lib/node_modules/grunt-init/templates' ] */

init.srcpath

ファイル名の初期化テンプレートのパスを検索し、絶対パスを返します。

init.srcpath(filepath[, ...])

init.userDir

ユーザーのテンプレートディレクトリへの絶対パスを返します。

var dir = init.userDir();
// dir === '/Users/shama/.grunt-init'

init.writePackageJSON

遷移先ディレクトリ内にpackage.jsonファイルを保存します。コールバック関数は、後処理としてプロパティを追加、削除、または他の何かしらの処理をするのに使用されます。

init.writePackageJSON(filename, props[, callback])

組み込みプロンプト

author_email

package.jsonで使用するための著者の電子メールアドレス。ユーザーのgitの設定ファイルからデフォルト値を検出しようとします。

author_name

package.jsonと著作権表示で使用する著者のフルネームです。ユーザーのgitの設定ファイルからデフォルト値を検出しようとします。

author_url

package.jsonで使用する著者のウェブサイトの公開されているURL。

bin

プロジェクトのルートからcliスクリプトへの相対パス。

bugs

プロジェクトの問題追跡用に公開されているURL。プロジェクトがgithubのリポジトリを持っている場合は、githubのものがデフォルトに設定されます。

description

プロジェクトの説明。 package.jsonおよびREADMEファイルで使用されます。

grunt_version

プロジェクトに必要なGruntの規定された有効なバージョン範囲。

homepage

プロジェクトの公開されているホームページのURLです。もしGithubリポジトリがあれば、GithubのURLを初期値にします。

jquery_version

もし、jQueryプロジェクトであれば、プロジェクトに必要なjQueryのバージョンです。規定された有効なバージョン範囲の指定で無ければいけません。

licenses

プロジェクトのライセンス。複数のライセンスは空白で区切ります。組み込みライセンスは、MIT、MPL-2.0、GPL-2.0、GPL-2.0で、 MITが初期値となっています。カスタムされたライセンスはinit.addLicenseFilesで追加します。

main

プロジェクトのmainエントリポイントです。初期値はlibフォルダ内のプロジェクト名になります。

name

プロジェクト名です。プロジェクトテンプレート全体で頻繁に使用されます。初期値は、現在の作業ディレクトリ名になります。

node_version

プロジェクトに必要なNode.jsのバージョン。規定された有効なバージョン範囲の指定で無ければいけません。

npm_test

プロジェクト上でテスト実行するコマンドです。初期値はgruntです。

repository

プロジェクトのgitリポジトリです。 GithubのURLから初期値が推測されます。

title

人が読むためのプロジェクト名。初期値は人が読みやすい名前に変えられたプロジェクト名になります。

version

プロジェクトのバージョンです。初期値は、最初の規定された有効な値である、0.1.0が割り当てられます。