Guetamale Template Framework

Version 0.5.2

2005.06.13

NISHIMOTO Keisuke

1 概要

Webアプリケーションやソースの自動生成など，テキスト生成をする機会は世の中にたくさんあります．java.io.Writerなどで直接テキストを書き出せば目的を達成できますが，この場合，プログラムソースと文書が混在してしまい，可読性やメンテナンスが低下してしまいます．

この場合は，元となるテンプレートテキストと，プログラムを分離して管理した方が何かと便利です．

それらのテキスト生成を，テンプレートとコンテキスト(文脈)によって生成する仕組みをこのフレームワークでは提供します．

2 仕様

2.1 動作環境

以下の環境を前提にしています。

表1.動作環境

SDK Java 2 SDK 1.2 以上

OS Windows, Linux など上記 SDK が動作する OS

表1.動作環境
SDK	Java 2 SDK 1.2 以上
OS	Windows, Linux など上記 SDK が動作する OS

全環境を試していないので、動作しない環境があるかもしれません。

2.2 機能

構成と内容

テンプレートファイル: テキスト生成の元となるテンプレート(型)
TemplateDocumenParser: テンプレートを内部オブジェクト(TemplateDocument)に変換するParser
TemplateDocument: テキスト書き出しをする内部オブジェクトで，TemplateContextと組みで動作する
TemplateContext: テンプレートに挿入する文書要素(リソース)を提供する
目的のテキスト: 目的とするテキストファイルまたはストリーム．TemplateContextによってこの内容は動的に変わる

基本機能

表2.主な機能

部機能備考

テンプレート(ファイル) 文書要素の挿入コンテキストリソースの値を挿入できます。

テキスト分岐(真偽) コンテキストリソースの値が"true"または"false"の時に、文書要素を差し替えることができます。

テキスト分岐(ケース) コンテキストリソースの値を条件として，文書要素を差し替えることができます。

テキストの繰り返しコンテキストリソースの値が，"true"である間、文書要素の繰り返しができます。

コンテキスト(TemplateContext) 挿入要素のマッピングそのコンテキストによって格納されたリソースの値を、挿入要素として返します．リソースの値は，Propertiesなどの固定的なものやコンテキスト内で動的に作られた値等を返せます．

表2.主な機能
部	機能	備考
テンプレート(ファイル)	文書要素の挿入	コンテキストリソースの値を挿入できます。
テキスト分岐(真偽)	コンテキストリソースの値が"true"または"false"の時に、文書要素を差し替えることができます。
テキスト分岐(ケース)	コンテキストリソースの値を条件として，文書要素を差し替えることができます。
テキストの繰り返し	コンテキストリソースの値が，"true"である間、文書要素の繰り返しができます。
コンテキスト(TemplateContext)	挿入要素のマッピング	そのコンテキストによって格納されたリソースの値を、挿入要素として返します．リソースの値は，Propertiesなどの固定的なものやコンテキスト内で動的に作られた値等を返せます．

2.3 インストール

lib/guatemala.jar, lib/lex.jar を環境変数 CLASSPATH などに通してください。

2 ダウンロード

以下のページからダウンロードできます。

http://cappuccino.jp/keisuken/java/guatemala/guatemala-0.5.2.tar.gz

3 ライセンス

ライセンス

使用に関しては、MIT license に準じています。
商用・非商用に限らずご使用していただけます。
西本圭佑は本ソフトウェアの品質についていかなる保証も行っておらず、本ソフトウェアの欠陥及びそれによって発生した損失や損害については一切責任を負いません。

4 連絡先

質問や要望などがありましたら keisuken atmark cappuccino.ne.jp まで内容を書いてお送りください。

Appendix

A1 APIリファレンス

APIリファレンス

A2 テンプレートファイル仕様

文法

