コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

これらのページの出力の読み方

このセクションのほとんどのページでは、入力に加えて出力も示しています。ビルドが dist/ の下に書き出したファイル、ビルドがターミナルに表示したテキスト、またはビルドが書き出したものに対して tofu のようなツールを実行したときに表示された内容です。

これらのブロックは実際の実行結果からコピーしたもので、手で書いたものではありません。 例を自分でビルドすれば、自分の出力をページと 1 行ずつ比較できます。

出力をここに載せている理由は、まさにこの比較のためです。いくつかのページでは、1 行を変更して再ビルドする、あるいはレンダリングされたファイルを削除してツールを再実行するよう求め、その差分を読むよう求めます。こうした指示に従う価値があるのは、比較対象のブロックが正確な場合だけです。そうでなければ、ページが見つけさせようとした差分と、ページが単に触れなかった差分とを見分ける手段がありません。

そのため、出力を示すブロックは常に 2 つの状態のどちらかであり、その中間になることはありません。

完全

ブロックは、ページが指したものの全体を示します。導入文が web サービスと言う場合、そのサービスのすべての行が含まれています。ファイルを指す場合、ファイル全体が含まれています。

省略箇所を示した抜粋

実際の出力は長いことが多く、すべてを表示すると、ページが説明しようとしている 1 行が埋もれてしまいます。行を省略した場合、ブロックは省略した位置に、独立した行でそのことを示します。

[… omitted: what was left out]

実際の使用例を示します。これは terraform-declared-sensitivity の例の plan で、説明の要点は 1 つの属性に関するものです。

# module.store.terraform_data.reference will be created
+ resource "terraform_data" "reference" {
[… omitted: an id attribute, reported as known only after apply]
+ input = (sensitive value)
[… omitted: an output attribute, reported as known only after apply]
+ triggers_replace = [
+ "app-artifacts",
+ "AKIAEXAMPLE0001",
]
}

自分の plan には、これら 2 つの属性が含まれます。このマークによって、それらがそこにあるべきものであること、つまりビルドが異なる動作をした結果ではなく、ページが再掲しないことを選んだ行であることがわかります。マークは行が省かれた各位置に置かれるため、行がないことと同様に、その位置も読み取れます。

マークは常に、何かが省かれたことだけでなく、何が省かれたかを示します。「An id attribute, reported as known only after apply」とあれば、その行に出会ったときに見分けるのに十分ですが、単なる省略記号ではそうはいきません。

角括弧は意図的なものです。 [… で始まる行は、YAML、HCL、JSON、その他これらのページが表示するどの形式でも有効な内容ではなく、ここで示すどのツールもそのような行を表示しません。そのため、こうした行は常にページによる説明であり、ビルドが生成したものではありません。出力と取り違えられることも、流し読みで見落とされることもありません。

省略に当たらないもの

次の 4 つは、何も省略せずにブロックの見た目を変えるもので、いずれもマークを付けません。

  • より小さな範囲を指すこと。 「web サービス」と述べてそのサービスを示すページは、指したものから何も省略していません。ファイルの残りの部分は、範囲から欠けているのではなく、範囲の外にあります。
  • インデント。 深くネストした構造から取り出した断片は、単独で読めるよう、通常は左端から表示します。行は出力されたとおりの行であり、変わったのは先頭の空白だけです。
  • キャプションや注記。 行の出典となるファイルを示す # 行や、値の横の短い注記は、ビルドではなくページによる説明であることが見てわかります。
  • 引用したメッセージの各行に付けた #。 ページがコマンドとそれが表示したメッセージを 1 つのブロックで示す場合、ブロック全体を実行可能に保つため、メッセージはコメントアウトされています。表示された 1 行が長い場合、この幅で読みやすくするために複数の # 行に折り返すことがあります。いずれの場合も、文言は表示されたとおりの文言で、表示された順序のままです。

マークは、ほかの方法では検出できない唯一のケース、つまり行が単に存在しない場合のためにあります。

再現ではなく説明のためのブロック

ここにあるいくつかのページは、ビルドできるワークスペースではなく文章によるウォークスルーであり、1、2 のページは特定の実行結果ではなくペイロードの形を示しています。そうしたブロックには差分比較できるという保証がないため、周囲の文章でそのことを明記しています。本物の代わりに黙って置かれることはありません。ブロックにそうした記載がなければ、それは実行結果からコピーされたものであり、上記の 2 つの状態が適用されます。

これらのページを改変する場合

同じ 2 つの状態を維持してください。例を変更したため、あるいは新しい release のレンダリング結果が異なるために出力が変わった場合は、ブロックを手で編集するのではなく実際の実行結果で置き換え、省略した行にはマークを付けてください。正しく見えるように編集されたブロックは、確認済みのブロックとまったく同じように読めてしまうため、この慣例が防ごうとしているのはまさにそれです。