quill

README

Quill

A general-purpose, gradually-typed, fast template engine for Go.

Quill is a template engine for Go that pairs Twig-class composition with things nothing else in the Go template space combines: a gradual type system, a compile-to-Go backend, native branch-aware coverage, a sandbox, streaming, and byte-exact whitespace control. Use it for HTML pages, config files, emails, source, or any other text -- no use case is privileged.

Full docs: https://avmnu-sng.github.io/quill-template-engine/ · API reference: https://pkg.go.dev/github.com/avmnu-sng/quill-template-engine

Contents

• Why Quill
• Install
• 30-second example
• Passing Go data
• Escaping
• Use cases
• Coming from Jinja, Twig, or Go text/template
• Editor support
• Documentation
• Development
• License

Why Quill

• Gradual type system. Annotate as much or as little as you like; the checker catches undefined names, bad calls, and type mismatches at load time, before a byte is rendered, and untyped values still just work. Removing every annotation renders identical bytes -- types only move an error earlier in time.
• Compile-to-Go backend. Templates compile to Go for the hot path, installed with WithCompiled -- a compiled loop renders several times faster than the interpreter, while a tiny interpreted template already beats text/template. See the Performance guide for methodology and numbers.
• Native branch-aware coverage. quill cover reports unit and branch coverage of your templates with text, LCOV, and HTML output and a FailUnder gate -- the analogue of go tool cover, for templates.
• Twig-class composition. extends, block, use, embed, macros, includes, and slots -- real template inheritance and reuse, not string concatenation.
• Whitespace control, byte-exact. Three trim modes (hard, line, and a no-trim close), Jinja-style trim_blocks/lstrip_blocks cleanup applied by default so control statements do not leak blank lines, a spaceless filter and region, a trim filter, and a keep-close-newline pragma.
• Sandbox and streaming. Run untrusted templates under a policy sandbox, and stream output to any io.Writer with RenderTo instead of buffering.
• No escaping by default, like Go text/template. Opt into HTML escaping with WithAutoescapeHTML.

Install

Add the library to a module:

go get github.com/avmnu-sng/quill-template-engine

Install the command-line tool (renders templates and reports coverage):

go install github.com/avmnu-sng/quill-template-engine/cmd/quill@latest

Quill requires Go 1.26 or newer and depends on nothing outside the Go standard library.

30-second example

Build an Environment over a loader and render by name.

package main

import (
	"fmt"

	quill "github.com/avmnu-sng/quill-template-engine"
	"github.com/avmnu-sng/quill-template-engine/pkg/runtime"
)

