search

go-sprout / sprout

From sprig to sprout - Useful template functions for Go templates with steroids
https://sprout.atom.codes
MIT License
98 stars 5 forks source link
go golang hacktoberfest sprig sprout template templates

readme

Sprout Logo
Code Climate maintainability Codecov GitHub release (latest by date) GitHub contributors GitHub Repo stars Go Reference

Official Documentation

[!NOTE] Sprout is an evolved variant of the Masterminds/sprig library, reimagined for modern Go versions. It introduces fresh functionalities and commits to maintaining the library, picking up where Sprig left off. Notably, Sprig had not seen updates for two years and was not compatible beyond Golang 1.13, necessitating the creation of Sprout.

Motivation

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.

Roadmap to Sprout v1.0

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

Table of Contents

Transitioning from Sprig

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:

[!IMPORTANT] The sprigin package is a temporary solution to provide backward compatibility with Sprig. We recommend updating your code to use the Sprout package directly to take advantage of the new features and improvements.

A complete guide is available in the documentation.

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")
)

Usage

Creating a Handler

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()

Customizing the Handler

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"),
)

Working with Registries

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-in 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(),
)

Working with Registries Groups

In some cases, you can use a group of registries to add multiple registries at once.

You can retrieve all built-in registries groups under Registry Groups.

import (
  "github.com/go-sprout/sprout/group/all"
)

//...

handler.AddGroup(
  all.RegistryGroup(),
)

Building Function Maps

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 }}`)

Working with Templates

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.

Usage: Quick Example

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)
}

Performance Benchmarks

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

Sprig v3.2.3 vs Sprout v0.5

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.

Development Philosophy (Currently in consideration to create ours)

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