include

Documentation

Overview

Package include implements a HCL extension that allows inclusion of one HCL body into another using blocks of type "include", with the following structure:

include {
  path = "./foo.hcl"
}

The processing of the given path is delegated to the calling application, allowing it to decide how to interpret the path and which syntaxes to support for referenced files.

Index

• func Transformer(blockType string, ctx *hcl.EvalContext, resolver Resolver) transform.Transformer
• type Resolver
  • func FileResolver(baseDir string, parser *hclparse.Parser) Resolver
  • func MapResolver(m map[string]hcl.Body) Resolver
• type ResolverFunc
  • func (f ResolverFunc) ResolveBodyPath(path string, refRange hcl.Range) (hcl.Body, hcl.Diagnostics)

Functions

func Transformer

func Transformer(blockType string, ctx *hcl.EvalContext, resolver Resolver) transform.Transformer

Transformer builds a transformer that finds any "include" blocks in a body and produces a merged body that contains the original content plus the content of the other bodies referenced by the include blocks.

blockType specifies the type of block to interpret. The conventional type name is "include".

ctx provides an evaluation context for the path expressions in include blocks. If nil, path expressions may not reference variables nor functions.

The given resolver is used to translate path strings (after expression evaluation) into bodies. FileResolver returns a reasonable implementation for applications that read configuration files from local disk.

The returned Transformer can either be used directly to process includes in a shallow fashion on a single body, or it can be used with transform.Deep (from the sibling transform package) to allow includes at all levels of a nested block structure:

transformer = include.Transformer("include", nil, include.FileResolver(".", parser))
body = transform.Deep(body, transformer)
// "body" will now have includes resolved in its own content and that
// of any descendent blocks.

Types

type Resolver

type Resolver interface {
	ResolveBodyPath(path string, refRange hcl.Range) (hcl.Body, hcl.Diagnostics)
}

A Resolver maps an include path (an arbitrary string, but usually something filepath-like) to a hcl.Body.

The parameter "refRange" is the source range of the expression in the calling body that provided the given path, for use in generating "invalid path"-type diagnostics.

If the returned body is nil, it will be ignored.

Any returned diagnostics will be emitted when content is requested from the final composed body (after all includes have been dealt with).

func FileResolver

func FileResolver(baseDir string, parser *hclparse.Parser) Resolver

FileResolver creates and returns a Resolver that interprets include paths as filesystem paths relative to the calling configuration file.

When an include is requested, the source filename of the calling config file is first interpreted relative to the given basePath, and then the path given in configuration is interpreted relative to the resulting absolute caller configuration directory.

This resolver assumes that all calling bodies are loaded from local files and that the paths to these files were correctly provided to the parser, either absolute or relative to the given basePath.

If the path given in configuration ends with ".json" then the referenced file is interpreted as JSON. Otherwise, it is interpreted as HCL native syntax.

func MapResolver

func MapResolver(m map[string]hcl.Body) Resolver

MapResolver returns a Resolver that consults the given map for preloaded bodies (the values) associated with static include paths (the keys).

An error diagnostic is returned if a path is requested that does not appear as a key in the given map.

type ResolverFunc

type ResolverFunc func(path string, refRange hcl.Range) (hcl.Body, hcl.Diagnostics)

ResolverFunc is a function type that implements Resolver.

func (ResolverFunc) ResolveBodyPath

func (f ResolverFunc) ResolveBodyPath(path string, refRange hcl.Range) (hcl.Body, hcl.Diagnostics)

ResolveBodyPath is an implementation of Resolver.ResolveBodyPath.