TAG_NORMAL           ::= '%%'
TAG_TRIM_SPACE       ::= '!!'
TAG_TRIM_LINE        ::= '##'
TAG_TRIM_WHITE_SPACE ::= '@@'
TAG_DESC ::= (TAG_NORMAL | TAG_TRIM_SPACE | TAG_TRIM_LINE | TAG_TRIM_WHITE_SPACE)
TAG_SEPARATOR ::= ':'
LABEL ::= Character.isJavaIdentifierStart Character.isJavaIdentifierPart*
VALUE ::= '"' [^"] '"' | Character.isJavaIdentifierPart*
TAG ::= TAG_DESC LABEL (':' (LABEL | VALUE))? TAG_DESC

インクルード

構文: %%include:"{パス}"%%
例: %%include:"foo/bar.tpl"%%

構文: %%-コメント-%%
例: %%- ここからユーザーリストの出力 -%%

繰り返し

構文: %%while:{リソース名}%% {文} %%endwhile%%
例: %%while:userList%%
ID: %%id%%, Name: %%name%%
%%endwhile%%

if 分岐

構文: %%if:{リソース名}%% {真時の文} %%else%% {偽時の文} %%endif%%
例: %%if:isMember%%
あなたはメンバーです。
%%else%%
あなたはメンバーではありません。
%%endif%%

switch 分岐

構文: %%switch:{リソース名}%% %%case:{ケース名}%% {文} %%endcase%% %%default%% {文} %%enddefault%% %%endswitch%%
例: %%switch:memberType%%
  %%case:admin%%管理者%%endcase%%
  %%case:guest%%ゲスト%%endcase%%
  %%default%%メンバー%%enddefault%%
%%endswitch%%

トリミング

構文

テンプレート要素タグは、前後のシグネチャにより前後の文字列をトリミングできます。

表1.タグシグネチャとトリミング
タグシグネチャ	トリミング
%%	なし
!!	改行までのスペースを取り除く
##	改行までのスペースと1行分の改行を取り除く
@@	改行, スペースを取り除く

例

表2.トリミングによる実行例
右側		左側
テンプレート	出力	テンプレート	出力
abc __%%foo%%__ def	abc __{foo}__ def	abc __%%foo%%__ def	abc __{foo}__ def
abc __!!foo%%__ def	abc {foo}__ def	abc __%%foo!!__ def	abc __{foo} def
abc __##foo%%__ def	abc {foo}__ def	abc __%%foo##__ def	abc __{foo} def
abc __@@foo%%__ def	abc{foo}__ def	abc __%%foo@@__ def	abc __{foo}def

注釈: '_': スペース, "{foo}": 挿入される文字列

A3 サンプル1 (Hello, world)

実行結果

Hello, world!

テンプレート

%%message%%

コンテキスト設定ファイル

context.class=HelloWorldContext
message=Hello, world!

コンテキストクラス

public class HelloWorldContext implements TemplateContext {

  private Map elements;

  pubilic void init(Properties config) {
    elements = config;
  }

  public Object getElement(String name) {
    return elements.get(name);
  }
}

A4 サンプル (時刻表示)

実行結果

こんにちは
ただ今2005/05/06 15:05です。

テンプレート

%%switch:time%%
%%case:"goodmorning"%% %%goodmorning%% %%endcase%%
%%case:"goodafternoon"%% %%goodafternoon%% %%endcase%%
%%case:"goodevening"%% %%goodevening%% %%endcase%%
%%endswitch%%
ただ今%%date%%です。

コンテキスト設定ファイル

context.class=DateContext
goodmorning=おはようございます
goodafternoon=こんにちは
goodeveninig=こんばんは
message=Hello, world!

コンテキストクラス

public class HelloWorldContext implements TemplateContext {

  private Map elements;
  private Calendar calendar = Calendar.getInstance();
  private Date date = new Date();
  private DateFormat dateFormat = new SimpleDateFormat("yyyy/MM/dd HH:mm");

  pubilic void init(Properties config) {
    elements = config;
    Calendar calendar = Calendar
    elements.put("date", new Object() {
      public String toString() {
        return dateFormat.format(date);
      }
    });
    elements.put("time", new Object() {
      public String toString() {
        calendar.setTime(date);
        int hour = calendar.get(Calendar.HOUR_OF_DAY);
        if(hour >= 4 && hour < 10) {
          return "goodmorning";
        } else if(hour >= 10 && hour < 17) {
          return "goodafternoon";
        } else {
          return "goodevening";
        }
      }
    });
  }

  public Object getElement(String name) {
    return elements.get(name);
  }
}

A5 サンプル (シンプルループ)

実行結果

テンプレート

%%while:loop%%
%%i%%
%%endwhile%%

コンテキスト設定ファイル

context.class=SimpleLoopContext
start=1
end=10

コンテキストクラス

public class SimpleLoopContext implements TemplateContext {

  private Map elements;
  private int start;
  private int end;
  private int i;

  pubilic void init(Properties config) {
    elements = config;
    start = getIntProperty("start") - 1;
    end = getIntProperty("end");
    elements.put("i", new Object() {
      public String toString() {
        return Integer.toString(i);
      }
    });
    elements.put("loop", new Object() {
      public String toString() {
        i++;
        return new Boolean(i <= end);
      }
    });
  }

  public Object getElement(String name) {
    return elements.get(name);
  }

  private int getIntProperty(String name) {
    try {
      String value = elements.get(name).trim();
      return Integer.parseInt(value);
    } catch(Exception e) {
      return 0;
    }
  }
}

A6 サンプル (テンプレートの生成とドキュメントの生成)

// Configファイル読み込み
Properties config = new Properties();
FileInputStream configIn = null;
try {
  configIn = new FileInputStream("hello.props");
  config.load(configIn);
} catch(IOException e) {
  ...
} finally {
  if(configIn != null) {
    configIn.close();
  }
}

// TemplateDocumentFactory生成
TemplateDocument document = null;
try {
  document = TemplateDocumentParser.parse("hello.tpl");
} catch(TemplateException e) {
  ...
} catch(IOException e) {
  ...
}

// 必要なContextを設定
Properties configInstance = (Properties)config.clone();
configInstance.put(..., ...);

// Document生成
FileWriter writer = null;
try {
  writer = new FileWriter("hello.txt");
  document.write(configInstance, writer);
} catch(IOException e) {
  ...
} finally {
  if(writer != null) {
    writer.close();
  }
}

A7.履歴

0.5.2, 2005.06.13
- テンプレート文法エラーの付近を例外メッセージとして返すようにした
0.5.1, 2005.05.27 -
- $&()*+,./;<=>?[]^_{|}~ JavaIdentifierPart などの文字列をタグ名・タグパラメータ名に使えるようにした．
  - %%".foo.bar"%% -> %%.foo.bar%%
0.5.0, 2005.05.26 -
- 複雑な仕様を全てカット
- リソース形式のTemplateContextと，それを使用してテキストを書き出すTemplateDocumentの二本柱とした
- タグによるテキスト整形の仕様はそのまま
- Lexを使用した新しいParser
- 全てはTemplateContext次第．TemplateContextを継承して必要な機能を組み込めば別のシステムを作ることも可能．
0.4.1, 2003.04.25 -
- HTMLEntityFilter の追加
0.4.0, 2003.03.04 -
- Context において、repeat タグを廃止し、element タグで代価させた
- GuatemalaServlet において HttpServletRequest で得られるパラメータをデフォルトエンコードに変換するようにした
- MultipartFormData を HttpServletRequest を継承させた
0.3.0, 2002.09.10 -
- TemplateContextFactory で、TemplateConfig の情報をリソース要素と返す時に null だった場合、NullPointerException が発生する不具合を修正
- TemplateFilter を追加した (利用例 XML Entity の変換など)
- GuatemalaServlet
  - それぞれの TemplateDocument/Context に Request encode, Template encode, Response encode を設定できるようにした
  - 例外発生時にレスポンスで返すメッセージはセキュリティ上問題ない必要最低限の情報に限定した
  - 例外などの情報の詳細をログに残すようにした
  - テンプレートやコンテキストファイルがなかった場合 404 Not Found を送出するようにした
0.2.3, 2002.09.06 - TemplateBean の init メソッドで初期化しないバグ修正
0.2.2, 2002.09.02 - テンプレート部で字句解析後、バッファをクリアしていなかったためメモリを消費していたので、解析ごとにバッファクリアするようにした
0.2.1, 2002.09.02 - テンプレート部 switch 内で include できないバグ修正
0.2.0, 2002.08.27 - コンテキスト部で if, switch 分岐の operator を廃止し、リソースから得る様に簡略化
0.1.0, 2002.08.10 - 基本機能実装完了
0.0.0, 2001.03.01 - 作成し始める

A5.ToDo

ドキュメント不足の解消
エラーメッセージの整理
Parsing 効率の向上
メモリ消費量を少なくする
サニタイジングのサポート

Guetamale Template Framework

1 概要

2 仕様

2.1 動作環境

2.2 機能

構成と内容

基本機能

2.3 インストール

2 ダウンロード

3 ライセンス

4 連絡先

Appendix

A1 APIリファレンス

A2 テンプレートファイル仕様

文法

インクルード

コメント

繰り返し

if 分岐

switch 分岐

トリミング

A3 サンプル1 (Hello, world)

実行結果

テンプレート

コンテキスト設定ファイル

コンテキストクラス

A4 サンプル (時刻表示)

実行結果

テンプレート

コンテキスト設定ファイル

コンテキストクラス

A5 サンプル (シンプルループ)

実行結果

テンプレート

コンテキスト設定ファイル

コンテキストクラス

A6 サンプル (テンプレートの生成とドキュメントの生成)

A7.履歴

A5.ToDo