templater

Documentation

Index

• func ExpandShell(s string, data map[string]any) string
• func IsSH() bool
• func Replace[T any](v T, cache *Cache) T
• func ReplaceGlobs(globs []*ast.Glob, cache *Cache) []*ast.Glob
• func ReplaceNoShell[T any](v T, cache *Cache) T
• func ReplaceNoShellWithExtra[T any](v T, cache *Cache, extra map[string]any) T
• func ReplaceVar(v ast.Var, cache *Cache) ast.Var
• func ReplaceVarWithExtra(v ast.Var, cache *Cache, extra map[string]any) ast.Var
• func ReplaceVars(vars *ast.Vars, cache *Cache) *ast.Vars
• func ReplaceVarsWithExtra(vars *ast.Vars, cache *Cache, extra map[string]any) *ast.Vars
• func ReplaceWithExtra[T any](v T, cache *Cache, extra map[string]any) T
• func ResolveRef(ref string, cache *Cache) any
• type Cache
  • func (r *Cache) Err() error
  • func (r *Cache) ResetCache()
  • func (r *Cache) Seed(m map[string]any)
  • func (r *Cache) Update(k string, v any)

Functions

func ExpandShell

func ExpandShell(s string, data map[string]any) string

ExpandShell expands shell-native variable references in s against data. Recognizes:

• ${NAME} — bracketed form, NAME must be [a-zA-Z_][a-zA-Z0-9_]*
• $NAME — unbracketed form, NAME same charset
• $$ — literal $ (SPEC §Template Syntax)

Unknown references are left literal so the shell can handle them — e.g. `$?`, `$1`, or an env-only var not declared in the Ritefile pass through unchanged for mvdan/sh to interpret downstream. Only refs whose name is a known key in data get substituted.

Quoting honors POSIX shell semantics: `'…'` suppresses expansion entirely, `"…"` keeps expanding, `\$` outside or inside double quotes is a literal `$`. Heredocs participate too — `<<'DELIM'` or `<<\DELIM` disables expansion in the body; bare `<<DELIM` keeps it. Single-quoted strings treat `\` as a literal character (POSIX). This exists so Ritefiles can emit literal `$X` runs (heredoc help text, sed scripts, etc.) without sentinel workarounds — see #121.

func IsSH

func IsSH() bool

Deprecated: now always returns true

func Replace

func Replace[T any](v T, cache *Cache) T

func ReplaceGlobs

func ReplaceGlobs(globs []*ast.Glob, cache *Cache) []*ast.Glob

func ReplaceNoShell

func ReplaceNoShell[T any](v T, cache *Cache) T

ReplaceNoShell is like Replace but skips the ExpandShell pass. Use this for strings that will be handed to a shell for interpretation (task cmd.Cmd): the shell resolves `$VAR` against its own env, and until Phase 4's vars/env unification lands, rite vars and the shell env can have different values for the same name. Running ExpandShell on a shell-bound string would pre-empt the shell with rite's var-set answer, which is premature — the endstate is correct but wave 3 hasn't yet collapsed the tiers.

func ReplaceNoShellWithExtra

func ReplaceNoShellWithExtra[T any](v T, cache *Cache, extra map[string]any) T

ReplaceNoShellWithExtra is the for-loop iterator counterpart to ReplaceNoShell — same shell-bypass, but accepts per-iteration extras.

func ReplaceVar

func ReplaceVar(v ast.Var, cache *Cache) ast.Var

func ReplaceVarWithExtra

func ReplaceVarWithExtra(v ast.Var, cache *Cache, extra map[string]any) ast.Var

func ReplaceVars

func ReplaceVars(vars *ast.Vars, cache *Cache) *ast.Vars

func ReplaceVarsWithExtra

func ReplaceVarsWithExtra(vars *ast.Vars, cache *Cache, extra map[string]any) *ast.Vars

func ReplaceWithExtra

func ReplaceWithExtra[T any](v T, cache *Cache, extra map[string]any) T

func ResolveRef

func ResolveRef(ref string, cache *Cache) any

Types

type Cache

type Cache struct {
	Vars *ast.Vars
	// contains filtered or unexported fields
}

Cache is a help struct that allow us to call "replaceX" funcs multiple times, without having to check for error each time. The first error that happen will be assigned to r.err, and consecutive calls to funcs will just return the zero value.

Safe for concurrent use: internal state is guarded by mu. Concurrent Replace calls from different goroutines (e.g. the output.Group wrappers used by parallel deps) used to race on the cacheMap lazy init — see #52.

func (*Cache) Err

func (r *Cache) Err() error

func (*Cache) ResetCache

func (r *Cache) ResetCache()

func (*Cache) Seed

func (r *Cache) Seed(m map[string]any)

Seed adds fallback entries to the templater's view that aren't part of the underlying Vars. Existing keys are preserved. Used to make built-in vars visible to template resolution while keeping them out of the canonical variable set until lowest-priority merge time.

func (*Cache) Update

func (r *Cache) Update(k string, v any)

Update records a key/value pair that was just added to the underlying Vars so the templater's view stays consistent without rebuilding from scratch.