---

Official Documentation

---

Sprout was born out of the need for a modernized, maintained, and performant template function library. Sprig, the predecessor to Sprout, had not seen updates for two years and was not optimized for later versions of Golang. Sprout aims to fill this gap by providing a library that is actively maintained, compatible with the latest Go versions, and optimized for performance.

You can track our progress towards Sprout v1.0 by following the documentation page here.

• Motivation
• Roadmap to Sprout v1.0
• Transitioning from Sprig
• Usage
  • Creating a Handler
  • Customizing the Handler
  • Working with Registries
  • Building Function Maps
  • Working with Templates
• Usage: Quick Example (code only)
• Performence Benchmarks
  • Sprig v3.2.3 vs Sprout v0.2
• Development Philosophy (Currently in reflexion to create our)

Sprout provide a package sprigin to provide a drop-in replacement for Sprig in the v1.0, with the same function names and behavior. To use Sprout in your project, simply replace the Sprig import with sprigin:

import (
-  "github.com/Masterminds/sprig/v3"
+  "github.com/go-sprout/sprout/sprigin"
)

tpl := template.Must(
  template.New("base").
-   Funcs(sprig.FuncMap()).
+   Funcs(sprigin.FuncMap()).
    ParseGlob("*.tmpl")
)

A handler in Sprout is responsible for managing the function registries and functions. The DefaultHandler is the primary implementation provided by Sprout.

import "github.com/go-sprout/sprout"

handler := sprout.New()

Sprout supports various customization options using handler options:

handler := sprout.New(
  // Add your logger to the handler to log errors and debug information using the
  // standard slog package or any other logger that implements the slog.Logger interface.
  // By default, Sprout uses a slog.TextHandler.
  sprout.WithLogger(slogLogger),
  // Set the alias for a function. By default, Sprout use alias for some functions for backward compatibility with Sprig.
  sprout.WithAlias("hello", "hi"),
)

Registries in Sprout are groups of functions that can be added to a handler. They help organize functions and optimize template performance.

You can retrieve all built-ins registries and functions under Registries.

import (
  "github.com/go-sprout/sprout/registry/conversion" // toString, toInt, toBool, ...
  "github.com/go-sprout/sprout/registry/std" // default, empty, any, all, ...
)

//...

handler.AddRegistries(
  conversion.NewRegistry(),
  std.NewRegistry(),
)

To use Sprout with templating engines like html/template or text/template, you need to build the function map:

funcs := handler.Build()
tpl := template.New("example").Funcs(funcs).Parse(`{{ hello }}`)

Once your function map is ready, you can use it to render templates:

tpl, err := template.New("example").Funcs(funcs).Parse(`{{ myFunc }}`)
if err != nil {
    log.Fatal(err)
}
tpl.Execute(os.Stdout, nil)

This will render the template with all functions and aliases available.

Here is a quick example of how to use Sprout with the text/template package:

package main

import (
	"os"
	"text/template"

	"github.com/go-sprout/sprout"
	"github.com/go-sprout/sprout/registry/std"
)

func main() {
	handler := sprout.New()
	handler.AddRegistry(std.NewRegistry())

	tpl := template.Must(
    template.New("example").Funcs(handler.Build()).Parse(`{{ hello }}`),
  )
	tpl.Execute(os.Stdout, nil)
}

To see all the benchmarks, please refer to the benchmarks directory.

goos: linux
goarch: amd64
pkg: sprout_benchmarks
cpu: Intel(R) Core(TM) i9-9900K CPU @ 3.60GHz
BenchmarkSprig-16              1        2991811373 ns/op        50522680 B/op      32649 allocs/op
BenchmarkSprout-16             1        1638797544 ns/op        42171152 B/op      18061 allocs/op
PASS
ok      sprout_benchmarks       4.921s

Time improvement: ((2991811373 - 1638797544) / 2991811373) * 100 = 45.3% Memory improvement: ((50522680 - 42171152) / 50522680) * 100 = 16.5%

So, Sprout v0.5 is approximately 45.3% faster and uses 16.5% less memory than Sprig v3.2.3. 🚀

You can see the full benchmark results here.

Our approach to extending and refining Sprout was guided by several key principles:

• Build on the principles of simplicity, flexibility, and consistency.
• Empower developers to create robust templates without sacrificing performance or usability.
• Adheres strictly to Go's templating conventions, ensuring a seamless experience for those familiar with Go's native tools.
• Naming conventions across functions are standardized for predictability and ease of use.
• Emphasizes error handling, preferring safe defaults over panics.
• Provide a clear and comprehensive documentation to help users understand the library and its features.
• Maintain a high level of code quality, ensuring that the library is well-tested, performant, and reliable.
• Continuously improve and optimize the library to meet the needs of the community.
• Avoids any external dependencies within template functions, ensuring all operations are self-contained and reliable.
• Performance is a key consideration, with a focus on optimizing the library for speed and efficiency.