func main() {
	env := quill.NewWithArray(map[string]string{
		"greet.quill": `Hello {{ name | upper }}{{ "!" if loud }}`,
	})
	out, err := env.Render("greet.quill", map[string]runtime.Value{
		"name": runtime.Str("ada"),
		"loud": runtime.Bool(true),
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(out) // Hello ADA!
}

To load templates from disk (so @extends, @include, and @import resolve by name under a root), use a filesystem loader:

env := quill.New(loader.NewFilesystemLoader("templates"))

Loaders compose: loader.NewChainLoader tries several loaders in order, loader.NewPrefixLoader routes by name prefix, loader.NewFSLoader serves an fs.FS (including an embed.FS baked into the binary), and loader.NewFuncLoader sources templates from a callback.

Passing Go data

Render binds a map[string]runtime.Value built with the runtime constructors (runtime.Str, runtime.Int, runtime.Arr, and friends). To pass ordinary Go values instead, use RenderValues, which marshals each binding through runtime.FromGo:

type User struct {
	Name  string   `quill:"name"`
	Admin bool     `quill:"admin"`
	Tags  []string `quill:"tags"`
}

out, _ := env.RenderValues("greet.quill", map[string]any{
	"user":  User{Name: "ada", Admin: true, Tags: []string{"x", "y"}},
	"count": 3,
})

FromGo maps scalars, slices, maps (with a deterministic key order), and structs (honoring a quill:"name" or json:"name" tag) to the value model, and passes any existing runtime.Value through unchanged, so hand-built and native bindings mix freely.

Escaping

Output escaping is off by default, like Go text/template. Turn on HTML escaping globally with quill.WithAutoescapeHTML(true), or apply one of the six escape strategies (html, js, css, html_attr, html_attr_relaxed, url) locally with the escape(strategy)/e filter or an @escape strategy { ... @} region. Strategies compose via a stack, and content produced under an active strategy is marked safe so it is never escaped twice.

Use cases

Quill is general-purpose: no single output shape is privileged. It renders HTML pages, configuration files, emails, and program source with the same engine -- pick escaping and whitespace settings per job. See the docs for a worked example of each.

Coming from Jinja, Twig, or Go text/template

If you already know Jinja, Twig, or Go text/template, most of Quill will feel familiar: interpolation, pipe filters, if/for, and template inheritance all map across. The Whitespace Control guide includes a side-by-side mapping table so you can translate trim modifiers and block-cleanup behavior directly.

Editor support

The engine does not enforce a file extension -- template names are arbitrary strings -- but the recommended convention for template files on disk is .quill. It avoids a clash with CodeQL, whose .ql extension GitHub Linguist claims by default. A VS Code extension with a TextMate grammar for Quill lives in editors/vscode/; see its README for local install steps.

Documentation

The full guide lives at https://avmnu-sng.github.io/quill-template-engine/ and covers getting started, the language, the gradual type system, whitespace control, escaping and the sandbox, coverage, performance, the standard library, and the architecture. The canonical API reference is pkg.go.dev.

Development

Quill uses go-task as its build tool. Install it with go install github.com/go-task/task/v3/cmd/task@latest, then run task --list to see the targets. The common ones:

task build        # build all packages and the cmd/quill binary
task test         # go test ./...
task test:unit    # tests with the race detector and a coverage profile
task check:all    # gofmt, go vet, and go mod tidy checks
task lint:all     # golangci-lint + actionlint (needs task install:tools)
task ci           # the full pipeline: lint, checks, tests, and security scans

A thin Makefile forwards make build/make test/make check to the equivalent task targets. The engine itself is standard-library only; the linters and scanners are dev tooling. See CONTRIBUTING.md for the full workflow.

License

Apache-2.0. See LICENSE.

Documentation

Overview

Package quill is a general-purpose, gradually-typed, fast template engine for Go.

Quill compiles and renders templates written in the Quill language: a brace-delimited, keyword-led surface with pipe filters, arrow functions, and a Pratt-parsed expression language. It pairs Twig-class composition -- template inheritance, blocks, macros, includes, embeds, and traits -- with a gradual type system, a compile-to-Go backend for the hot path, native branch-aware coverage, a policy sandbox, streaming output, and byte-exact whitespace control. It renders HTML pages, configuration files, emails, program source, or any other text with the same engine; no single use case is privileged. The runtime depends on nothing outside the Go standard library.

See the guide at https://avmnu-sng.github.io/quill-template-engine/ for the language reference, grammar, standard library, runtime semantics, and the extension API. This package is under active development; its API is not yet stable.

The facade

Environment is the engine facade. Build one over a Loader with New (or over an in-memory template map with NewWithArray), then Render by name. Output escaping is off by default, like Go text/template, and undefined variables are strict by default; both, along with the sandbox, the type registry, coverage, streaming, the compiled backend, and host extensions, are configured through Option values.

The pipeline

A template loads once and is memoized. Loading parses the source into an AST, runs the gradual type checker (package check) between parse and interpret, and prepares the module for the tree-walking interpreter (package interp). The checker consumes the annotations the parser threads through the AST -- the @types block, @set/@for targets, @macro/@block params and returns, and arrow params -- infers types where the spec defines it, and applies the gradual `any` fallback everywhere a value is unannotated. It rejects an ill-typed template with a positioned error before any byte is rendered, catching the runtime errors a static reader can see: a string/number arithmetic mismatch, rendering a list/map value, a for over a non-iterable typed iterand, a missing member/method, a call with the wrong arity or argument types, a bad map key kind, and a set/for/param annotation inconsistent with what flows into it. It narrows unions and nullables through `is` tests and null-safe access. Object member shapes and host callable signatures come from an optional host registry (check.Registry, installed via WithTypes); with no registry, Object types are opaque-but-known and host calls are dynamic, and the checker still enforces every in-template annotation.

Annotations never change runtime behavior. An unannotated template types entirely as `any`, so the checker is silent and the template renders byte-for-byte identically to a build that ignores types; removing every annotation from any template yields the same bytes.

Composition and the standard library

The engine renders the full composition surface -- @extends/@block with parent(), @macro with defaults and variadics, @import/@from, @use trait reuse, @embed, and the statement- and function-form @include -- and the complete standard-library catalogue of filters, functions, and tests, including arrow functions through map/filter/sort/reduce/find, the `has some`/`has every` quantifiers, the `matches` regex operator, and the whitespace-control trim modifiers.

Performance

Templates run on a tree-walking interpreter by default, and a compiled loop or module can be generated with the compile-to-Go backend (package compile) and installed with WithCompiled for the hot path. Rendering can either return a string (Render) or stream to an io.Writer (RenderTo) without buffering the whole output.

Extensions

A host adds its own filters, functions, and tests through the ext package and layers them over the core library with WithExtensions (callable sets) or WithExtension (Extension bundles). A later host layer shadows an earlier one and every host layer shadows core.

Escaping and the sandbox

Output escaping is off by default. HTML escaping is available globally (WithAutoescapeHTML) or as one of six strategies applied by the escape/e filter and the @escape region. A host-supplied SecurityPolicy (sandbox.Policy) restricts the permitted tags, filters, functions, per-type methods, and per-type properties, enforced at compile time for the tag/filter/function floor and at each host member-access site for the type-graph. The sandbox activates globally (WithSandboxActive), per @sandbox region, or per sandboxed include, and each violation raises a host-catchable *errors.Security. Allowlisting is uniform with no grandfathering: a host callable is gated exactly like a built-in.

Coverage

An Environment with a cover.Collector attached (WithCoverage) records which units and branch arms each render exercised, unioning across renders and exported as text, LCOV, or HTML. Coverage is opt-in and zero-overhead when off, and instrumentation never changes rendered bytes.

Example

Render a template by name from an in-memory template map. Output escaping is off by default.

package main

import (
	"fmt"

	quill "github.com/avmnu-sng/quill-template-engine"
	"github.com/avmnu-sng/quill-template-engine/pkg/runtime"
)

func main() {
	env := quill.NewWithArray(map[string]string{
		"greet.quill": `Hello {{ name | upper }}{{ "!" if loud }}`,
	})
	out, err := env.Render("greet.quill", map[string]runtime.Value{
		"name": runtime.Str("ada"),
		"loud": runtime.Bool(true),
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(out)
}

Output:
Hello ADA!

Index

• Constants
• type Environment
  • func New(ldr loader.Loader, opts ...Option) *Environment
  • func NewWithArray(templates map[string]string, opts ...Option) *Environment
  • func (e *Environment) AutoescapeHTML() bool
  • func (e *Environment) CompileString(name, body string) (*interp.Template, error)
  • func (e *Environment) Coverage() *cover.Collector
  • func (e *Environment) Display(w io.Writer, name string, vars map[string]runtime.Value) error
  • func (e *Environment) Extensions() *ext.ExtensionSet
  • func (e *Environment) LoadTemplate(name string) (*interp.Template, error)
  • func (e *Environment) Logger() *log.Logger
  • func (e *Environment) Policy() *sandbox.Policy
  • func (e *Environment) RandomSeed() (int64, bool)
  • func (e *Environment) RawSource(name string) (string, bool)
  • func (e *Environment) Render(name string, vars map[string]runtime.Value) (string, error)
  • func (e *Environment) RenderCache() *cache.RenderCache
  • func (e *Environment) RenderString(name, body string, vars map[string]runtime.Value) (string, error)
  • func (e *Environment) RenderStringTo(w io.Writer, name, body string, vars map[string]runtime.Value) error
  • func (e *Environment) RenderStringValues(name, body string, vars map[string]any) (string, error)
  • func (e *Environment) RenderTo(w io.Writer, name string, vars map[string]runtime.Value) error
  • func (e *Environment) RenderToValues(w io.Writer, name string, vars map[string]any) error
  • func (e *Environment) RenderValues(name string, vars map[string]any) (string, error)
  • func (e *Environment) SandboxActive() bool
  • func (e *Environment) StrictVariables() bool
  • func (e *Environment) TabWidth() int
  • func (e *Environment) TemplateExists(name string) bool
• type Option
  • func WithAutoescapeHTML(on bool) Option
  • func WithCompiled(manifests ...*compiled.Manifest) Option
  • func WithCompiledVerify(report func(compiled.Divergence)) Option
  • func WithCoverage(coll *cover.Collector) Option
  • func WithExtension(exts ...ext.Extension) Option
  • func WithExtensions(sets ...*ext.ExtensionSet) Option
  • func WithLogger(l *log.Logger) Option
  • func WithRandomSeed(seed int64) Option
  • func WithSandboxActive(on bool) Option
  • func WithSandboxPolicy(p *sandbox.Policy) Option
  • func WithStrictVariables(on bool) Option
  • func WithTabWidth(spaces int) Option
  • func WithTypes(reg *check.Registry) Option

Examples

• Package
• Environment.RenderTo
• Environment.RenderValues
• WithAutoescapeHTML
• WithExtensions

Constants

const Version = "0.3.0"

Version is the module's released semantic version, without the leading v. The release workflow requires the pushed tag to equal "v" + Version, so this constant is the single source of truth for the version the module reports.

Types

type Environment

type Environment struct {
	// contains filtered or unexported fields
}

Environment is the engine facade: it ties a Loader, a parse cache, and the callable registry together and renders templates by name or from a string. It implements interp.Engine so the tree-walking renderer can load parents, includes, and imports through it.

The defaults match the spec: autoescape is OFF by default (spec 04 Section 8.1) and strict_variables is ON (the strict-by-default undefined policy, spec 04 Section 6). Both are configurable via Option.

func New

func New(ldr loader.Loader, opts ...Option) *Environment

New builds an Environment over a Loader with the given options. The registry is layered bottom-up: the core stdlib is the floor, then the engine-bound include/block-family callables, then each host extension set or bundle supplied via WithExtensions/WithExtension in option order. A later layer shadows an earlier one and every host layer shadows core (host callables shadow core, spec 03 Section 1).

func NewWithArray

func NewWithArray(templates map[string]string, opts ...Option) *Environment

NewWithArray is a convenience constructor over an in-memory template map.

func (*Environment) AutoescapeHTML

func (e *Environment) AutoescapeHTML() bool

AutoescapeHTML reports the default output strategy (interp.Engine).

func (*Environment) CompileString

func (e *Environment) CompileString(name, body string) (*interp.Template, error)

CompileString parses and prepares an ad-hoc template body, backing template_from_string (interp.Engine, spec 03 Section 3.3). The body is not added to the loader; inheritance/include targets in it still resolve by name.

func (*Environment) Coverage

func (e *Environment) Coverage() *cover.Collector

Coverage returns the host-attached coverage Collector, or nil when coverage is off (interp.Engine). The interpreter copies it into each render's cov field.

func (*Environment) Display

func (e *Environment) Display(w io.Writer, name string, vars map[string]runtime.Value) error

Display renders the named template directly into w -- the push model of the Template contract, under its traditional name. It is RenderTo: a slot-free template closure streams with bounded memory, a slot-using one buffers then writes, and the bytes written equal Render's returned string.

func (*Environment) Extensions

func (e *Environment) Extensions() *ext.ExtensionSet

Extensions returns the callable registry (interp.Engine).

func (*Environment) LoadTemplate

func (e *Environment) LoadTemplate(name string) (*interp.Template, error)

LoadTemplate parses and prepares the named template (interp.Engine), with both steps memoized: the parse cache pins the module and the prepared memo pins the Template built from it, so a warm load is two map hits. LoadTemplate therefore returns the SAME *Template pointer across calls for an unchanged template; a Template is immutable after prepare and safe to share across concurrent renders. CompileString and the RenderString family stay uncached.

func (*Environment) Logger

func (e *Environment) Logger() *log.Logger

Logger returns the sink the @log statement writes to (interp.Engine). It is never nil; without WithLogger it discards.

func (*Environment) Policy

func (e *Environment) Policy() *sandbox.Policy

Policy returns the host-supplied sandbox security policy, or nil (interp.Engine).

func (*Environment) RandomSeed

func (e *Environment) RandomSeed() (int64, bool)

RandomSeed returns the configured RNG seed and whether one was set (interp.Engine).

func (*Environment) RawSource

func (e *Environment) RawSource(name string) (string, bool)

RawSource returns the unparsed source text of the named template, backing the source() function (interp.Engine, spec 03 Section 3.2).

func (*Environment) Render

func (e *Environment) Render(name string, vars map[string]runtime.Value) (string, error)

Render loads the named template and renders it with vars, returning the output. When an installed compiled unit (WithCompiled) passes the dispatch gate the render runs through the generated function with identical output and error bytes, including the partial output an errored render returns.

func (*Environment) RenderCache

func (e *Environment) RenderCache() *cache.RenderCache

RenderCache returns the engine's rendered-body cache, backing @cache (interp.Engine, spec 01 Section 4.7).

func (*Environment) RenderString

func (e *Environment) RenderString(name, body string, vars map[string]runtime.Value) (string, error)

RenderString parses an ad-hoc template body (not added to the loader) and renders it. Inheritance/include/import targets in the body still resolve through the loader by name.

func (*Environment) RenderStringTo

func (e *Environment) RenderStringTo(w io.Writer, name, body string, vars map[string]runtime.Value) error

RenderStringTo parses an ad-hoc template body (not added to the loader) and renders it directly to w with RenderTo's streaming-vs-buffered behavior. Inheritance/include/import targets in the body still resolve through the loader by name.

func (*Environment) RenderStringValues

func (e *Environment) RenderStringValues(name, body string, vars map[string]any) (string, error)

RenderStringValues parses an ad-hoc template body (not added to the loader) and renders it from native Go bindings, marshaling each value through runtime.FromGo exactly as RenderValues does. Inheritance/include/import targets in the body still resolve through the loader by name.

func (*Environment) RenderTo

func (e *Environment) RenderTo(w io.Writer, name string, vars map[string]runtime.Value) error

RenderTo loads the named template and renders it directly to w. When the template closure uses no deferred-slot construct (@yield, @provide, slot()), the output streams to w incrementally with bounded memory; otherwise the full output is buffered, its slot placeholders are resolved, and the result is written to w in one call (nothing is written on a render error). The bytes written equal Render's returned string in both cases. RenderTo neither wraps nor flushes w; pass a bufio.Writer for buffered throughput and flush it after RenderTo returns (a @flush statement flushes such a writer mid-render). An installed compiled unit (WithCompiled) that passes the dispatch gate renders through the generated function: a slot-free unit streams to w exactly as the interpreter's slot-free path does, while a slots unit (Manifest.UsesSlots) buffers into a scratch builder that reaches w only on success, matching the interpreter's buffered-slots path which writes nothing on error -- so a mid-render error never leaks an unresolved placeholder to the caller's writer. Under WithCompiledVerify the dispatched render buffers both engines' outputs to compare them, then writes the interpreter's bytes: for a slot-free unit that includes an errored render's partial output (matching the streaming path), and for a slots unit it writes nothing on error (matching the buffered path).

Example

Stream output to any io.Writer with RenderTo instead of buffering the whole result.

package main

import (
	"os"

	quill "github.com/avmnu-sng/quill-template-engine"
	"github.com/avmnu-sng/quill-template-engine/pkg/runtime"
)

func main() {
	env := quill.NewWithArray(map[string]string{
		"list.quill": "@for n in nums {\nitem {{ n }}\n@}",
	})
	err := env.RenderTo(os.Stdout, "list.quill", map[string]runtime.Value{
		"nums": runtime.Arr(runtime.NewList(
			runtime.Int(1), runtime.Int(2), runtime.Int(3),
		)),
	})
	if err != nil {
		panic(err)
	}
}

Output:
item 1
item 2
item 3

func (*Environment) RenderToValues

func (e *Environment) RenderToValues(w io.Writer, name string, vars map[string]any) error

RenderToValues renders the named template directly to w like RenderTo, but from native Go bindings: each value in vars is marshaled through runtime.FromGo exactly as RenderValues does.

func (*Environment) RenderValues

func (e *Environment) RenderValues(name string, vars map[string]any) (string, error)

RenderValues renders the named template from native Go bindings: each value in vars is marshaled through runtime.FromGo, so a host can pass ordinary Go scalars, slices, maps, structs, and nested combinations without hand-building runtime.Value bindings. A value that is already a runtime.Value passes through unchanged, so hand-built and native bindings mix freely. An unsupported Go kind (a channel, a bare function, a complex number) returns the typed marshaling error and renders nothing.

Example

Pass ordinary Go values -- structs, slices, scalars -- with RenderValues, which marshals each binding through runtime.FromGo.

package main

import (
	"fmt"

	quill "github.com/avmnu-sng/quill-template-engine"
)

func main() {
	type User struct {
		Name  string   `quill:"name"`
		Admin bool     `quill:"admin"`
		Tags  []string `quill:"tags"`
	}

	env := quill.NewWithArray(map[string]string{
		"user.quill": `{{ user.name }} (admin: {{ user.admin }}) tags: {{ user.tags | join(", ") }}`,
	})
	out, err := env.RenderValues("user.quill", map[string]any{
		"user": User{Name: "ada", Admin: true, Tags: []string{"x", "y"}},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(out)
}

Output:
ada (admin: true) tags: x, y

func (*Environment) SandboxActive

func (e *Environment) SandboxActive() bool

SandboxActive reports the global sandbox activation gate (interp.Engine).

func (*Environment) StrictVariables

func (e *Environment) StrictVariables() bool

StrictVariables reports the undefined-handling policy (interp.Engine).

func (*Environment) TabWidth

func (e *Environment) TabWidth() int

TabWidth returns the spaces-per-indent-level width backing the tab filter, the tab/space/break functions, and the @tab region (interp.Engine, WithTabWidth).

func (*Environment) TemplateExists

func (e *Environment) TemplateExists(name string) bool

TemplateExists reports whether the named template can be loaded (interp.Engine).

type Option

type Option func(*Environment)

Option configures an Environment at construction.

func WithAutoescapeHTML

func WithAutoescapeHTML(on bool) Option

WithAutoescapeHTML turns the default output strategy to html (off by default).

Example

Turn on HTML escaping globally with WithAutoescapeHTML.

package main

import (
	"fmt"

	quill "github.com/avmnu-sng/quill-template-engine"
	"github.com/avmnu-sng/quill-template-engine/pkg/runtime"
)

func main() {
	env := quill.NewWithArray(
		map[string]string{"page.quill": `<p>{{ body }}</p>`},
		quill.WithAutoescapeHTML(true),
	)
	out, err := env.Render("page.quill", map[string]runtime.Value{
		"body": runtime.Str("<b>hi</b>"),
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(out)
}

Output:
<p>&lt;b&gt;hi&lt;/b&gt;</p>

func WithCompiled

func WithCompiled(manifests ...*compiled.Manifest) Option

WithCompiled installs generated compiled units (the compile backend's exported manifests) for by-name dispatch. Render, RenderTo, and the entry points delegating to them serve a template whose name matches an installed manifest through the generated render function instead of the interpreter, but only when the dispatch gate proves the bytes cannot differ: the manifest's compile-options fingerprint must equal this Environment's configuration, no sandbox policy or activation, coverage collector, or host type registry may be configured, a unit containing @log must not lose lines a non-discarding logger would receive, and every member source must byte-equal the text the loader currently serves (verified once and re-verified whenever the parse cache serves a re-parsed module). Any unprovable condition falls back to the interpreter, so installing a manifest changes render cost, never rendered bytes or errors. A host callable flagged NeedsEnvironment sees the serving path's own engine handle: the interpreter's and the generated code's handles are distinct concrete types exposing identical configuration through ext.EngineConfig, the injected handle's documented surface. A manifest missing its render function, entry name, or entry source is ignored; a later manifest for the same entry name replaces an earlier one. Templates whose output depends on UNSEEDED randomness are the documented exception: compiled and interpreted draws come from independent time-seeded sources, so their output compares distributionally, never byte-wise.

func WithCompiledVerify

func WithCompiledVerify(report func(compiled.Divergence)) Option

WithCompiledVerify switches the installed compiled units (WithCompiled) from direct dispatch to shadow verification: a by-name render the dispatch gate would serve compiled instead runs both engines, byte-compares the outputs and error text, reports any divergence to the report callback, and always serves the interpreter's result. It is the trust-building mode for a new unit: production traffic renders exactly as before while every would-be compiled render is checked against the authoritative interpreter. Under verification a dispatched RenderTo buffers the render instead of streaming, since both outputs must exist to compare; the interpreter's bytes -- including the partial output of an errored render -- are then written to w, so the writer receives exactly what the streaming paths would have written. WithCompiledVerify(nil) is the same as not passing it: direct dispatch stays on.

func WithCoverage

func WithCoverage(coll *cover.Collector) Option

WithCoverage attaches a template-coverage Collector so every Render on this Environment records which units and branch arms it exercised, unioning across renders (package cover, docs/coverage.md). It mirrors WithAutoescapeHTML / WithStrictVariables. WithCoverage(nil) is the same as not passing it: coverage stays off and the interpreter pays no per-node cost. Coverage instrumentation only reads node positions and increments counters, so a template renders byte-identically with or without it (the binding invariant).

func WithExtension

func WithExtension(exts ...ext.Extension) Option

WithExtension layers one or more Extension bundles over the core stdlib. Each bundle is registered (its filters, functions, tests, constants, and enums folded in) in New, interleaved with WithExtensions layers in the order the options were passed, so shadow order is uniform across sets and bundles: later shadows earlier, and every host layer shadows core.

func WithExtensions

func WithExtensions(sets ...*ext.ExtensionSet) Option

WithExtensions layers one or more host callable sets over the core stdlib. Each set is folded into the registry in New, after the core floor and the engine-bound callables, in the order given, so a later set shadows an earlier one and every host set shadows core (host shadows core, spec 03 Section 1). Multiple WithExtensions options accumulate in call order. Passing several sets in one call is equivalent to passing them across several options.

Example

Register a host filter and function through the ext package and render with them.

package main

import (
	"fmt"

	quill "github.com/avmnu-sng/quill-template-engine"
	"github.com/avmnu-sng/quill-template-engine/pkg/ext"
	"github.com/avmnu-sng/quill-template-engine/pkg/runtime"
)

func main() {
	set := ext.NewExtensionSet()
	set.AddFunction(ext.NewFunction("clamp", func(x, lo, hi int64) int64 {
		switch {
		case x < lo:
			return lo
		case x > hi:
			return hi
		default:
			return x
		}
	}))

	env := quill.NewWithArray(
		map[string]string{"demo.quill": `{{ clamp(42, 0, 10) }}`},
		quill.WithExtensions(set),
	)
	out, err := env.Render("demo.quill", map[string]runtime.Value(nil))
	if err != nil {
		panic(err)
	}
	fmt.Println(out)
}

Output:
10

func WithLogger

func WithLogger(l *log.Logger) Option

WithLogger sets the destination the @log statement writes to. The default is a discarding logger, so @log is inert until a host attaches a sink. @log produces no rendered output regardless of the logger.

func WithRandomSeed

func WithRandomSeed(seed int64) Option

WithRandomSeed fixes the seed of the engine's randomness functions (random, shuffle), making their output deterministic and reproducible. This is the documented determinism mechanism for tests and golden output (spec 03 Section 3.2, X15); without it the functions draw from a time-seeded source. It is a host/environment knob, distinct from any template-author argument.

func WithSandboxActive

func WithSandboxActive(on bool) Option

WithSandboxActive turns the sandbox on globally so every render is sandboxed (the always-on activation path, design/escaping-safety Section 6.2). Without a policy an active sandbox denies everything.

func WithSandboxPolicy

func WithSandboxPolicy(p *sandbox.Policy) Option

WithSandboxPolicy installs the host-supplied sandbox security policy: the allowlists for tags, filters, functions, per-type methods and properties, and the type-graph the per-type lookups walk (spec 04 Section 8.3). It does not by itself turn the sandbox on; activation is global (WithSandboxActive), per @sandbox region, or per sandboxed include. A policy is required for any of those to permit anything, since allowlisting is uniform with no grandfathering.

func WithStrictVariables

func WithStrictVariables(on bool) Option

WithStrictVariables sets strict-undefined handling (on by default). Setting it false enables the lenient mode: an undefined read becomes Null and a for over a non-iterable becomes an empty loop (spec 04 Section 6).

func WithTabWidth

func WithTabWidth(spaces int) Option

WithTabWidth sets the number of spaces one indent level expands to for the tab filter, the tab/space/break indentation functions, and the @tab region (spec 03 Section 5.1). The default is 4. A width below zero clamps to zero (an indent level then contributes nothing).

func WithTypes

func WithTypes(reg *check.Registry) Option

WithTypes installs the host static-typing registry the gradual type checker consults: the Object<"Name"> member shapes and host callable signatures (spec 04 Section 1, design/type-system.md Sections 4.4, 9.1). It does not enable or change any runtime behavior; it only sharpens the load-time checker so an annotation referencing a host type or a host callable can be verified. With no registry the checker still enforces every in-template annotation; Object types are then opaque and host calls dynamic.