hcl2: github.com/hashicorp/hcl2/ext/userfunc Index | Files

package userfunc

import "github.com/hashicorp/hcl2/ext/userfunc"

Package userfunc implements a HCL extension that allows user-defined functions in HCL configuration.

Using this extension requires some integration effort on the part of the calling application, to pass any declared functions into a HCL evaluation context after processing.

The function declaration syntax looks like this:

function "foo" {
  params = ["name"]
  result = "Hello, ${name}!"

When a user-defined function is called, the expression given for the "result" attribute is evaluated in an isolated evaluation context that defines variables named after the given parameter names.

The block name "function" may be overridden by the calling application, if that default name conflicts with an existing block or attribute name in the application.


Package Files

decode.go doc.go public.go

func DecodeUserFunctions Uses

func DecodeUserFunctions(body hcl.Body, blockType string, context ContextFunc) (funcs map[string]function.Function, remain hcl.Body, diags hcl.Diagnostics)

DecodeUserFunctions looks for blocks of the given type in the given body and, for each one found, interprets it as a custom function definition.

On success, the result is a mapping of function names to implementations, along with a new body that represents the remaining content of the given body which can be used for further processing.

The result expression of each function is parsed during decoding but not evaluated until the function is called.

If the given ContextFunc is non-nil, it will be called to obtain the context in which the function result expressions will be evaluated. If nil, or if it returns nil, the result expression will have access only to variables named after the declared parameters. A non-nil context turns the returned functions into closures, bound to the given context.

If the returned diagnostics set has errors then the function map and remain body may be nil or incomplete.

type ContextFunc Uses

type ContextFunc func() *hcl.EvalContext

A ContextFunc is a callback used to produce the base EvalContext for running a particular set of functions.

This is a function rather than an EvalContext directly to allow functions to be decoded before their context is complete. This will be true, for example, for applications that wish to allow functions to refer to themselves.

The simplest use of a ContextFunc is to give user functions access to the same global variables and functions available elsewhere in an application's configuration language, but more complex applications may use different contexts to support lexical scoping depending on where in a configuration structure a function declaration is found, etc.

Package userfunc imports 3 packages (graph). Updated 2018-02-12. Refresh now. Tools for package owners.