Documentation
¶
Overview ¶
Package template provides utilities for Go template AST inspection and analysis. This package enables extraction of field references from templates, which is useful for dependency resolution (e.g., locals referencing other locals).
Index ¶
- func DeferCalls(tree *parse.Tree, namespace, method string, data any, resolveRoots ...string) int
- func ExtractAllFieldRefsByPrefix(templateStr string, prefix string) ([]string, error)
- func ExtractFieldRefsByPrefix(templateStr string, prefix string) ([]string, error)
- func HasDynamicScope(templateStr string) (bool, error)
- func HasRootReference(templateStr string) (bool, error)
- func HasTemplateActions(str string) (bool, error)
- func LookupFieldPath(data any, path []string) (any, bool)
- func StaticFunctionNames(input string, delimiters ...string) ([]string, bool)
- type FieldRef
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DeferCalls ¶
DeferCalls rewrites a parsed template so that every simple action calling the template function `namespace.method` (for example `atmos.Component`) is emitted verbatim as text when the template is executed, instead of being evaluated. The emitted text is itself a template action, so a later render pass can evaluate it with a richer context.
Only plain actions are deferred. Actions that declare or assign variables and control structures (if, range, with) that call the function are left untouched, because emitting part of them would leave the template unbalanced or the declared variables undefined. Actions referencing variables or a dot rebound by range/with also remain in their original execution scope.
A deferred action is emitted in its canonical form (trim markers are not preserved). Field references in a deferred action that are rooted at one of resolveRoots (for example `locals`, which only exist during the current pass) are replaced by their scalar value from data, so that the later pass does not need them. References that cannot be resolved to a scalar are left as is.
It returns the number of actions that were deferred.
func ExtractAllFieldRefsByPrefix ¶
ExtractAllFieldRefsByPrefix extracts all field references that start with a specific prefix, returning the full remaining path after the prefix. For example, ExtractAllFieldRefsByPrefix(tmpl, "locals") for .locals.config.nested returns ["config.nested"].
func ExtractFieldRefsByPrefix ¶
ExtractFieldRefsByPrefix extracts field references that start with a specific prefix. For example, ExtractFieldRefsByPrefix(tmpl, "locals") returns all .locals.X references. Returns the second-level identifiers (e.g., "foo" for .locals.foo).
func HasDynamicScope ¶ added in v1.229.0
HasDynamicScope reports whether a template contains a `range` or `with` action, either of which rebinds "." to something other than the template's root data for the body it encloses. Field references found inside such a body (e.g. `.name` inside `{{ range .vars.list }}{{ .name }}{{ end }}`) are NOT relative to the template's root, so a caller using ExtractFieldRefs to statically determine which root-level fields a template touches (see pkg/list/column.RequiredSections) must treat any template containing dynamic scope as unresolvable rather than misattributing those inner references to the root.
func HasRootReference ¶ added in v1.229.0
HasRootReference reports whether a template contains a bare "." action (*parse.DotNode) -- e.g. "{{ . }}" or "{{ printf "%v" . }}" -- which accesses the entire root data value rather than a specific named field. ExtractFieldRefs only records *parse.FieldNode matches, so a template consisting solely of "{{ . }}" yields zero field references even though it exposes every field of the root, including ones no FieldNode ever names. Callers like pkg/list/column.RequiredSections that statically enumerate which root-level fields a template touches must treat any such reference as unresolvable rather than silently recording it as touching nothing.
func HasTemplateActions ¶
HasTemplateActions checks if a string contains Go template actions. This is a more robust version that uses AST parsing instead of simple string matching.
func LookupFieldPath ¶ added in v1.223.0
LookupFieldPath resolves a field path against map-like data.
func StaticFunctionNames ¶
StaticFunctionNames returns the distinct names of the functions a template calls, in order of first appearance, without executing anything. Callers decide which functions are acceptable. The second result is false when the template does not parse. An optional delimiter pair uses the same syntax as the template evaluator.
Types ¶
type FieldRef ¶
type FieldRef struct {
Path []string // e.g., ["locals", "foo"] for .locals.foo
}
FieldRef represents a reference to a field in a template (e.g., .locals.foo).
func ExtractFieldRefs ¶
ExtractFieldRefs parses a Go template string and extracts all field references. Handles complex expressions: conditionals, pipes, range, with blocks, nested templates. Returns nil if the string is not a valid template or contains no field references.
func ExtractPlainFieldRef ¶ added in v1.223.0
ExtractPlainFieldRef returns the field reference when the template is exactly one plain field action, such as "{{ .locals.default_tags }}".
func StaticFieldRefs ¶ added in v1.230.0
StaticFieldRefs returns root-relative dependencies without executing functions. Function names are resolved by the evaluator, not by this structural analysis. Dynamic scope, whole-root access, and named template calls require full evaluation. An optional delimiter pair uses the same syntax as the template evaluator.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package datasource renders Gomplate templates with merged YAML/JSON metadata.
|
Package datasource renders Gomplate templates with merged YAML/JSON metadata. |
|
Package delimiters resolves and applies the Go template delimiters that `templates.settings.delimiters` configures in atmos.yaml.
|
Package delimiters resolves and applies the Go template delimiters that `templates.settings.delimiters` configures in atmos.yaml. |