github.com/shogo82148/std@v1.22.1-0.20240327122250-4e474527810c/text/template/doc.go

// Copyright 2011 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

/*
パッケージtemplateは、テキスト出力を生成するためのデータ駆動型テンプレートを実装します。

HTML出力を生成するには、[html/template] を参照してください。
これはこのパッケージと同じインターフェースを持ち、
特定の攻撃に対して自動的にHTML出力を保護します。

テンプレートは、それをデータ構造に適用することで実行されます。テンプレート内の注釈は、
データ構造の要素（通常は構造体のフィールドやマップのキー）を参照して、実行を制御し、
表示する値を導き出します。テンプレートの実行は構造を歩き、カーソルを設定します。
これはピリオド '.' で表され、"dot"と呼ばれ、実行が進行するにつれて構造内の現在の位置の
値に設定されます。

テンプレートの入力テキストは、任意の形式のUTF-8エンコードされたテキストです。
"アクション" -- データ評価または制御構造 -- は "{{" と "}}" で区切られます。
アクションの外側のすべてのテキストは、そのままの状態で出力にコピーされます。

一度パースされると、テンプレートは並行して安全に実行することができますが、
並行実行がWriterを共有している場合、出力は交互になる可能性があります。

これは "17 items are made of wool" を出力する簡単な例です。

	type Inventory struct {
		Material string
		Count    uint
	}
	sweaters := Inventory{"wool", 17}
	tmpl, err := template.New("test").Parse("{{.Count}} items are made of {{.Material}}")
	if err != nil { panic(err) }
	err = tmpl.Execute(os.Stdout, sweaters)
	if err != nil { panic(err) }

より複雑な例は以下に示されています。

テキストとスペース

デフォルトでは、アクション間のすべてのテキストは、テンプレートが実行されるときに
そのままコピーされます。例えば、上記の例の " items are made of " という文字列は、
プログラムが実行されると標準出力に表示されます。

しかし、テンプレートのソースコードを整形するために、アクションの左
デリミタ（デフォルトでは "{{"）が直後にマイナス記号と空白に続いている場合、
直前のテキストからすべての末尾の空白がトリムされます。
同様に、右デリミタ（"}}"）が空白とマイナス記号に先行されている場合、
直後のテキストからすべての先頭の空白がトリムされます。
これらのトリムマーカーでは、空白が存在しなければなりません：
"{{- 3}}"は"{{3}}"と同じですが、直前のテキストをトリムします、一方
"{{-3}}"は数値-3を含むアクションとして解析されます。

例えば、ソースが以下のテンプレートを実行すると、

	"{{23 -}} < {{- 45}}"

生成される出力は以下のようになります。

	"23<45"

このトリミングにおいて、空白文字の定義はGoと同じです：スペース、水平タブ、キャリッジリターン、改行。

アクション

以下にアクションのリストを示します。"引数"と"パイプライン"は、
データの評価であり、それぞれに続く対応するセクションで詳細に定義されています。

*/
//	{{/* コメント */}}
//	{{- /* 前後のテキストから空白をトリムしたコメント */ -}}
//		コメント; 破棄されます。改行を含むことができます。
//		コメントはネストできず、ここに示されているように
//		デリミタで始まり終わらなければなりません。
/*

	{{パイプライン}}
		パイプラインの値のデフォルトのテキスト表現（fmt.Printによって
		印刷されるのと同じ）が出力にコピーされます。

	{{if パイプライン}} T1 {{end}}
		パイプラインの値が空の場合、出力は生成されません。
		それ以外の場合、T1が実行されます。空の値はfalse、0、
		任意のnilポインタまたはインターフェース値、および長さゼロの
		任意の配列、スライス、マップ、または文字列です。
		ドットは影響を受けません。

	{{if パイプライン}} T1 {{else}} T0 {{end}}
		パイプラインの値が空の場合、T0が実行されます。
		それ以外の場合、T1が実行されます。ドットは影響を受けません。

	{{if パイプライン}} T1 {{else if パイプライン}} T0 {{end}}
		if-elseチェーンの見た目を簡素化するために、ifのelseアクションは
		直接別のifを含むことができます。その効果は、以下を書くのと全く同じです。
			{{if パイプライン}} T1 {{else}}{{if パイプライン}} T0 {{end}}{{end}}

	{{range パイプライン}} T1 {{end}}
		パイプラインの値は、配列、スライス、マップ、またはチャネルでなければなりません。
		パイプラインの値の長さがゼロの場合、何も出力されません。
		それ以外の場合、ドットは配列、スライス、またはマップの連続する要素に設定され、
		T1が実行されます。値がマップで、キーが定義された順序を持つ基本型である場合、
		要素はソートされたキーの順序で訪れます。

	{{range パイプライン}} T1 {{else}} T0 {{end}}
		パイプラインの値は、配列、スライス、マップ、またはチャネルでなければなりません。
		パイプラインの値の長さがゼロの場合、ドットは影響を受けず、T0が実行されます。
		それ以外の場合、ドットは配列、スライス、またはマップの連続する要素に設定され、
		T1が実行されます。

	{{break}}
		最も内側の {{range pipeline}} ループが早期に終了し、
		現在の反復を停止し、残りのすべての反復をバイパスします。

	{{continue}}
		最も内側の {{range pipeline}} ループの現在の反復が停止し、
		ループは次の反復を開始します。

	{{template "name"}}
		指定された名前のテンプレートがnilデータで実行されます。

	{{template "name" パイプライン}}
		指定された名前のテンプレートが実行され、ドットはパイプラインの値に設定されます。

	{{block "name" pipeline}} T1 {{end}}
		ブロックは、テンプレートを定義するための省略形です
			{{define "name"}} T1 {{end}}
		そして、それをその場で実行します
			{{template "name" pipeline}}
		典型的な使用法は、一連のルートテンプレートを定義し、
		それらをブロックテンプレートを再定義することでカスタマイズすることです。

	{{with パイプライン}} T1 {{end}}
		パイプラインの値が空の場合、出力は生成されません。
		それ以外の場合、ドットはパイプラインの値に設定され、T1が実行されます。

	{{with パイプライン}} T1 {{else}} T0 {{end}}
		パイプラインの値が空の場合、ドットは影響を受けず、T0が実行されます。
		それ以外の場合、ドットはパイプラインの値に設定され、T1が実行されます。

	{{with pipeline}} T1 {{else with pipeline}} T0 {{end}}
		with-elseチェーンの見た目を簡単にするために、withのelseアクションは
		直接別のwithを含めることができます。その効果は、以下のように書くのと
		全く同じです。
			{{with pipeline}} T1 {{else}}{{with pipeline}} T0 {{end}}{{end}}


Arguments

引数は、以下のいずれかによって示される単純な値です。

	- Goの構文に従ったブール値、文字列、文字、整数、浮動小数点数、虚数
		または複素数の定数。これらはGoの型なし定数のように動作します。
		Goと同様に、大きな整数定数が割り当てられたり関数に渡されたりするときに
		オーバーフローするかどうかは、ホストマシンのintが32ビットか64ビットかに
		依存することに注意してください。
	- 型なしのGoのnilを表すキーワードnil。
	- 文字 '.' (ピリオド)：
			.
		結果はドットの値です。
	- 変数名、これはドル記号に続く（可能性のある空の）英数字の文字列で、
		例えば
			$piOver2
		または
			$
		結果は変数の値です。
		変数については以下で説明します。
	- データのフィールド名、これはピリオドに続く構造体でなければならず、
		例えば
			.Field
		結果はフィールドの値です。フィールドの呼び出しはチェーン化することができます：
			.Field1.Field2
		フィールドは変数に対しても評価することができ、チェーン化も可能です：
			$x.Field1.Field2
	- データのキー名、これはマップでなければならず、ピリオドに続きます、
		例えば
			.Key
		結果はキーによってインデックス付けされたマップ要素の値です。
		キーの呼び出しはチェーン化し、フィールドと任意の深さで組み合わせることができます：
			.Field1.Key1.Field2.Key2
		キーは英数字の識別子でなければならないが、フィールド名とは異なり、
		大文字で始まる必要はありません。
		キーは変数に対しても評価することができ、チェーン化も可能です：
			$x.key1.key2
	- データの引数なしメソッドの名前、これはピリオドに続きます、
		例えば
			.Method
		結果は、ドットをレシーバとしてメソッドを呼び出す値、dot.Method()です。
		このようなメソッドは1つの戻り値（任意の型）または2つの戻り値を持つ必要があり、
		2つ目はエラーです。
		2つある場合で戻り値のエラーがnilでない場合、実行は終了し、
		エラーがExecuteの値として呼び出し元に返されます。
		メソッドの呼び出しはチェーン化し、フィールドとキーと任意の深さで組み合わせることができます：
			.Field1.Key1.Method1.Field2.Key2.Method2
		メソッドは変数に対しても評価することができ、チェーン化も可能です：
			$x.Method1.Field
	- 引数なし関数の名前、例えば
			fun
		結果は関数を呼び出す値、fun()です。戻り型と値はメソッドと同様に動作します。
		関数と関数名については以下で説明します。
	- グルーピングのための上記のインスタンスを括弧で囲んだもの。結果は
		フィールドまたはマップキーの呼び出しによってアクセスできます。
			print (.F1 arg1) (.F2 arg2)
			(.StructValuedMethod "arg").Field

引数は任意の型に評価することができます。もしポインタであれば、実装は必要に応じて
自動的に基本型に間接参照します。
評価が関数値を生成する場合、例えば構造体の関数値フィールドなど、関数は自動的に
呼び出されませんが、ifアクションなどの真偽値として使用することができます。それを
呼び出すには、以下で定義されているcall関数を使用します。

パイプライン

パイプラインは、"コマンド"の可能性のあるチェーン化されたシーケンスです。コマンドは、単純な
値（引数）または関数またはメソッドの呼び出しで、複数の引数を持つ可能性があります：

	Argument
		結果は引数の評価値です。
	.Method [Argument...]
		メソッドは単独であるか、チェーンの最後の要素であることができますが、
		チェーンの中間にあるメソッドとは異なり、引数を取ることができます。
		結果は、引数を用いてメソッドを呼び出した値です：
			dot.Method(Argument1, etc.)
	functionName [Argument...]
		結果は、名前に関連付けられた関数を呼び出した値です：
			function(Argument1, etc.)
		関数と関数名については以下で説明します。

パイプラインは、パイプライン文字 '|' でコマンドのシーケンスを区切ることにより
"チェーン化"することができます。チェーン化されたパイプラインでは、各コマンドの結果が
次のコマンドの最後の引数として渡されます。パイプラインの最終コマンドの出力が
パイプラインの値となります。

コマンドの出力は、値が1つまたは2つ（2つ目の型はerror）のいずれかになります。
もし2つ目の値が存在し、非nilと評価される場合、実行は終了し、そのエラーは
Executeの呼び出し元に返されます。

変数

アクション内のパイプラインは、結果をキャプチャするために変数を初期化することができます。
初期化は以下の構文を持ちます

	$変数 := パイプライン

ここで、$変数は変数の名前です。変数を宣言するアクションは出力を生成しません。

以前に宣言された変数は、以下の構文を使用して割り当てることもできます

	$変数 = パイプライン

"range"アクションが変数を初期化する場合、変数は反復の連続する要素に設定されます。
また、"range"は、カンマで区切られた2つの変数を宣言することもできます：

	range $index, $element := パイプライン

この場合、$indexと$elementは、配列/スライスのインデックスまたはマップキーと要素の
連続する値に設定されます。ただし、変数が1つだけの場合、要素が割り当てられます。
これはGoのrange節の慣習とは逆です。

変数のスコープは、それが宣言された制御構造（"if"、"with"、または"range"）の
"end"アクションまで、またはそのような制御構造がない場合はテンプレートの終わりまで
広がります。テンプレートの呼び出しは、その呼び出し地点から変数を継承しません。

実行が開始されると、$はExecuteに渡されたデータ引数、つまり、dotの開始値に設定されます。

例

以下は、パイプラインと変数を示す一行のテンプレートの例です。
すべてが引用符で囲まれた単語 "output" を生成します：

	{{"\"output\""}}
		A string constant.
	{{`"output"`}}
		A raw string constant.
	{{printf "%q" "output"}}
		A function call.
	{{"output" | printf "%q"}}
		A function call whose final argument comes from the previous
		command.
	{{printf "%q" (print "out" "put")}}
		A parenthesized argument.
	{{"put" | printf "%s%s" "out" | printf "%q"}}
		A more elaborate call.
	{{"output" | printf "%s" | printf "%q"}}
		A longer chain.
	{{with "output"}}{{printf "%q" .}}{{end}}
		A with action using dot.
	{{with $x := "output" | printf "%q"}}{{$x}}{{end}}
		A with action that creates and uses a variable.
	{{with $x := "output"}}{{printf "%q" $x}}{{end}}
		A with action that uses the variable in another action.
	{{with $x := "output"}}{{$x | printf "%q"}}{{end}}
		The same, but pipelined.

関数

実行中、関数は2つの関数マップで見つけられます：まずテンプレート内、次にグローバル関数マップ内です。
デフォルトでは、テンプレート内には関数は定義されていませんが、Funcsメソッドを使用して追加することができます。

事前定義されたグローバル関数は以下のように名付けられます。

	and
		引数のブール型のANDを返します。つまり、最初の空の引数または最後の引数を返します。
		つまり、"and x y"は"if x then y else x"と同じように動作します。
		評価は引数を左から右へと進み、結果が決定した時点で返ります。
	call
		最初の引数（関数である必要があります）を、残りの引数をパラメータとして呼び出した結果を返します。
		したがって、"call .X.Y 1 2"はGoの表記ではdot.X.Y(1, 2)となります。ここで
		Yは関数値フィールド、マップエントリ、またはそれに類するものです。
		最初の引数は、関数型の値を生成する評価の結果でなければなりません
		（printのような事前定義された関数とは異なります）。関数は
		1つまたは2つの結果値を返す必要があり、2つ目の型はerrorです。引数が関数と一致しない場合や
		返されたエラー値が非nilの場合、実行は停止します。
	html
		引数のテキスト表現のエスケープされたHTML相当を返します。この関数は
		html/templateでは利用できません、いくつかの例外を除いて。
	index
		最初の引数を次の引数でインデックス化した結果を返します。
		したがって、"index x 1 2 3"はGoの構文ではx[1][2][3]となります。
		各インデックス化されたアイテムは、マップ、スライス、または配列でなければなりません。
	slice
		sliceは、最初の引数を残りの引数でスライスした結果を返します。
		したがって、"slice x 1 2"はGoの構文ではx[1:2]、"slice x"はx[:]、
		"slice x 1"はx[1:]、そして"slice x 1 2 3"はx[1:2:3]となります。
		最初の引数は、文字列、スライス、または配列でなければなりません。
	js
		引数のテキスト表現のエスケープされたJavaScript相当を返します。
	len
		引数の整数長を返します。
	not
		単一の引数のブール否定を返します。
	or
		引数のブール型のORを返します。つまり、最初の非空の引数または最後の引数を返します。
		したがって、"or x y"は"if x then x else y"と同じように動作します。
		評価は引数を左から右へと進み、結果が決定した時点で返ります。
	print
		fmt.Sprintのエイリアス
	printf
		fmt.Sprintfのエイリアス
	println
		fmt.Sprintlnのエイリアス
	urlquery
		その引数のテキスト表現のエスケープされた値を、URLクエリに埋め込むのに適した形で返します。
		この関数はhtml/templateでは利用できません、いくつかの例外を除いて。

ブール関数は、ゼロ値をfalse、非ゼロ値をtrueとして取ります。

また、関数として定義された一連の二項比較演算子もあります：

	eq
		arg1 == arg2のブール型の真偽値を返します
	ne
		arg1 != arg2のブール型の真偽値を返します
	lt
		arg1 < arg2のブール型の真偽値を返します
	le
		arg1 <= arg2のブール型の真偽値を返します
	gt
		arg1 > arg2のブール型の真偽値を返します
	ge
		arg1 >= arg2のブール型の真偽値を返します

よりシンプルな多方向の等価性テストのために、eq（のみ）は2つ以上の
引数を受け入れ、2番目以降を最初のものと比較し、実質的に以下を返します

	arg1==arg2 || arg1==arg3 || arg1==arg4 ...

(ただし、Goの||とは異なり、eqは関数呼び出しであり、すべての
引数が評価されます。)

比較関数は、Goが比較可能と定義している任意の型の値で動作します。
基本的な型、例えば整数については、ルールが緩和されています：
サイズと正確な型は無視され、任意の整数値、符号付きまたは符号なし、
は他の任意の整数値と比較することができます。（算術値が比較され、
ビットパターンではないので、すべての負の整数はすべての符号なし整数より小さいです。）
しかし、通常通り、intをfloat32などと比較することはできません。

関連付けられたテンプレート

各テンプレートは、作成時に指定された文字列によって名付けられます。また、各
テンプレートは、名前で呼び出すことができる他のテンプレートとゼロ以上関連付けられています。
そのような関連付けは推移的であり、テンプレートの名前空間を形成します。

テンプレートは、テンプレート呼び出しを使用して、別の関連付けられた
テンプレートをインスタンス化することができます。上記の "template" アクションの説明を参照してください。
名前は、呼び出しを含むテンプレートに関連付けられたテンプレートの名前でなければなりません。

ネストしたテンプレート定義

テンプレートを解析するとき、別のテンプレートが定義され、解析中の
テンプレートと関連付けられることがあります。テンプレート定義は、
Goプログラムのグローバル変数のように、テンプレートのトップレベルに
現れなければなりません。

そのような定義の構文は、各テンプレート宣言を
"define"と"end"アクションで囲むことです。

"define"アクションは、文字列定数を提供することで作成されるテンプレートの名前を指定します。
以下に簡単な例を示します：

	{{define "T1"}}ONE{{end}}
	{{define "T2"}}TWO{{end}}
	{{define "T3"}}{{template "T1"}} {{template "T2"}}{{end}}
	{{template "T3"}}

これは、T1とT2という2つのテンプレートを定義し、実行時に他の2つを呼び出す
T3という3つ目のテンプレートを定義します。最後にT3を呼び出します。このテンプレートが
実行されると、以下のテキストが生成されます

	ONE TWO

構造上、テンプレートは一つの関連付けのみに存在することができます。もしテンプレートを
複数の関連付けからアドレス可能にする必要がある場合、テンプレート定義は複数回パースされて
異なる*Template値を作成するか、[Template.Clone] または [Template.AddParseTree] メソッドでコピーされなければなりません。

Parseは、関連する複数のテンプレートを組み立てるために複数回呼び出すことができます。
関連するテンプレートがファイルに保存されている場合のパースを簡単に行うための
[ParseFiles]、[ParseGlob]、[Template.ParseFiles] および [Template.ParseGlob] を参照してください。

テンプレートは直接実行するか、または名前で識別される関連付けられたテンプレートを実行する
ExecuteTemplateを通じて実行することができます。上記の例を呼び出すために、私たちは
以下のように書くかもしれません。

	err := tmpl.Execute(os.Stdout, "no data needed")
	if err != nil {
		log.Fatalf("execution failed: %s", err)
	}

or to invoke a particular template explicitly by name,

	err := tmpl.ExecuteTemplate(os.Stdout, "T2", "no data needed")
	if err != nil {
		log.Fatalf("execution failed: %s", err)
	}

*/
package template