gomplate

README

Read the docs at docs.gomplate.ca, chat with developers and community in the #gomplate channel on Gophers Slack

gomplate is a template renderer which supports a growing list of datasources, such as: JSON (including EJSON - encrypted JSON), YAML, AWS EC2 metadata, Hashicorp Consul and Hashicorp Vault secrets.

Come chat with developers and community in the #gomplate channel on Gophers Slack and on GitHub Discussions!

Here are some hands-on examples of how gomplate works:

$ # at its most basic, gomplate can be used with environment variables...
$ echo 'Hello, {{ .Env.USER }}' | gomplate
Hello, hairyhenderson

$ # but that's kind of boring. gomplate has tons of functions to do useful stuff, too
$ gomplate -i 'the answer is: {{ mul 6 7 }}'
the answer is: 42

$ # and, since gomplate uses Go's templating syntax, you can do fun things like:
$ gomplate -i '{{ range seq 5 1 }}{{ . }} {{ if eq . 1 }}{{ "blastoff" | toUpper }}{{ end }}{{ end }}'
5 4 3 2 1 BLASTOFF

$ # the real fun comes when you use datasources!
$ cat ./config.yaml
foo:
  bar:
    baz: qux
$ gomplate -d config=./config.yaml -i 'the value we want is: {{ (datasource "config").foo.bar.baz }}'
the value we want is: qux

$ # datasources are defined by URLs, and gomplate is not limited to just file-based datasources:
$ gomplate -d ip=https://ipinfo.io -i 'country code: {{ (ds "ip").country }}'
country code: CA

$ # standard input can be used as a datasource too:
$ echo '{"cities":["London", "Johannesburg", "Windhoek"]}' | gomplate -d city=stdin:///in.json -i '{{ range (ds "city").cities }}{{.}}, {{end}}'
London, Johannesburg, Windhoek, 

