Sprout Template Function Library

A Registry is a modular collection of functions designed to improve build efficiency and maintainability. Instead of importing a monolithic library, you can use registries to:

• Optimize Build Time: Only include the specific functions you need, reducing binary size.
• Promote Reusability: Share function collections across multiple projects as Go packages.
• Enable Collaboration: Easily incorporate registries contributed by other developers.
• Manage Versioning: Treat registries as versioned Go packages to ensure consistency.

A RegistryGroup is a struct that allows you to group multiple registries together. This enables you to manage collections of registries as a single unit, promoting modularity and cleaner code organization within a Handler.

Warning: When using RegistryGroup, ensure you review the functions contained within each registry in the group to avoid registering undesired functions or causing unexpected behavior due to conflicts.

The Handler interface is the core abstraction in Sprout used to manage function registries, logging, and error handling. To create a custom handler, you must implement the following methods:

• Logger() *slog.Logger: Returns the logger instance used for logging.
• AddRegistry(registry Registry) error: Adds a single registry to the handler.
• AddRegistries(registries ...Registry) error: Adds multiple registries to the handler.
• RawFunctions() FunctionMap: Returns the map of registered functions.
• RawAliases() FunctionAliasMap: Returns the map of function aliases.
• Build() FunctionMap: Builds and returns the complete function map, ready to be used in templates.

The dig function has two major behavioral differences in Sprout:

1. Argument Order/Default Value: In Sprig, the default value is the second-to-last argument. In Sprout, use the pipe syntax and the default filter separately.
2. Key Resolution: In Sprig, dots in keys are treated literally (e.g., dig "a.b" looks for a key named exactly "a.b"). In Sprout, keys are split on dots (e.g., dig "a.b" is equivalent to dig "a" "b").

// Sprig
{{ dig "key1" "key2" "default" $dict }}

// Sprout
{{ $dict | dig "key1" "key2" | default "default" }}

A Handler is the central component in Sprout responsible for managing function registries and functions. The DefaultHandler is the primary implementation. You use a handler to organize functions into registries and eventually build a FuncMap compatible with Go's text/template or html/template engines.

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

handler := sprout.New()

The append and prepend functions add elements to a list.

Important: These functions do not modify the original list in place; they return a new list. When using them within a loop (like a range), you must assign the result back to your variable to accumulate changes.

// To accumulate in a range, assign the result back:
{{- $stages := list -}}
{{- range .Stages -}}
  {{- $stages = $stages | append .Name -}}
{{- end -}}

When creating registries, follow these naming rules:

• Package Names: Use short, concise, singular nouns (e.g., util instead of utils). Exceptions include strings, slices, and maps to maintain consistency with the Go standard library.
• UIDs: The Unique Identifier (UID) for a repository must be in camelCase and prefixed with your name or organization, separated by a dot (e.g., 42atomys.myRegistry).
• Documentation: Every package must include a README or a comment providing a brief overview of its purpose.

Sprout provides three types of notices via NoticeKind, each mapped to a specific slog level:

Info

Linked to slog.InfoLevel. Used for purely informational messages.

Debug

Linked to slog.DebugLevel. Useful for template debugging. You can use the $out placeholder in the message, which will be replaced by the actual output of the function.

Deprecated

Indicates a function should be replaced. When triggered, it writes to the warning logger with a message indicating the function is deprecated and suggesting an alternative.

// Info notice
sprout.NewInfoNotice("toLower", "This is an informative notice")

// Debug notice with $out placeholder
sprout.NewDebugNotice("toLower", "toLower result are $out")

// Deprecated notice
sprout.NewDeprecatedNotice("int", "please use `toInt` instead")