userfunc

README

HCL User Functions Extension

This HCL extension allows a calling application to support user-defined functions.

Functions are defined via a specific block type, like this:

function "add" {
  params = [a, b]
  result = a + b
}

function "list" {
  params         = []
  variadic_param = items
  result         = items
}

The extension is implemented as a pre-processor for cty.Body objects. Given a body that may contain functions, the DecodeUserFunctions function searches for blocks that define functions and returns a functions map suitable for inclusion in a hcl.EvalContext. It also returns a new cty.Body that contains the remainder of the content from the given body, allowing for further processing of remaining content.

For more information, see the godoc reference.

Documentation

Overview

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.

Index

• func DecodeUserFunctions(body hcl.Body, blockType string, context ContextFunc) (funcs map[string]function.Function, remain hcl.Body, diags hcl.Diagnostics)
• func NewFunction(paramsExpr, varParamExpr, resultExpr hcl.Expression, ...) (function.Function, hcl.Diagnostics)
• type ContextFunc

Functions

func DecodeUserFunctions

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.

func NewFunction

func NewFunction(paramsExpr, varParamExpr, resultExpr hcl.Expression, getBaseCtx func() *hcl.EvalContext) (function.Function, hcl.Diagnostics)

NewFunction creates a new function instance from preparsed HCL expressions.

Types

type ContextFunc

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.