amrita-altered

Warning.

(2009.1)
amrita-alteredは、過去のソフトウェアとの互換性のために置いています。新しいソフトウェアを開発する場合は、ERBなどを使うことをお奨めします。

AmritaはRuby用のHTML/XMLテンプレートエンジンです。その改造版を置いています。

Amritaとは

Amritaはテンプレートエンジンと呼ばれるものの一つです。Webアプリケーションなど、動的にHTMLデータを生成するプログラムで使います。

これまでは、HTMLにプログラムを埋め込んだり、逆にプログラムにHTMLデータを散りばめたりするものばかりで、どうしてもデザインとロジックが混ざってしまいました。テンプレートエンジンを使うと、HTMLデータとプログラムをほぼ完全に分離できます。

テンプレートエンジンは、あらかじめ何らかのマーク（目印）を付けておいたHTMLデータに、様々なデータを埋め込んでいきます。Amritaはほかのテンプレートエンジンと異なり、テンプレートがHTMLそのままです。

例えば、テンプレートであるHTMLデータとそのHTMLデータに値を埋め込むプログラムは、次のようになります。 

<p id="text">ここを置き換える</p>

require "amrita/template"
model = {:text => "はろーわーるど"}       # これがモデル（マッピング）データ
tmpl = Amrita::TemplateFile.new("sample.html")
tmpl.expand($stdout, model)

出力結果は次のとおりです。 

<p>はろーわーるど</p>

Amrita::Template#expand()に、出力先と、テンプレートに埋め込むデータを指すマッピングデータを渡します。

詳しい使い方は、基礎から学ぶWebデータベースプログラミング を参照してください。

なぜ改造版なのか

Amritaには、安定版であるバージョン1.0系列と開発版である1.8系列がありました。1.8系列は（初期設定のままで）属性値の置き換えができる、高速、などの特徴がありました。

拙著の基礎から学ぶWebデータベースプログラミングでも、属性値の置換をしたかったのと、開発版でもありバグがあっても早晩改修されるだろうと考えて、1.8系列を使っていました。

しかし、1.8系列の新版はいつになっても出てきません。いくつか看過できない重大なバグがあり、仕方ないので自分で直そうと思いましたが、内部が複雑怪奇でどのように手を付けたらいいか分かりませんでした。

そこで、1.8系列用に書かれたテンプレートとRubyスクリプトをAmrita 1.0系列でも動作するようにしました。

互換性について

amrita-alteredは、基本的にはバグ修正が中心であり、既存のプログラムが動作しなくなるような変更はしないつもりです。

■属性値の展開

属性値の展開方法がAmrita 1.0.xオリジナルとAmrita 1.8.xでは異なるのですが、amrita-alteredは、モードを切り替えることで、どちらを対象としたプログラムであってもそのまま動くようにしています。

Amrita 1.0.xオリジナルでは、HTMLタグの属性値を展開するには、Amrita::Template#expand_attr をtrueにする必要がありました。amrita-alteredは、この場合にAmrita 1.0.x互換モードで動作します。そうでないときはAmrita 1.8.xに合わせた動作になります。

デフォルトexpand_attr=true
Amrita 1.0
オリジナル 		属性値を展開しない。属性値を展開する。属性は要素と並列。
Amrita 1.8 展開する。属性は要素の子expand_attrがなく、エラーになる。
amrita-altered 展開する。属性は要素の子展開する。属性は要素と並列。

オリジナルのAmrita 1.0.2は、属性指定と要素指定とを並列に扱うため、要素の内容であるテキストと属性値の両方を置換するには、次のように書きます。なお、tid属性はAmritaでの置換対象を表します。 

<ul>
  <span tid="item"><li tid="text" style="@s">here is replaced</li></span>
</ul>

model = {
  :item => [
    {:s => "color:black", :text => "テキスト1"},
    {:s => "color:red", :text => "テキスト2"}
  ]
}
tmpl.amrita_id = "tid"
tmpl.expand_attr = true  # Amrita 1.0モード
tmpl.expand($stdout, model)

展開する前のHTMLデータは、HTMLとしてかなり不自然です。

Amrita 1.8.2およびamrita-alteredのデフォルトでは、HTMLデータを次のように書きます。モデルデータは上と同じです。 

<ul>
  <li tid="item" style="@s"><span tid="text">here is replaced</span></li>
</ul>

属性は、要素の子と考えるようになっています。

■XMLモード

Amritaのテンプレートは、HTMLデータかXMLデータです。テンプレートのパーサは、Template#xml=で切り替えます。これがfalse（デフォルト）のときはHTMLパーサを、trueのときはXMLパーサを使います。

XMLモードのときは、RDFなどHTML以外のデータも扱えるように、HTMLとしての妥当性検査は行いません。例えばhrという名前の要素であっても、内容を持つことができます。

xmlasxml動作
false（デフォルト）false（デフォルト）テンプレートはHTMLデータ。出力時にHTMLの妥当性検査を行う。
falsetrueテンプレートはHTMLデータ。出力時にHTMLの妥当性検査を行う。XHTMLとして出力。
true無視テンプレートはXMLデータ。出力はXMLスタイル。出力時に妥当性検査を省略。

■HTML要素を交互に展開

amrita-altered 1.1で導入した機能です。

表を出力するときに、次のように交互に色を変えたいことがあります。

ABC123
DEF456

