render

Documentation

Overview

Package render turns a fetched template plus a set of answers into files on disk.

Index

• func EffectiveInclude(t blueprint.Template) (include []string, suffix string)
• func Execute(tpl string, data any, left, right string) (string, error)
• func FieldRefs(text, left, right string) ([]string, error)
• func HasExpression(text, left string) bool
• func Hash(data []byte) string
• func Match(pattern, rel string) bool
• func ParseOnly(text, left, right string) error
• func Truthy(s string) bool
• type Builtins
• type Options
• type Resolver
  • func (r *Resolver) Data(answers map[string]any) map[string]any
  • func (r *Resolver) Resolve(vars []blueprint.Variable) (map[string]any, error)
• type Result
  • func Render(o Options) (*Result, error)
  • func (r *Result) Paths() []string

Functions

func EffectiveInclude

func EffectiveInclude(t blueprint.Template) (include []string, suffix string)

effectiveInclude resolves the include globs and the suffix to strip.

With nothing configured, `*.tmpl` files are rendered and lose the suffix. The alternative — rendering every file by default — corrupts any template that legitimately contains the delimiters, which covers Blade views, Helm charts, GitHub Actions expressions and Go templates. EffectiveInclude exposes the resolved globs and suffix, so that callers scanning a template for manifests know what suffix to strip.

func Execute

func Execute(tpl string, data any, left, right string) (string, error)

Execute renders a single template string against data. Used for hooks and inline file contents.

func FieldRefs

func FieldRefs(text, left, right string) ([]string, error)

FieldRefs returns the top-level field names a template reads from its data, so `{{ .app_name }}` yields "app_name" and `{{ .Rig.Project }}` yields "Rig".

This is what lets a typo'd variable be caught without rendering. Execution only reaches the branches the answers select, so a reference inside an untaken `if` can sit broken for as long as nobody picks that combination.

Fields inside a `with` or `range` body are deliberately not collected: dot is rebound there, so `{{ with .db }}{{ .host }}{{ end }}` reads host from db rather than from the top level, and reporting it as undeclared would be wrong. A false accusation is worse than a missed one in a check that fails builds.

func HasExpression

func HasExpression(text, left string) bool

HasExpression reports whether text contains a template action at all, so that plain strings can skip parsing entirely.

func Hash

func Hash(data []byte) string

Hash exposes the content hash used in the lockfile.

func Match

func Match(pattern, rel string) bool

Match exposes the glob matcher, so validation can work out which files in a template would be rendered without duplicating the rule.

func ParseOnly

func ParseOnly(text, left, right string) error

ParseOnly parses a template without executing it, using the same functions and delimiters a real render would. It reports syntax errors and calls to functions that do not exist.

func Truthy

func Truthy(s string) bool

Truthy is the exported form, so the runner applies the same rule to `when` on files and hooks that the resolver applies to variables.

Types

type Builtins

type Builtins struct {
	// Project is the target directory's base name.
	Project string
	// Dir is the absolute path of the generated project.
	Dir string
	// Blueprint is the blueprint's name.
	Blueprint string
	// Version is the rig version that generated the project.
	Version string
}

Builtins are the values rig supplies itself, reachable in templates under `.Rig`. They live in their own namespace so that adding a builtin later can never collide with a blueprint's variable — which is also why the parser restricts variable names to lowercase.

type Options

type Options struct {
	// TemplateRoot is the fetched skeleton. May be empty for a blueprint that
	// declares only inline files.
	TemplateRoot string
	// TargetDir is written into. It is created if missing.
	TargetDir string
	// BlueprintDir is the directory holding blueprint.yaml, and the anchor
	// for any `from` partial. Required only when a file uses one.
	BlueprintDir string

	Template blueprint.Template
	Files    []blueprint.File
	Data     map[string]any
}

Options configures one render pass.

type Resolver

type Resolver struct {
	Prompter ui.Prompter

	// Preset holds answers replayed from a lockfile. Keys that no longer
	// match a variable are dropped, and values that are no longer valid fall
	// back to the default.
	//
	// That leniency is not politeness, it is correctness. Blueprints remove
	// variables and change the options of a choice, and a project generated
	// before such a change still carries the old answer. Treating that as an
	// error would make `rig apply` fail permanently for every project older
	// than the edit — template evolution would be one-way.
	Preset map[string]string

	// Override holds answers given on the command line with --set. An
	// unknown key here is an error, because at a keyboard it is a typo.
	Override map[string]string

	Builtins Builtins
	// Left and Right are the template delimiters, matching the ones used for
	// file contents so a blueprint only has to choose once.
	Left, Right string
}

Resolver turns a blueprint's variable declarations into concrete answers.

func (*Resolver) Data

func (r *Resolver) Data(answers map[string]any) map[string]any

Data exposes the finished context for the render pass.

func (*Resolver) Resolve

func (r *Resolver) Resolve(vars []blueprint.Variable) (map[string]any, error)

Resolve walks the variables in declaration order, so that a later variable's default and `when` can refer to an earlier answer. That ordering guarantee is the reason `variables` is a list rather than a map.

type Result

type Result struct {
	// Files maps a project-relative slash path to the sha256 of its content.
	Files map[string]string
}

Result records what was produced. The hashes are what `rig apply` compares against to tell a file the user edited from one still as generated.

func Render

func Render(o Options) (*Result, error)

Render writes the template and the blueprint's inline files into TargetDir.

func (*Result) Paths

func (r *Result) Paths() []string

Paths returns the generated paths in sorted order.