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, BoltDB, 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-2021 Dave Henderson

Documentation

Overview

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

Index

• func ContextWithFSProvider(ctx context.Context, fsp fsimpl.FSProvider) context.Context
• func CreateFuncs(ctx context.Context, d *data.Data) template.FuncMap
• func FSProviderFromContext(ctx context.Context) fsimpl.FSProvider
• func Funcs(d *data.Data) template.FuncMap
• func PluginFunc(ctx context.Context, cmd string, opts PluginOpts) func(...interface{}) (interface{}, error)
• func Run(ctx context.Context, cfg *config.Config) error
• func RunTemplates(o *Config) error
• func SetExperimental(ctx context.Context) context.Context
• type Config
  • func (o *Config) String() string
• type Datasource
• type MetricsType
• type Options
• type PluginOpts
• type Renderer
  • func NewRenderer(opts Options) *Renderer
  • func (t *Renderer) Render(ctx context.Context, name, text string, wr io.Writer) error
  • func (t *Renderer) RenderTemplates(ctx context.Context, templates []Template) error
• type Template

Examples

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

Functions

func ContextWithFSProvider

func ContextWithFSProvider(ctx context.Context, fsp fsimpl.FSProvider) context.Context

ContextWithFSProvider returns a context with the given FSProvider. Should only be used in tests.

func CreateFuncs

func CreateFuncs(ctx context.Context, d *data.Data) template.FuncMap

CreateFuncs - function mappings are created here

func FSProviderFromContext

func FSProviderFromContext(ctx context.Context) fsimpl.FSProvider

FSProviderFromContext returns the FSProvider from the context, if any

func Funcs

func Funcs(d *data.Data) template.FuncMap

Funcs - Deprecated: use CreateFuncs instead

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.Config) error

Run all gomplate templates specified by the given configuration

func RunTemplates

func RunTemplates(o *Config) error

RunTemplates - run all gomplate templates specified by the given configuration

Deprecated: use the Renderer interface instead

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 {
	Input       string
	InputFiles  []string
	InputDir    string
	ExcludeGlob []string
	OutputFiles []string
	OutputDir   string
	OutputMap   string
	OutMode     string
	Out         io.Writer

	DataSources       []string
	DataSourceHeaders []string
	Contexts          []string

	Plugins []string

	LDelim string
	RDelim string

	Templates []string
}

Config - values necessary for rendering templates with gomplate. Mainly for use by the CLI

Deprecated: this type will be phased out, internal/config.Config is used everywhere else, and will be exposed as API in a future version

func (*Config) String

func (o *Config) String() string

nolint: gocyclo

type Datasource

type Datasource struct {
	URL    *url.URL
	Header http.Header
}

Datasource - a datasource URL with optional headers

Experimental: subject to breaking changes before the next major release

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 Options

type Options 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

	// Experimental - enable experimental features
	Experimental bool
}

Options for template rendering.

Experimental: subject to breaking changes before the next major release

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

	// 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 Renderer

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

Renderer provides gomplate's core template rendering functionality. It should be initialized with NewRenderer.

Experimental: subject to breaking changes before the next major release

Example

ctx := context.Background()

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

// 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 maritime registry dataset
u, _ := url.Parse("https://www.econdb.com/maritime/vessel/9437/")
tr := NewRenderer(Options{
	Context: map[string]Datasource{
		"vessel": {URL: u},
	},
})

err := tr.Render(ctx, "jsontest",
	`{{"\U0001F6A2"}} The {{ .vessel.data.Name }}'s call sign is {{ .vessel.data.Callsign }}, `+
		`and it has a draught of {{ .vessel.data.Draught }}.`,
	os.Stdout)
if err != nil {
	panic(err)
}

Example (ManyTemplates)

ctx := context.Background()

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

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 Options) *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

func (*Renderer) Render

func (t *Renderer) Render(ctx context.Context, name, text string, wr io.Writer) error

Render is a convenience method for rendering a single template. For more than one template, use RenderTemplates. If wr is a non-os.Stdout io.Closer, it will be closed after the template is rendered.

Experimental: subject to breaking changes before the next major release

func (*Renderer) RenderTemplates

func (t *Renderer) RenderTemplates(ctx context.Context, templates []Template) error

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.

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

Experimental: subject to breaking changes before the next major release