Function Aliases

Need two names for one function in your code? Aliases are the solution.

The function aliasing feature introduces a seamless way for developers to maintain backward compatibility while transitioning to new function names in their codebases. This mechanism is designed to ensure that older code remains functional without immediate modifications, even as the library evolves.

This feature is crucial for migrating from Sprig v3.2.3 or when upgrading between Sprout versions.

To configure aliases, you must use the Sprout function handler.

How It Works

• Definition: An alias behaves as a secondary name for a function, referring to the original implementation in memory, the function is not duplicated at runtime.

• Usage: When the deprecated (aliased) function names are used, the code behaves as if the new function names were called, ensuring compatibility.

• Example: Suppose oldFunc is deprecated in favor of newFunc in your template. The alias allows code calling oldFunc to execute newFunc transparently.

Usage

Add one alias

To use the function aliases feature, you just need to use the configuration function WithAlias() as shown below:

handler:= sprout.New(sprout.WithAlias("newFunc", "oldFunc"))

template.New("base").Funcs(handler.Build()).Parse("{{ newFunc }}")

This creates a mapping between an old function name (oldFunc) and a new one (newFunc). Calls to oldFunc within the template are redirected to execute newFunc. This enables the template to parse and execute using the new function name seamlessly.

Add more than one aliases for the same function

To add more aliases for the same original function, simply add more parameters to the WithAlias function:

handler := sprout.New(sprout.WithAlias("newFunc", "oldFunc", "secondAlias"))

This creates two aliases for the function newFunc. Calling oldFunc or secondAlias will execute newFunc.

Add aliases for multiples function at once

To map multiple functions, use the same strategy we use for backward compatibility with Sprig by creating a FunctionAliasMap and injecting it into your Function Handler with the WithAliases function:

var myAliases = sprout.FunctionAliasMap{
	"newFunc": {"oldFunc", "secondAlias"},
	"hello":   {"hi", "greet"},
}

handler := sprout.New(sprout.WithAliases(myAliases))

This creates two aliases for two methods (4 in total). Calling oldFunc or secondAlias with execute newFunc and calling hi or greet will execute hello.

Best Practices

• Documentation: Clearly document all aliases on your codebase to avoid confusion.

• Deprecation Notices: Use comments or documentation to inform users of deprecated functions and encourage the adoption of new names.

• Gradual Transition: Allow a transition period where both old and new function names are supported. For my projects, I use a version frame of 5 minors or 1 major, if this can guide you.

Add aliases on your registry

To add aliases on your registry, see How to create a registrypage.