Allow for user defined functions
Signed-off-by: Patrick Van Stee <patrick@vanstee.me>pull/192/head
Patrick Van Stee
5 years ago
parent
10d4b7a878
commit
870b38837b
@ -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).
|
||||
@ -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
|
||||
}
|
||||
@ -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
|
||||
@ -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)
|
||||
}
|
||||
Loading…
Reference in New Issue