template

README

template

Jinja2-compatible templating with Ansible's filter and test library, pure Go CGO=0.

Part of go-ansible — a pure-Go (CGO=0), functional-parity port of Ansible.

Usage

eng := template.New()

out, err := eng.Render("Hello {{ name | upper }}", map[string]any{"name": "world"})

ok, err := eng.EvalBool("ansible_facts.os_family == 'Debian'", data) // when: conditions

v, err := eng.RenderValue(rawYAMLValue, data) // whole-expression native-type preservation:
                                               // "{{ port }}" renders to an int, not "8080"

IsTemplate reports whether a string contains {{ }}/{% %} at all, so a caller can skip the engine for plain values. Ansible's filter and test library (to_json, regex_replace, combine, default, mandatory, ternary, …) is registered on every Engine.

Documentation

Overview

Package template implements Ansible's templating semantics on top of a Jinja2-compatible engine (github.com/nikolalohinski/gonja/v2): string interpolation with {{ }}, control structures with {% %}, Ansible's own filter and test library on top of the Jinja2 built-ins, and Ansible's rule that a value which is a SINGLE {{ expr }} with nothing else around it renders to the expression's native type (list, dict, int, bool...), not a string.

Index

• Variables
• func IsOmit(v any) bool
• func IsTemplate(s string) bool
• type Engine
  • func New() *Engine
  • func (e *Engine) Eval(exprSrc string, data map[string]any) (any, error)
  • func (e *Engine) EvalBool(exprSrc string, data map[string]any) (bool, error)
  • func (e *Engine) Render(src string, data map[string]any) (string, error)
  • func (e *Engine) RenderValue(raw any, data map[string]any) (any, error)

Variables

var Omit omitType

Omit is the sentinel value the "omit" global evaluates to. A task argument written as "{{ x | default(omit) }}" renders to this value when x is undefined, and RenderValue drops the containing map key or list item rather than passing Omit through to a module.

Functions

func IsOmit

func IsOmit(v any) bool

IsOmit reports whether v is the omit sentinel.

func IsTemplate

func IsTemplate(s string) bool

IsTemplate reports whether s contains any Jinja2 delimiter ({{, {%, or {#) and therefore needs rendering at all.

Types

type Engine

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

Engine renders Ansible-flavored Jinja2 templates and expressions.

func New

func New() *Engine

New returns an Engine with Jinja2's built-in filters/tests plus Ansible's filter and test library.

func (*Engine) Eval

func (e *Engine) Eval(exprSrc string, data map[string]any) (any, error)

Eval evaluates a single Jinja2 expression (no {{ }} wrapper — e.g. the raw text of an Ansible `when:` condition, or the inside of a wholeExpression string) and returns its native Go value.

func (*Engine) EvalBool

func (e *Engine) EvalBool(exprSrc string, data map[string]any) (bool, error)

EvalBool evaluates exprSrc and applies Ansible/Jinja2 truthiness — the semantics of a `when:` condition.

func (*Engine) Render

func (e *Engine) Render(src string, data map[string]any) (string, error)

Render renders a full template string (text mixed with {{ }} / {% %}) to its string form.

func (*Engine) RenderValue

func (e *Engine) RenderValue(raw any, data map[string]any) (any, error)

RenderValue applies Ansible's templating rule to an arbitrary decoded YAML value: strings are templated (with the whole-expression rule preserving native types), and lists/maps are walked recursively so a nested `{{ }}` anywhere in a task's arguments is resolved. Non-string scalars pass through unchanged.

A value that renders to Omit (see omit.go — typically reached via `default(omit)`) is dropped entirely: from a map, the whole key disappears; from a list, the item disappears — matching real Ansible's own "Omit values remaining in template results will be automatically dropped during template finalization." A bare top-level result of exactly Omit, with no containing map or list to drop it from, is an error, matching real Ansible's own AnsibleValueOmittedError.