Allow for user defined functions

Signed-off-by: Patrick Van Stee <patrick@vanstee.me>

vendor/github.com/hashicorp/hcl/v2/ext/userfunc/README.md

@@ -0,0 +1,28 @@
+# 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:
+
+```hcl
+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](http://godoc.org/github.com/hashicorp/hcl/v2/ext/userfunc).

vendor/github.com/hashicorp/hcl/v2/ext/userfunc/decode.go

@@ -0,0 +1,156 @@
+package userfunc
+
+import (
+	"github.com/hashicorp/hcl/v2"
+	"github.com/zclconf/go-cty/cty"
+	"github.com/zclconf/go-cty/cty/function"
+)
+
+var funcBodySchema = &hcl.BodySchema{
+	Attributes: []hcl.AttributeSchema{
+		{
+			Name:     "params",
+			Required: true,
+		},
+		{
+			Name:     "variadic_param",
+			Required: false,
+		},
+		{
+			Name:     "result",
+			Required: true,
+		},
+	},
+}
+
+func decodeUserFunctions(body hcl.Body, blockType string, contextFunc ContextFunc) (funcs map[string]function.Function, remain hcl.Body, diags hcl.Diagnostics) {
+	schema := &hcl.BodySchema{
+		Blocks: []hcl.BlockHeaderSchema{
+			{
+				Type:       blockType,
+				LabelNames: []string{"name"},
+			},
+		},
+	}
+
+	content, remain, diags := body.PartialContent(schema)
+	if diags.HasErrors() {
+		return nil, remain, diags
+	}
+
+	// first call to getBaseCtx will populate context, and then the same
+	// context will be used for all subsequent calls. It's assumed that
+	// all functions in a given body should see an identical context.
+	var baseCtx *hcl.EvalContext
+	getBaseCtx := func() *hcl.EvalContext {
+		if baseCtx == nil {
+			if contextFunc != nil {
+				baseCtx = contextFunc()
+			}
+		}
+		// baseCtx might still be nil here, and that's okay
+		return baseCtx
+	}
+
+	funcs = make(map[string]function.Function)
+Blocks:
+	for _, block := range content.Blocks {
+		name := block.Labels[0]
+		funcContent, funcDiags := block.Body.Content(funcBodySchema)
+		diags = append(diags, funcDiags...)
+		if funcDiags.HasErrors() {
+			continue
+		}
+
+		paramsExpr := funcContent.Attributes["params"].Expr
+		resultExpr := funcContent.Attributes["result"].Expr
+		var varParamExpr hcl.Expression
+		if funcContent.Attributes["variadic_param"] != nil {
+			varParamExpr = funcContent.Attributes["variadic_param"].Expr
+		}
+
+		var params []string
+		var varParam string
+
+		paramExprs, paramsDiags := hcl.ExprList(paramsExpr)
+		diags = append(diags, paramsDiags...)
+		if paramsDiags.HasErrors() {
+			continue
+		}
+		for _, paramExpr := range paramExprs {
+			param := hcl.ExprAsKeyword(paramExpr)
+			if param == "" {
+				diags = append(diags, &hcl.Diagnostic{
+					Severity: hcl.DiagError,
+					Summary:  "Invalid param element",
+					Detail:   "Each parameter name must be an identifier.",
+					Subject:  paramExpr.Range().Ptr(),
+				})
+				continue Blocks
+			}
+			params = append(params, param)
+		}
+
+		if varParamExpr != nil {
+			varParam = hcl.ExprAsKeyword(varParamExpr)
+			if varParam == "" {
+				diags = append(diags, &hcl.Diagnostic{
+					Severity: hcl.DiagError,
+					Summary:  "Invalid variadic_param",
+					Detail:   "The variadic parameter name must be an identifier.",
+					Subject:  varParamExpr.Range().Ptr(),
+				})
+				continue
+			}
+		}
+
+		spec := &function.Spec{}
+		for _, paramName := range params {
+			spec.Params = append(spec.Params, function.Parameter{
+				Name: paramName,
+				Type: cty.DynamicPseudoType,
+			})
+		}
+		if varParamExpr != nil {
+			spec.VarParam = &function.Parameter{
+				Name: varParam,
+				Type: cty.DynamicPseudoType,
+			}
+		}
+		impl := func(args []cty.Value) (cty.Value, error) {
+			ctx := getBaseCtx()
+			ctx = ctx.NewChild()
+			ctx.Variables = make(map[string]cty.Value)
+
+			// The cty function machinery guarantees that we have at least
+			// enough args to fill all of our params.
+			for i, paramName := range params {
+				ctx.Variables[paramName] = args[i]
+			}
+			if spec.VarParam != nil {
+				varArgs := args[len(params):]
+				ctx.Variables[varParam] = cty.TupleVal(varArgs)
+			}
+
+			result, diags := resultExpr.Value(ctx)
+			if diags.HasErrors() {
+				// Smuggle the diagnostics out via the error channel, since
+				// a diagnostics sequence implements error. Caller can
+				// type-assert this to recover the individual diagnostics
+				// if desired.
+				return cty.DynamicVal, diags
+			}
+			return result, nil
+		}
+		spec.Type = func(args []cty.Value) (cty.Type, error) {
+			val, err := impl(args)
+			return val.Type(), err
+		}
+		spec.Impl = func(args []cty.Value, retType cty.Type) (cty.Value, error) {
+			return impl(args)
+		}
+		funcs[name] = function.New(spec)
+	}
+
+	return funcs, remain, diags
+}

vendor/github.com/hashicorp/hcl/v2/ext/userfunc/doc.go

@@ -0,0 +1,22 @@
+// 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 userfunc

vendor/github.com/hashicorp/hcl/v2/ext/userfunc/public.go

@@ -0,0 +1,42 @@
+package userfunc
+
+import (
+	"github.com/hashicorp/hcl/v2"
+	"github.com/zclconf/go-cty/cty/function"
+)
+
+// 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.
+type ContextFunc func() *hcl.EvalContext
+
+// 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 DecodeUserFunctions(body hcl.Body, blockType string, context ContextFunc) (funcs map[string]function.Function, remain hcl.Body, diags hcl.Diagnostics) {
+	return decodeUserFunctions(body, blockType, context)
+}

vendor/modules.txt

@@ -212,6 +212,7 @@ github.com/hashicorp/golang-lru/simplelru
 # github.com/hashicorp/hcl/v2 v2.4.0
 github.com/hashicorp/hcl/v2
 github.com/hashicorp/hcl/v2/ext/customdecode
+github.com/hashicorp/hcl/v2/ext/userfunc
 github.com/hashicorp/hcl/v2/gohcl
 github.com/hashicorp/hcl/v2/hclsimple
 github.com/hashicorp/hcl/v2/hclsyntax