14 · 値の辞書としての __config__
シナリオ
複数のセルが同じ定数 ― 部門名、日付しきい値、更新カットオフ ― を参照します。すべてのセルにリテラルを埋め込むのは壊れやすいです。値 1 つ変えるのにテンプレート全体を探さないといけませんから。__config__ は作成者がどのセルからでも読んで使える値辞書の役割も併せ持ちます。
動作の仕組み
ADR-0011 基準で __config__ は予約された設定シートです。key と value の 2 列で構成されます。一部のキーはスペックで定義されています(name、description、source_sheet、source_table、output_file_pattern、match_pattern)。それ以外のキーは作成者が自由に定義でき、次のようにアクセスします:
{{ __config__[key_name] }}
例
__config__:
| キー | 値 |
|---|---|
source_sheet | 元データ |
source_table | 1 |
output_file_pattern | レポート.xlsx |
priority_threshold | 10000 |
default_region | 東京 |
report_owner | 田中 |
テンプレートセル:
{{ "Prepared by " & __config__[report_owner] }}
{{ IF([更新金額] > __config__[priority_threshold], "優先", "標準") }}
{{ IFEMPTY([地域], __config__[default_region]) }}
priority_threshold を 10000 から 5000 に変えればすべてのセルが一度に更新されます。作成者はレポートのあちこちに散らばった 20 個の式ではなく、__config__ のセル 1 つを修正するだけで済みます。
型認識
__config__ に保存された値は、書き込んだセルの型をそのまま引き継ぎます:
- 数値セルは数値とし て(
10000は数値で比較されます)。 - 文字列セルは文字列として。
- 日付セルは Date として。
- ブール値は Boolean として。
__config__[priority_threshold] > 5000 ← 数値比較
__config__[start_date] = TODAY() ← 日付比較
特定の型を強制したいなら Excel セル型をそれに合わせて指定してください。テンプレート内で明示的に変換するには TEXT()(数値 → 文字列)または算術演算(__config__[x] + 0 で数値文字列 → 数値の強制変換)を使えばよいです。
再利用できない予約キー
ADR-0011 に従って、次の __config__ キーはスペックで定義されエンジンが直接読みます。カスタム意味で上書きしてはいけません:
namedescriptionsource_sheetsource_tableoutput_file_patternmatch_pattern
カスタムキーは ^__[a-z]+__$ パターン(例: __foo__ のような dunder で包んだ名前)とマッチしてはいけません(ADR-0027 予約)。先頭に単一の _ が付くのは構いません。それ以外はどんな識別子も使えます。
ソースデータに入れないのはなぜ?
ワークフロー内で「共有定数」を扱う 2 つの選択肢があります:
__config__の作成者定義キー ― 値がテンプレート内に居座ります。値を変更するにはテンプレートをバージョンアップする必要があります。運用担当者が触れてはいけない組織単位の定数に適しています。default付きの__inputs__宣言 ― 値はテンプレート内にありますが、ホストが実行のたびに上書きできます。運用担当者が毎回調整できる実行単位パラメータ(対象月、しきい値など)に適しています。
「このテンプレートはこれらの定数でハードコードされていて、変えるにはテンプレートを修正する必要がある」なら __config__ を使ってください。「このテンプレートはパラメータを受け取り、ホストが実行のたびに決めて渡す」なら __inputs__ を使ってください。
スペックポインタ
- ADR-0011 ― 予約シート命名規則。
spec/evaluation.mdの「Template Configuration」。- 実行単位の代替手段である
__inputs__は Cookbook 06 を参照。