使い方

前提条件
概要
変換処理の流れ
変換資材
変換スクリプト

前提条件

　yakumoに用意された変換資材 fyakumo, thtmlによりテキストファイルを HTMＬへ変換するときの前提条件を以下に示します。

変換対象の文字コードは UTF-8、改行コードは LFで記述してください。
xxx.txtを xxx.htmlに変換します。
厳密には以下の条件となります。
- 変換対象と変換結果が一対一であること。
- 変換対象キー＋拡張子 txtが変換対象ファイル名となること。
- 変換結果キー＋拡張子 htmlが変換結果ファイル名となること。

概要

　yakumoは独自の記法で記述されたテキストを、いったんbltxt文書に変換してから構造化し、目的の形式へ変換します。
　テキストを直接 bltxt記法で記述しても構いません。しかし bltxt記法を記述するのは煩雑です。このため、いわゆる糖衣構文で記述し、それを bltxt記法へ変換するという過程を経ます。

変換スクリプト: 変換する対象、変換結果の出力先などを定義するスクリプトです。; 利用者が必ず準備する必要があります。
変換資材: テキストから bltxt文書へ、bltxt文書から目的の形式へ変換するための各種資材をまとめたものです。; yakumo記法から bltxt文書へ変換するサンプル資材があります。yakumo記法を参照してください。; yakumo記法から bltxt文書へ変換された後、HTML5へ変換するサンプル資材があります。HTML化を参照してください。

変換処理の流れ

　yakumoは以下の工程で、特定の記法に従うテキストを目的の形式へ変換します。

変換対象を解析します。
1. 変換対象のテキストをbltxt文書に整形します。
  - switemスクリプトを用いてテキストをbltxt文書に整形します。
    - switemについては switem を参照してください。
2. bltxt文書を解析します。
  - bltxt文書はXMLに似た、タグを用いて階層関係を表現した文書です。
    - bltxt文書については bltxt を参照してください。
変換結果を整形します。
- すべての clmapの宣言に大域変数としてログ出力子 "fprint"を設定します。
- clmapスクリプトから以下のクロージャを変換結果毎に並列して呼びます。
  clmapスクリプトについては clmap を参照してください。
  1. 事前準備をします。省略可です。
    - 変換資材にて設定された事前準備のためのクロージャを呼びます。
    - 変換資材ごとに、設定がされていれば一回のみ呼びます。
    - 引数は以下のとおりです。
      - 第一引数として変換対象キーとBLtxtインスタンスとのマップを渡します。
      - 第二引数として変換スクリプトのインスタンス(ConvertScript)を渡します。
    - 戻り値として補足情報のマップを返してください。
  2. テンプレートに適用するバインド変数を取得します。
    - 最上位にある無名のクロージャを呼びます。
    - 変換結果毎に並列して呼びます。
    - 引数は以下のとおりです。
      - 第一引数として変換結果キーを渡します。
      - 第二引数として変換対象キーとBLtxtインスタンスとのマップを渡します。
      - 第三引数として補足情報のマップを渡します。
        補足情報は以下をマージしたものとなります。
        
        変換スクリプトで指定されたもの
        
        事前準備のクロージャの実行結果（変換資材と紐づくもののみ）
    - 戻り値としてテンプレートに適用するバインド変数のマップを返してください。
- 上記のクロージャ実行後、テンプレートにバインド変数を適用して出力します。
関連ファイルを出力します。省略可です。
- 関連ファイルとは、変換結果に併せて出力が必要な静的ファイルです。
- たとえば HTMLへの変換であれば CSSファイルや JavaScriptファイルなどが相当します。

変換資材

　変換に必要な各種資材をまとめたものが変換資材です。
　変換資材は資材スクリプトで定義します。

　資材スクリプトのファイル名は「material.groovy」固定です。
　委任クラスは Yakumo です。

　変換資材の作成の仕方として、以下の二種類があります。

クラスパス上にリソースとして作成する場合
ファイルとして作成する場合

　変換資材名は、資材スクリプトを格納しているフォルダ名あるいはフォルダへのパスです。
　慣例として、bltxt記法へ変換する資材は先頭一文字を"f"(from)にしてください。
　bltxt文書を目的の記法へ変換するための資材ならば先頭一文字を"t"(to)にしてください。

　資材スクリプトは以下の記述から構成されます。

loadメソッド: 前提として必要な変換資材を宣言します。
materialメソッド: この変換資材を構成するファイルへのパスを定義します。

バインド変数

　資材スクリプトでは以下のバインド変数を利用できます。

convName: 変換資材名。変換資材がリソースの場合のみ。
convDir: 資材スクリプト格納フォルダ（java.io.File）。変換資材がフォルダの場合のみ。

loadメソッド

　Yakumo#loadメソッドに渡すクロージャで、必要な他の変換資材を読みこみます。
　クロージャ内では以下のメソッドを使用できます。委任クラスは MaterialLoader です。

material: 利用する他の変換資材を設定します。

materialメソッド

　変換資材は、以下のうち最低ひとつのファイルから構成されます。

switemスクリプト
clmapスクリプト
テンプレートファイル

　Yakumo#materialメソッドに渡すクロージャで、変換資材を設定します。
　クロージャ内では以下のメソッドを使用できます。委任クラスは ConvertMaterial です。

switem: switemスクリプトを設定します。
clmap: clmapスクリプトを設定します。
clmapProp: クロージャマップに共通の大域変数をバインドします。
template: テンプレートを設定します。

変換スクリプト

　変換のために実行するのが変換スクリプトです。
　利用する変換資材を定義したり、変換後に実行する処理を記述したりします。
　Groovy DSLのため、Groovyスクリプトとして処理を記述できます。
　委任クラスは Yakumo です。

　変換スクリプトは以下の記述から構成されます。

loadメソッド: 前提として必要な変換資材を宣言します。; これは資材スクリプトと同じです。
scriptメソッド: 変換対象、変換結果といった変換に必要な各種設定や処理を記述します。
relatedメソッド: 関連ファイルのコピーに関する設定をします。

バインド変数

　変換スクリプトでは以下のバインド変数を利用できます。
　Yakumo#runメソッドに引数 varsで渡した変数名、変数値もバインドされます。

scriptFile: 変換スクリプトファイル（java.io.File）

scriptメソッド

　Yakumo#scriptメソッドに渡すクロージャで、変換スクリプトを設定します。
　クロージャ内では以下のメソッドを使用できます。委任クラスは ConvertScript です。

targets: 変換対象について設定するためのクロージャを渡します。; 委任クラスは ConvertTargets です。
results: 変換結果について設定するためのクロージャを渡します。; 委任クラスは ConvertResults です。
append: 補足情報を設定します。
doFirst: 解析前に実行する処理を設定します。
doBetween: 解析後、整形前に実行する処理を設定します。; 引数として変換対象キーとBLtxtインスタンスとのマップを渡します。
doLast: 整形および関連ファイルのコピー後に実行する処理を設定します。

relatedメソッド

　関連ファイルとは、変換結果に併せて出力が必要な静的ファイルです。

　Yakumo#relatedメソッドに渡すクロージャで、関連ファイルを設定します。
　関連ファイルは資材スクリプト、変換スクリプトどちらでも設定できます。

　クロージャ内では以下のメソッドを使用できます。委任クラスは RelatedSources です。

outDir: 関連ファイルの出力ディレクトリを設定します。
copyMode: 関連ファイルのコピーモードを設定します。
source: 関連ファイルを設定します。
removeSet: セット名に対応する関連ファイルをすべてコピー対象から除外します。; 利用する変換資材が設定した関連ファイルをコピーしたくない場合に利用してください。