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, d *data.Data) template.FuncMap
- func Funcs(d *data.Data) template.FuncMapdeprecated
- 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) errordeprecated
- func SetExperimental(ctx context.Context) context.Context
- type Configdeprecated
- type Datasource
- type MetricsType
- type Options
- type PluginOpts
- type Renderer
- type Template
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var DefaultFSProvider = sync.OnceValue[fsimpl.FSProvider]( 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 ¶
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 RunTemplates
deprecated
Types ¶
type Config
deprecated
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, github.com/hairyhenderson/gomplate/v4/internal/config.Config is used everywhere else, and will be exposed as API in a future version
type Datasource ¶
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 { // FSProvider - allows lookups of data source filesystems. Defaults to // [DefaultFSProvider]. FSProvider fsimpl.FSProvider // 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 // 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 // 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 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 public API u, _ := url.Parse("https://ipinfo.io/1.1.1.1") tr := NewRenderer(Options{ Context: map[string]Datasource{ "info": {URL: u}, }, }) err := tr.Render(ctx, "jsontest", `{{"\U0001F30E"}} {{ .info.hostname }} is served from {{ .info.city }}, {{ .info.region }}`, os.Stdout) if err != nil { panic(err) }
Output: 🌎 one.one.one.one is served from Los Angeles, California
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 ¶
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 ¶
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 ¶
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
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Package aws contains functions which wrap various Amazon Web Services APIs
|
Package aws contains functions which wrap various Amazon Web Services APIs |
Package base64 contains Base64 encoding/decoding functions
|
Package base64 contains Base64 encoding/decoding functions |
cmd
|
|
gomplate
The gomplate command
|
The gomplate command |
Package coll contains functions to help manipulate and query collections of data, like slices/arrays and maps.
|
Package coll contains functions to help manipulate and query collections of data, like slices/arrays and maps. |
Package conv contains functions that help converting data between different types
|
Package conv contains functions that help converting data between different types |
Package crypto contains functions to help perform hashing and simple encryption operations
|
Package crypto contains functions to help perform hashing and simple encryption operations |
Package env contains functions that retrieve data from the environment
|
Package env contains functions that retrieve data from the environment |
Package file contains functions for working with files and directories on the local filesystem
|
Package file contains functions for working with files and directories on the local filesystem |
Package funcs is an internal package that provides gomplate namespaces and functions to be used in 'text/template' templates.
|
Package funcs is an internal package that provides gomplate namespaces and functions to be used in 'text/template' templates. |
internal
|
|
parsers
Package parsers has internal parsers for various formats.
|
Package parsers has internal parsers for various formats. |
tests/integration
Package integration contains integration tests.
|
Package integration contains integration tests. |
Package math contains set of basic math functions to be able to perform simple arithmetic operations
|
Package math contains set of basic math functions to be able to perform simple arithmetic operations |
Package net contains functions to help with network-oriented lookups
|
Package net contains functions to help with network-oriented lookups |
Package random contains functions for generating random values
|
Package random contains functions for generating random values |
Package regexp contains functions for dealing with regular expressions
|
Package regexp contains functions for dealing with regular expressions |
Package strings contains functions to manipulate strings
|
Package strings contains functions to manipulate strings |
Package test contains functions to help validate assumptions and can cause template generation to fail in specific cases
|
Package test contains functions to help validate assumptions and can cause template generation to fail in specific cases |
Package time contains functions to help work with date and time
|
Package time contains functions to help work with date and time |
Package tmpl contains functions for defining or executing in-line templates.
|
Package tmpl contains functions for defining or executing in-line templates. |