このドキュメントの内容
.NET Framework 用のテキストテンプレートエンジン NVelocity の簡単な使い方を説明します。
NVelocity
Java のテキストテンプレートエンジンVelocityの .NET 移植版です。
SOURCEFORGE にあるものは 0.4.1 を最後に開発が停止しており、現在は Castle Project に移管されているようです。残念ながら活発に開発が継続されているようではありませんが…。
【SOURCEFORGE】
【Castle Project】projects
【NuGet】NVelocity
ここには NVelocity に関する情報はほとんどありません。Other Projects の欄に GitHub へのリンクがありますが、リファレンスなどを見つけることはできませんでした。機能的にはほぼVelocityと同じですので、Velocityのリファレンスを参照するとよいです。
実行時にテンプレートファイルを外部から読み込んでテキストを生成するアプリケーションを簡単に作ることができます。.NET Framework 用のテキストテンプレートエンジンといえばT4が最も有名ですが、事実上 VisualStudio 専用と言えるT4との使い分けができると思います。
テキストの生成方法
- コンテキストに変数と値を格納します。
- テンプレートファイルパスとコンテキストを指定してテキストを生成します。
// 初期処理
NVelocity.App.Velocity.Init();
// コンテキストを生成する
NVelocity.VelocityContext context = new NVelocity.VelocityContext();
// 変数と値の組み合わせを格納する
context.Put("name", "あいうえお");
// テンプレートファイルを指定してテキストを生成する
StringBuilder sb = new StringBuilder();
using (StringWriter writer = new StringWriter(sb))
{
NVelocity.App.Velocity.MergeTemplate("test.vm", "shift-jis", context, writer);
}
Debug.WriteLine(sb.ToString());
テンプレートの構文
変数による値の置き換え
変数名の前に $ をつけます。
名前:$name
context.Put("name", "あいうえお")
名前:あいうえお
大文字小文字は区別されます。変換は行われず、そのまま出力されます。
名前:$Name
context.Put("name", "あいうえお")
名前:$Name // 変換されない
変数名に使用できる文字は a～z A～Z 0-9 _ - です。
このうち先頭の文字として使用できるのは a～z A～Z _ です。
名前:$_name1
名前:$-name1
名前:$1name
context.Put("_name1", "あいうえお")
context.Put("-name1", "あいうえお")
context.Put("1name", "あいうえお")
名前:あいうえお
名前:$-name // 変換されない
名前:$1name // 変換されない
変数名は {} で囲むことを推奨します。どこまでが変数名であるかがわかりやすくなります。なお、変数名のすぐ後ろに a～z A～Z 0-9 _ - が続く場合は {} で囲まないと正しく変数名が認識されません。
名前:<$name>
名前:-$name-
名前:-${name}-
context.Put("name", "あいうえお")
名前:<あいうえお>
名前:-$name- // 変換されない
名前:-あいうえお-
$ と変数名の間に ! を付加すると、コンテキストで値が指定されなかった、または null が指定されたときに "" に変換されます。
名前:<$unknown_name>
名前:<$!unknown_name>
名前:<$!{unknown_name}>
context.Put("name", "あいうえお")
名前:<$unknown_name>
名前:<>
名前:<>
変数のメンバの呼び出し
変数に指定した値の型に定義されているプロパティやメソッドを呼び出すことができます。メンバ名の大文字小文字は区別されないようです。
名前の長さ：${name.Length}
名前の長さ：${name.length}
名前の先頭2文字：${name.SubString(0,2)}
context.Put("name", "あいうえお")
名前の長さ：5
名前の長さ：5
名前の先頭2文字：あい
if 構文
C# の if とほぼ同じです。
-1-
#if ($name.SubString(0,1) == "あ")
"あ"で始まる
#end
-2-
#if ($name.SubString(0,1) == "か")
"か"で始まる
#end
-3-
#if ($name.SubString(0,1) == "さ")
"さ"で始まる
#elseif ($name.SubString(0,1) == "あ")
"あ"で始まる
#else
不一致
#end
-4-
context.Put("name", "あいうえお")
-1-
"あ"で始まる
-2-
-3-
"あ"で始まる
-4-
foreach 構文
C# の for each とほぼ同じです。
$velocityCount でループカウンタの値を取得することができます。1 オリジンです。
0 オリジンのカウンタが必要である場合、set 構文を用いて演算した結果を出力します。
#foreach ($c in ${name})
[${velocityCount}] ${c}
#end
#set ($i=0)
#foreach ($c in ${name})
#set ($i=${velocityCount} - 1)
[${i}] ${c}
#end
context.Put("name", "あいうえお")
[1] あ
[2] い
[3] う
[4] え
[5] お
[0] あ
[1] い
[2] う
[3] え
[4] お
カウンタ変数を用いた for ループを行いたい場合、配列を使用して次のように記述します。[0..4] は 0 ～ 4 の配列を表します。
#foreach ($i in [0..4])
[${i}]
#end
[0]
[1]
[2]
[3]
[4]
コメント
単一行コメントは ## です。
複数行コメントは #* *# で囲みます。
## 単一行コメント
あいうえお ## 文末コメント
#*
複数行コメント
複数行コメント
*#
あいうえお #* 文中コメント *# かきくけこ
あいうえお
あいうえお かきくけこ