fasttemplate

fasttemplate is a high-performance Go template engine designed for a single task: substituting template placeholders with user-defined values.

Key Characteristics

• Performance: It is significantly faster than text/template, strings.Replace, strings.Replacer, and fmt.Fprintf for placeholder substitution.
• No Escaping: Unlike html/template, it performs no automatic escaping. You are responsible for escaping data (e.g., HTML or URL escaping) before substitution.
• Use Case: Use it when you need maximum speed for simple string interpolation. If you need a powerful HTML template engine with automatic security features, use quicktemplate instead.

Choosing the right method depends on whether your template string is static or dynamic:

1. Frozen Templates (High Performance):

   • Use the *Template type.
   • First, call fasttemplate.New() or fasttemplate.NewTemplate() to parse the template.
   • Then, call t.Execute* methods.
   • Why? The template is pre-parsed into segments and tags, so execution only involves writing those segments and looking up tags in the map.

2. Constantly Changing Templates (Low Overhead for single use):

   • Use the package-level functions like fasttemplate.ExecuteString().
   • Why? Creating a Template object involves allocation and parsing. If you only use a template once before it changes, the overhead of creating a Template object is higher than just parsing it on the fly.

For simple placeholder substitution using a map of values, use fasttemplate.New. You specify the template string and the start and end delimiters (e.g., {{ and }}). Use ExecuteString to perform the substitution using a map[string]interface{}.

Important: fasttemplate does not perform any escaping (like html/template does). You must manually escape values (e.g., using url.QueryEscape) before passing them to the template engine to prevent injection or malformed output.

	template := "http://{{host}}/?q={{query}}&foo={{bar}}{{bar}}"
	t := fasttemplate.New(template, "{{", "}}")
	s := t.ExecuteString(map[string]interface{}{
		"host":  "google.com",
		"query": url.QueryEscape("hello=world"),
		"bar":   "foobar",
	})
	fmt.Printf("%s", s)

	// Output:
	// http://google.com/?q=hello%3Dworld&foo=foobarfoobar

To use fasttemplate efficiently, you should first parse your template string into a Template object. This pre-parses the template, making subsequent executions much faster.

• New(template, startTag, endTag): Parses the template. Panics if the template cannot be parsed (e.g., if an end tag is missing).
• NewTemplate(template, startTag, endTag): Parses the template and returns an error instead of panicking if parsing fails.

Once created, a Template object can be executed concurrently by multiple goroutines.

import "github.com/valyala/fasttemplate"

template := "Hello {{name}}!"
// Using New (panics on error)
t, err := fasttemplate.NewTemplate(template, "{{", "}}")
if err != nil {
    // handle error
}

To avoid repeated allocations, you can reuse an existing Template object by calling Reset. This allows you to change the template string, the start tag, or the end tag.

Warning: Reset may be called only if no other goroutines are currently calling methods on that Template instance.

t, _ := fasttemplate.NewTemplate("{{a}}", "{{", "}}")

// Use it
t.ExecuteString(map[string]interface{}{"a": "first"})

// Reuse it with a new template
t.Reset("{{b}}", "{{", "}}")
t.ExecuteString(map[string]interface{}{"b": "second"})

If your template string changes frequently, do not use the Template object. Instead, use the package-level functions which are optimized for templates that are not pre-parsed.

Methods:

• Execute(template, startTag, endTag string, w io.Writer, m map[string]interface{}) (int64, error)
• ExecuteStd(template, startTag, endTag string, w io.Writer, m map[string]interface{}) (int64, error)
• ExecuteString(template, startTag, endTag string, m map[string]interface{}) string
• ExecuteStringStd(template, startTag, endTag string, m map[string]interface{}) string

// For templates that change every time
template := "Hello {{name}}"
m := map[string]interface{}{"name": "Alice"}

result := fasttemplate.ExecuteString(template, "{{", "}}", m)

A TagFunc allows you to define custom logic for how a placeholder should be processed. This is useful for complex transformations or dynamic data fetching.

type TagFunc func(w io.Writer, tag string) (int, error)

When using a Template object, use ExecuteFunc or ExecuteFuncString. When using package-level functions, use ExecuteFunc or ExecuteFuncString.

Note: TagFunc must be safe to call from concurrently running goroutines.

// Custom function to handle a tag
myFunc := func(w io.Writer, tag string) (int, error) {
    if tag == "upper" {
        _, err := w.Write([]byte("UPPERCASE"))
        return 9, err
    }
    return 0, nil
}

// Using it with a frozen template
t.ExecuteFunc(os.Stdout, myFunc)