# Function Aliases

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.

{% hint style="info" %}
This feature is crucial for migrating from Sprig v3.2.3 or when upgrading between Sprout versions.
{% endhint %}

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:

<pre class="language-go"><code class="lang-go"><strong>handler:= sprout.New(sprout.WithAlias("newFunc", "oldFunc"))
</strong>
template.New("base").Funcs(handler.Build()).Parse("{{ newFunc }}")
</code></pre>

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:

<pre class="language-go"><code class="lang-go"><strong>handler := sprout.New(sprout.WithAlias("newFunc", "oldFunc", "secondAlias"))
</strong></code></pre>

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:

```go
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 registry](/sprout/advanced/how-to-create-a-registry.md)page.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.atom.codes/sprout/features/function-aliases.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.