$ # and here's something a little more complicated:
$ export CITIES='city: [London, Johannesburg, Windhoek]'
$ cat in.tmpl
{{ range $i, $city := (ds "cities").city -}}
{{ add 1 $i }}: {{ include "weather" (print $city "?0") }}
{{ end }}
$ gomplate -d 'cities=env:///CITIES?type=application/yaml' -d 'weather=https://wttr.in/?0' -H 'weather=User-Agent: curl' -f in.tmpl
1: Weather report: London

    \  /       Partly cloudy
  _ /"".-.     4-7 °C
    \_(   ).   ↑ 20 km/h
    /(___(__)  10 km
               0.0 mm

2: Weather report: Johannesburg

    \  /       Partly cloudy
  _ /"".-.     15 °C
    \_(   ).   ↘ 0 km/h
    /(___(__)  10 km
               2.2 mm

3: Weather report: Windhoek

    \  /       Partly cloudy
  _ /"".-.     20 °C
    \_(   ).   ↑ 6 km/h
    /(___(__)  20 km
               0.0 mm

Read the documentation at docs.gomplate.ca, and join the discussion in GitHub Discussions!

Please report any bugs found in the issue tracker.

License

The MIT License

Copyright (c) 2016-2023 Dave Henderson

Documentation

Overview

Package gomplate is a template renderer which supports a number of datasources, and includes hundreds of built-in functions.

Index

• Variables
• func CreateFuncs(ctx context.Context) template.FuncMap
• func PluginFunc(ctx context.Context, cmd string, opts PluginOpts) func(...interface{}) (interface{}, error)
• func Run(ctx context.Context, cfg *Config) error
• func SetExperimental(ctx context.Context) context.Context
• type Config
  • func Parse(in io.Reader) (*Config, error)
  • func (c Config) MarshalYAML() (interface{}, error)
  • func (c *Config) MergeFrom(o *Config) *Config
  • func (c *Config) String() string
  • func (c *Config) UnmarshalYAML(value *yaml.Node) error
• type DataSource
• type MetricsType
• type PluginConfig
  • func (p *PluginConfig) UnmarshalYAML(value *yaml.Node) error
• type PluginOpts
• type RenderOptions
• type Renderer
  • func NewRenderer(opts RenderOptions) Renderer
• type Template

Examples

• PluginFunc
• PluginFunc (With_template)
• Renderer
• Renderer (Datasources)
• Renderer (ManyTemplates)

Variables

var DefaultFSProvider = sync.OnceValue(
	func() fsimpl.FSProvider {
		fsp := fsimpl.NewMux()

		fsp.Add(autofs.FS)

		fsp.Add(datafs.WdFS)

		fsp.Add(datafs.EnvFS)
		fsp.Add(datafs.StdinFS)
		fsp.Add(datafs.MergeFS)

		return fsp
	})()

DefaultFSProvider is the default filesystem provider used by gomplate

Functions

func CreateFuncs

func CreateFuncs(ctx context.Context) template.FuncMap

CreateFuncs - function mappings are created here

func PluginFunc

func PluginFunc(ctx context.Context, cmd string, opts PluginOpts) func(...interface{}) (interface{}, error)

PluginFunc creates a template function that runs an external process - either a shell script or commandline executable.

Example

ctx := context.Background()

// PluginFunc creates a template function that runs an arbitrary command.
f := PluginFunc(ctx, "echo", PluginOpts{})

// The function can be used in a template, but here we'll just run it
// directly. This is equivalent to running 'echo foo bar'
out, err := f("foo", "bar")
if err != nil {
	panic(err)
}
fmt.Println(out)

Output:

foo bar

Example (With_template)

ctx := context.Background()

f := PluginFunc(ctx, "echo", PluginOpts{})

// PluginFunc is intended for use with gomplate, but can be used in any
// text/template by adding it to the FuncMap.
tmpl := template.New("new").Funcs(template.FuncMap{"echo": f})

tmpl, err := tmpl.Parse(`{{ echo "baz" "qux" }}`)
if err != nil {
	panic(err)
}

err = tmpl.Execute(os.Stdout, nil)
if err != nil {
	panic(err)
}

Output:

baz qux

func Run

func Run(ctx context.Context, cfg *Config) error

Run all gomplate templates specified by the given configuration

func SetExperimental

func SetExperimental(ctx context.Context) context.Context

SetExperimental enables experimental functions and features in the given context. This must be done before creating functions. The set of experimental features enabled by this is not fixed and will change over time.

Types

type Config

type Config struct {
	// Stdin - override for stdin:// URLs or the '-' input file. Can't be set in
	// the config file.
	// Usually this should be left as default - this will be set at runtime.
	Stdin io.Reader `yaml:"-"`

	// Stdout - override for the '-' output file. Can't be set in the config
	// file.
	// Usually this should be left as default - this will be set at runtime.
	Stdout io.Writer `yaml:"-"`

	// Stderr - override for plugins to write to stderr. Can't be set in the
	// config file.
	// Usually this should be left as default - this will be set at runtime.
	Stderr io.Writer `yaml:"-"`

	// ExtraHeaders - Extra HTTP headers not attached to pre-defined datsources.
	// Potentially used by datasources defined in the template at runtime. Can't
	// currently be set in the config file.
	ExtraHeaders map[string]http.Header `yaml:"-"`

	DataSources map[string]DataSource   `yaml:"datasources,omitempty"`
	Context     map[string]DataSource   `yaml:"context,omitempty"`
	Templates   map[string]DataSource   `yaml:"templates,omitempty"`
	Plugins     map[string]PluginConfig `yaml:"plugins,omitempty"`

	Input                 string   `yaml:"in,omitempty"`
	InputDir              string   `yaml:"inputDir,omitempty"`
	InputFiles            []string `yaml:"inputFiles,omitempty,flow"`
	ExcludeGlob           []string `yaml:"excludes,omitempty"`
	ExcludeProcessingGlob []string `yaml:"excludeProcessing,omitempty"`

	OutputDir   string   `yaml:"outputDir,omitempty"`
	OutputMap   string   `yaml:"outputMap,omitempty"`
	OutputFiles []string `yaml:"outputFiles,omitempty,flow"`
	OutMode     string   `yaml:"chmod,omitempty"`

	LDelim string `yaml:"leftDelim,omitempty"`
	RDelim string `yaml:"rightDelim,omitempty"`

	MissingKey string `yaml:"missingKey,omitempty"`

	PostExec []string `yaml:"postExec,omitempty,flow"`

	PluginTimeout time.Duration `yaml:"pluginTimeout,omitempty"`

	ExecPipe     bool `yaml:"execPipe,omitempty"`
	Experimental bool `yaml:"experimental,omitempty"`
}

Config models gomplate's configuration file and command-line options. It also contains some fields that can't be set in the config file.

func Parse

func Parse(in io.Reader) (*Config, error)

Parse a config file

func (Config) MarshalYAML

func (c Config) MarshalYAML() (interface{}, error)

TODO: remove when we remove the deprecated array format for templates

Deprecated: custom unmarshaling will be removed in the next version

func (*Config) MergeFrom

func (c *Config) MergeFrom(o *Config) *Config

MergeFrom - use this Config as the defaults, and override it with any non-zero values from the other Config

Note that Input/InputDir/InputFiles will override each other, as well as OutputDir/OutputFiles.

func (*Config) String

func (c *Config) String() string

String -

func (*Config) UnmarshalYAML

func (c *Config) UnmarshalYAML(value *yaml.Node) error

TODO: remove when we remove the deprecated array format for templates

Deprecated: custom unmarshaling will be removed in the next version

type DataSource

type DataSource = config.DataSource

DataSource - datasource configuration

type MetricsType

type MetricsType struct {
	// times for rendering each template
	RenderDuration map[string]time.Duration
	// time it took to gather templates
	GatherDuration time.Duration
	// time it took to render all templates
	TotalRenderDuration time.Duration

	TemplatesGathered  int
	TemplatesProcessed int
	Errors             int
}

MetricsType - Warning: experimental! This may change in breaking ways without warning. This is not subject to any semantic versioning guarantees!

var Metrics *MetricsType

Metrics tracks interesting basic metrics around gomplate executions. Warning: experimental! This may change in breaking ways without warning. This is not subject to any semantic versioning guarantees!

type PluginConfig

type PluginConfig struct {
	Cmd     string
	Args    []string      `yaml:"args,omitempty"`
	Timeout time.Duration `yaml:"timeout,omitempty"`
	Pipe    bool          `yaml:"pipe,omitempty"`
}

func (*PluginConfig) UnmarshalYAML

func (p *PluginConfig) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML - satisfy the yaml.Umarshaler interface - plugin configs can either be a plain string (to specify only the name), or a map with a name, timeout, and pipe flag.

type PluginOpts

type PluginOpts struct {
	// Stderr can be set to redirect the plugin's stderr to a custom writer.
	// Defaults to os.Stderr.
	Stderr io.Writer

	// Args are additional arguments to pass to the plugin. These precede any
	// arguments passed to the plugin function at runtime.
	Args []string

	// Timeout is the maximum amount of time to wait for the plugin to complete.
	// Defaults to 5 seconds.
	Timeout time.Duration

	// Pipe indicates whether the last argument should be piped to the plugin's
	// stdin (true) or processed as a commandline argument (false)
	Pipe bool
}

PluginOpts are options for controlling plugin function execution

type RenderOptions

type RenderOptions struct {
	// Datasources - map of datasources to be read on demand when the
	// 'datasource'/'ds'/'include' functions are used.
	Datasources map[string]DataSource
	// Context - map of datasources to be read immediately and added to the
	// template's context
	Context map[string]DataSource
	// Templates - map of templates that can be referenced as nested templates
	Templates map[string]DataSource

	// Extra HTTP headers not attached to pre-defined datsources. Potentially
	// used by datasources defined in the template.
	ExtraHeaders map[string]http.Header

	// Funcs - map of functions to be added to the default template functions.
	// Duplicate functions will be overwritten by entries in this map.
	Funcs template.FuncMap

	// LeftDelim - set the left action delimiter for the template and all nested
	// templates to the specified string. Defaults to "{{"
	LDelim string
	// RightDelim - set the right action delimiter for the template and all nested
	// templates to the specified string. Defaults to "{{"
	RDelim string

	// MissingKey controls the behavior during execution if a map is indexed with a key that is not present in the map
	MissingKey string
}

RenderOptions - options for controlling how templates are rendered, and what data are available.

type Renderer

type Renderer interface {
	// RenderTemplates renders a list of templates, parsing each template's
	// Text and executing it, outputting to its Writer. If a template's Writer
	// is a non-[os.Stdout] [io.Closer], it will be closed after the template is
	// rendered.
	RenderTemplates(ctx context.Context, templates []Template) error

	// Render is a convenience method for rendering a single template. For more
	// than one template, use [Renderer.RenderTemplates]. If wr is a non-[os.Stdout]
	// [io.Closer], it will be closed after the template is rendered.
	Render(ctx context.Context, name, text string, wr io.Writer) error
}

Renderer provides gomplate's core template rendering functionality. See NewRenderer.

Example

ctx := context.Background()

// create a new template renderer
tr := NewRenderer(RenderOptions{})

// render a template to stdout
err := tr.Render(ctx, "mytemplate",
	`{{ "hello, world!" | toUpper }}`,
	os.Stdout)
if err != nil {
	fmt.Println("gomplate error:", err)
}

Output:

HELLO, WORLD!

Example (Datasources)

ctx := context.Background()

// a datasource that retrieves JSON from a public API
u, _ := url.Parse("https://ipinfo.io/1.1.1.1")
tr := NewRenderer(RenderOptions{
	Context: map[string]DataSource{
		"info": {URL: u},
	},
})

err := tr.Render(ctx, "jsontest",
	`{{"\U0001F30E"}} {{ .info.hostname }} is served by {{ .info.org }}`,
	os.Stdout)
if err != nil {
	panic(err)
}

Output:

🌎 one.one.one.one is served by AS13335 Cloudflare, Inc.

Example (ManyTemplates)

ctx := context.Background()

// create a new template renderer
tr := NewRenderer(RenderOptions{})

templates := []Template{
	{
		Name:   "one.tmpl",
		Text:   `contents of {{ tmpl.Path }}`,
		Writer: &bytes.Buffer{},
	},
	{
		Name:   "two.tmpl",
		Text:   `{{ "hello world" | toUpper }}`,
		Writer: &bytes.Buffer{},
	},
	{
		Name:   "three.tmpl",
		Text:   `1 + 1 = {{ math.Add 1 1 }}`,
		Writer: &bytes.Buffer{},
	},
}

// render the templates
err := tr.RenderTemplates(ctx, templates)
if err != nil {
	panic(err)
}

for _, t := range templates {
	fmt.Printf("%s: %s\n", t.Name, t.Writer.(*bytes.Buffer).String())
}

Output:

one.tmpl: contents of one.tmpl
two.tmpl: HELLO WORLD
three.tmpl: 1 + 1 = 2

func NewRenderer

func NewRenderer(opts RenderOptions) Renderer

NewRenderer creates a new template renderer with the specified options. The returned renderer can be reused, but it is not (yet) safe for concurrent use.

Experimental: subject to breaking changes before the next major release

type Template

type Template struct {
	// Writer is the writer to output the rendered template to. If this writer
	// is a non-os.Stdout io.Closer, it will be closed after the template is
	// rendered.
	Writer io.Writer
	// Name is the name of the template - used for error messages
	Name string
	// Text is the template text
	Text string
}

Template contains the basic data needed to render a template with a Renderer