オリジナルのamritaでは、style属性値をRubyソースに書く必要があり、またRubyソースが煩雑でした。amrita-alteredでは、次のようにテンプレートを書きます。id属性値の末尾に「+」を付けます。 

<table style="border:solid black 1px">
  <tr id="line+" style="background-color:white"><td id="x"><td id="y">
  <tr id="line+" style="background-color:#CCFFCC"><td id="x"><td id="y">
</table>

Rubyスクリプトは、次のようにします。 

model = {
  :line => [
    {:x => "ABC", :y => 123},
    {:x => "DEF", :y => 456},
    {:x => "GHI", :y => 789}
  ]
}
tmpl.expand(STDOUT, model)

出力は、次のようになります。（手で改行を入れています。） 

<table style="border:solid black 1px">
  <tr style="background-color:white">
    <td>ABC</td><td>123</td>
  </tr>
  <tr style="background-color:#CCFFCC">
    <td>DEF</td><td>456</td>
  </tr>
  <tr style="background-color:white">
    <td>GHI</td><td>789</td>
  </tr>
</table>

ライセンス

Ruby'sライセンスです。

ダウンロード

Trunk - HEAD

リリースされてない最新状態は, gitリポジトリから入手できます。 

$ git clone https://gitlab.com/netsphere/small-bag.git
$ git filter-branch --subdirectory-filter amrita-altered HEAD

次のページで, ソースコードを閲覧することもできます。

1.4.1 (2010.9.25)

主な変更点 Changes:
  • メンテナンスしていないams (AmritaScript), amx, template compilerを削除。
  • 多くのテストケースにパスするようにした。
ファイル Download:
amrita-altered-1.4.1.tar.gz

1.4.0 (2006.10.8)

主な変更点 Changes:
Ruby 1.8.5で、汚染された文字列をinternするとSecurityErrorになるようになった。これに対応するため、内部でkeyをSymbolにするのを止め、文字列のまま保持するようにした。機能の追加、変更はなし。
ファイル Download:
amrita-altered-1.4.0.tar.gz
日付
2005.10.10
内容
  • 置換すべき属性が2つ以上ある場合に置換されないバグを修正した。（v1.3で混入。）
ファイル
amrita-altered-1.3.1.tar.gz
日付
2005.9.23
内容
  • HTML要素を交互に展開させる場合に、テンプレートのHTML要素の間に空白があっても適用するようにした。
  • 開始タグの属性の順序を保存するようにした。
ファイル
amrita-altered-1.3.tar.gz バグが混入していたため、バージョン1.3.1を使ってください。
日付
2005.6.26
内容
  • マイナな修正。オリジナル版との互換性の向上
ファイル
amrita-altered-1.2.tar.gz
日付
2005.6.12
内容
  • テンプレートのHTML要素を交互に展開する機能を追加した。
ファイル
amrita-altered-1.1.tar.gz, amrita-testsuite-20050612.tar.gz

以下は、すべてオリジナル版へのパッチになっています。

オリジナル版；amrita-1.0.2.tar.gz (ローカルコピー)

日付
2005.4.29
内容
  • XMLモード（Amrita::Template#xmlが真）のときは、空要素タグおよびURL属性値のチェックを省略する。
    XMLモードでhrやimgという名前の要素に内容を持たせることができなくなっていた。このバグはq2パッチでの修正でXMLモードを考慮していなかったために発生。
パッチ
amrita-1.0.2-q9.diff
日付
2005.4.16
内容
  • Amrita 1.0.2オリジナル互換モードとAmrita 1.8/alteredモードを切り替えるようにした。
  • Ruby 1.8で警告が出る点をさらに修正
  • use_compilerを無視するようにした。
パッチ
amrita-1.0.2-q8.diff
日付
2005.4.10
内容
  • XMLParserでXML処理命令 (PI)、コメント、CDATAが消えてしまう点を修正した。
  • Ruby 1.8で警告が出る点を修正
パッチ
amrita-1.0.2-q7.diff, amrita-test-suite-20050410.tar.gz
日付
2004.03.20
内容
  • テンプレートの属性値置換指定が残ってしまうことがあった点を修正した。q5パッチの修正方法は正しくなかった。
パッチ
amrita-1.0.2-q6.diff
日付
2003.12.17
内容
  • Ruby 1.8.1でXMLParserを使うとエラーになる（らしい）点を修正した。
パッチ
amrita-1.0.2-q4.diff
日付
2003.11.01
内容
  • Amrita::NodeArray#to_a()が正しく動かなかったので、each()を追加した。
  • 終了タグを省略できるHTML 4.01要素すべてについて、通常の文書で、要素の親子関係が正しくなるようにした。
パッチ
amrita-1.0.2-q3.diff
テストケース集
amrita-tests-20031101.tar.gz
日付
2003.10.26
内容
  • inputなど空要素の終了タグが出力される点を修正。
  • textareaなど空要素ではない要素で、終了タグが出力されないことがある点を修正
  • trの終了タグを省略したときに、次のtr要素がtd要素の子になる点を修正。
  • 属性値の置換を有効にした。属性値を'@foo'とする方法で、Amrita v1.8.2と互換。
  • 要素名、属性名をXML互換に近づけた。要素名、属性名に「:」を含められるようにした。
パッチ
amrita-1.0.2-q2.diff

外部リンク

Amrita Homepage
オリジナル版のWebサイト