import "template"

HTMLなどのテキスト出力を生成するためのデータ駆動型テンプレートです。

テンプレートは、データ構造を適用することで実行されます。テンプレート内のアノテーションはデータ構造内の要素(一般的に、構造体のフィールドまたはマップ内のキー)を参照し、実行の制御や出力値の取り出しを行います。実行の際、テンプレートはデータ構造内を移動します。「カーソル」@は、構造体内のカレント位置にある値を表します。

データアイテムは、値もしくはポインタ(自動的にポインタの先を参照します)です。

「field」は、次に示すデータのいずれかに一致します。

- 構造体のフィールド名(result = data.field)
- そのキーでマップに格納されている値(result = data[field])
- その名前を持つ、引数を持たず、値をひとつだけ返すメソッドからの戻り値
  (result = data.field())

主な構成体({}はメタキャラクタ、[]は、オプション要素のマーカー):

{# comment }

これは一行コメントです。

{.section field} XXX [ {.or} YYY ] {.end}

このフィールドの値を@にセットします。@がデータの同じ場所にとどまるよう指定します。フィールドがnilまたは空のときはYYYが実行され、それ以外はXXXが実行されます。

{.repeated section field} XXX [ {.alternates with} ZZZ ] [ {.or} YYY ] {.end}

.sectionと同じですが、フィールドは配列またはスライスのどちらかです。XXXは各要素に対して実行されます。配列がnilまたは空のときはYYYが代わりに実行されます。{.alternates with}マーカーが指定されているときは、XXXとZZZが交互に実行されます。

{field}
{field1 field2 ...}
{field|formatter}
{field1 field2...|formatter}

フィールドの値を出力に挿入します。各フィールドはまず.sectionと.repeatedでセットしたカーソルから検索します。そこでみつからないときは、外側のセクションを順次最上位に達するまで検索します。

formatterが指定されているときは、テンプレートのセットアップルーチンに渡されたフォーマッタマップ、もしくはデフォルトセット(“html”,”str”,”")内の該当フォーマッタを使ってデータを出力します。フォーマッタ関数は次のシグネチャを持ちます。

func(wr io.Writer, formatter string, data ...interface{})

wrは出力先で、dataは具体的なフィールドの値を保持し、formatterは呼び出す側で指定したフォーマッタの名前です。デフォルトのフォーマッタでは、各フィールドの文字列表現を連結するだけです。

パッケージファイル

format.go template.go

HTMLEscape関数

func HTMLEscape(w io.Writer, s []byte)

HTMLEscapeは、プレーンテキストデータsと等価である、正しくエスケープされたHTMLをwに書き込みます。

HTMLFormatter関数

func HTMLFormatter(w io.Writer, format string, value ...interface{})

HTMLFormatterは、任意の値をHTMLとしてフォーマットします。

StringFormatter関数

func StringFormatter(w io.Writer, format string, value ...interface{})

StringFormatterは、デフォルトの文字列表現にフォーマットします。この関数は”str”という名前で登録されるほか、デフォルトフォーマッタとしても登録されます。独自のカスタムフォーマッタマップに、”"という名前で登録することにより、このデフォルトフォーマッタを上書きすることが可能です。

Error型

Errorsは、解析および実行中に返されたエラーです。必要に応じてユーザ側で情報を取り出したり、再フォーマットしてください。

type Error struct {
    Line int
    Msg  string
}

(*Error) String関数

func (e *Error) String() string

FormatterMap型

FormatterMapは、フォーマッタの名前と、それを実装している関数のマッピングを格納する型です。

type FormatterMap map[string]func(io.Writer, string, ...interface{})

Template型

Templateは、テンプレートの定義を表す型です。解析後も内容は変化しません。

type Template struct {
    // contains unexported fields
}

MustParse関数

func MustParse(s string, fmap FormatterMap) *Template

MustParseは、Parseと同じですが、テンプレートが解析できなかったときpanicを起こします。

MustParseFile関数

func MustParseFile(filename string, fmap FormatterMap) *Template

MustParseFileは、ParseFileと同じですが、ファイルが読み込めなかったかテンプレートが解析できなかったときにpanicを起こします。

New関数

func New(fmap FormatterMap) *Template

Newは、変数をフォーマットするための関数を定義したフォーマッタマップ(nil指定可能)を伴なう、新しいテンプレートを作成します。

Parse関数

func Parse(s string, fmap FormatterMap) (t *Template, err os.Error)

Parseは、デフォルトパラメータ({}メタキャラクタなど)をもつテンプレートを作成します。文字列sはテンプレートのテキストです。フォーマッタマップfmapはnil指定が可能で、変数をフォーマットするための関数を定義したものです。この関数はテンプレートを返します。エラーが発生したときは、errにnil以外の値が返ります。

ParseFile関数

func ParseFile(filename string, fmap FormatterMap) (t *Template, err os.Error)

ParseFileは、デフォルトパラメータ({}メタキャラクタなど)でテンプレートを作成するラッパー関数です。filenameは、テンプレートテキストが記述されているファイルです。フォーマッタマップfmapはnil指定が可能で、変数をフォーマットするための関数を定義したものです。この関数はテンプレートを返します。エラーが発生したときは、errにnil以外の値が返ります。

(*Template) Execute関数

func (t *Template) Execute(data interface{}, wr io.Writer) (err os.Error)

Executeは、解析済みテンプレートに指定したデータオブジェクトを適用し、生成した出力をwrに書き込みます。

(*Template) Parse関数

func (t *Template) Parse(s string) (err os.Error)

Parseは、指定したテンプレートテキストを使ってテンプレートを初期化します。文字列sはテンプレートのテキストです。エラーが発生したときは、そのエラーを返します。

(*Template) ParseFile関数

func (t *Template) ParseFile(filename string) (err os.Error)

ParseFileは、Parseと同じですが、指定した名前のファイルからテンプレートの定義を読み込みます。

(*Template) SetDelims関数

func (t *Template) SetDelims(left, right string)

SetDelimsは、テンプレート操作に使う左右のデリミタ(メタキャラクタ)をセットします。これらは解析中に使われます。ここでデリミタの処理をしてもよかったのですが、ルーチンをシンプルに保つほうがよりよいと判断しました。またデリミタは、非常にまれですがエラーを引き起こします。Parseはすでに必要なエラーハンドリングインタフェースを持っているのもこのようにした理由です。