hcloverlay

Documentation

Overview

Package hcloverlay is an extension to HCL for modelling "overlays", which are objects that can contribute new arguments and blocks or add new arguments and blocks to an existing HCL body.

The ability to apply overlays implies some additional constraints on the design of the underlying language in comparison to plain use of HCL, but it can be useful in situations where e.g. HCL is bein used for configuration of a system but it's also desirable to be able to override particular configuration elements via command line arguments.

The specific additional constraints implied by an overlay depend on the particular overlay implementation. See the documentation of the overlay factory functions in this package for more details.

Index

• func ApplyOverlays(body hcl.Body, overlays ...Overlay) hcl.Body
• type Overlay
  • func ExtractCLIOptions(args []string, schema *hcl.BodySchema) ([]Overlay, []string, hcl.Diagnostics)
  • func ParseCLIArgument(raw string) (Overlay, hcl.Diagnostics)

Functions

func ApplyOverlays

func ApplyOverlays(body hcl.Body, overlays ...Overlay) hcl.Body

ApplyOverlays wraps the given HCL body such that when calling the various decoding methods the result will incorporate the result of applying the given overlays.

If multiple overlays are given, they will be applied in the given order with each subsequent overlay consuming the result of the one preceding it.

When applying overlays to a body, the original body is required to be valid per the schema except that the "Required" flag for attributes is not enforced. Requiredness is instead enforced on the result of applying the overlays.

Types

type Overlay

type Overlay interface {
	// ApplyOverlay receives the result of decoding a body along with the
	// schema that was used to decode that body and produces a new body
	// that incorporates whatever additional or replacement content the
	// overlay represents.
	//
	// ApplyOverlay returns an error if the given schema does not call for
	// any of the content changes that the overlay represents. These errors
	// will usually be phrased from the perspective that the overlay itself
	// is invalid, under the assumption that the overlay is being applied
	// at the request of an end-user.
	//
	// Although conceptually this method consumes a content object and produces
	// a replacement object, in practice implementations are free to modify
	// the given object directly and return that same object in the common
	// case where the overlay changes are surgical and it would be wasteful
	// to allocate an entirely new copy.
	ApplyOverlay(content *hcl.BodyContent, schema *hcl.BodySchema) (*hcl.BodyContent, hcl.Diagnostics)

	// PartialApplyOverlay is a variant of ApplyOverlay that should apply
	// as much of its additional or replacement content as possible but
	// should, if the schema does not call for any part of that content,
	// return a new Overlay that would apply the remaining changes.
	//
	// PartialApplyOverlay will return a nil new Overlay in the case where it
	// has applied all of the changes it represents.
	PartialApplyOverlay(content *hcl.BodyContent, schema *hcl.BodySchema) (*hcl.BodyContent, Overlay, hcl.Diagnostics)

	// ApplyJustAttributes applies all of the attribute modifications
	// represented by the overlay, returning an error if any of the
	// modifications call for the addition of a block.
	//
	// Conceptually, ApplyJustAttributes constructs a synthetic schema
	// containing whatever attributes the overlay implies and no block types,
	// and then calls ApplyOverlay with that synthetic schema to overlay
	// all of the implied attributes. (Actual implementation may vary, naturally.)
	ApplyJustAttributes(attrs hcl.Attributes) (hcl.Attributes, hcl.Diagnostics)
}

An Overlay is an object that can be applied to a body using the OverlayBody function, in which case it will get an opportunity to modify the result of decoding that body, usually by adding or replacing attributes or blocks.

func ExtractCLIOptions

func ExtractCLIOptions(args []string, schema *hcl.BodySchema) ([]Overlay, []string, hcl.Diagnostics)

ExtractCLIOptions interprets the given slice as a sequence of command line arguments and identifies any that have the conventional "--" prefix for named optional arguments followed by identifiers that correspond to attributes or block types in the given schema and attempts to produce an overlay for each one using the behaviors described for ParseCLIArgument.

Additionally, if one of the arguments is literally "--" then ExtractCLIOptions will not interpret any subsequent arguments as overlays.

ExtractCLIOptions returns a sequence of overlays and a new slice of strings that contains all of the arguments from the given slice that were not interpreted as overlays, so that they might be used for further command line processing.

func ParseCLIArgument

func ParseCLIArgument(raw string) (Overlay, hcl.Diagnostics)

ParseCLIArgument expects a string consisting of a sequence of dot-separated identifiers, followed by an equals sign "=" and then a sequence of arbitrary characters.

The part before the equals sign is interpreted as a sequence of traversals through the configuration to an argument to set or override. The part after the equals sign is a string value to set the argument to.

The result is an overlay that replaces the value of the indicated argument with the given string value.

This overlay is intended to be used with HCL-based configuration languages that have the following constraints in addition to those of the HCL infoset:

• All blocks must be uniquely identified by their block type and labels. If multiple blocks appear in the same body with the same header, an override for that header will apply only to the first such block in the source configuration.

• All argument names, block types, and block labels must be valid HCL identifiers, as decided by hclsyntax.ValidIdentifier .

• All arguments that may be overridden must accept strings, either directly or as the input to a type conversion.

If the given string traverses through a block whose type is derived by the schema but that does not exist in the configuration being overridden then the overlay will create a new block with the appropriate labels that contains only the specified argument.

Argument values overridden by CLI argument overlays will have no source location information, so an application using overlays returned from this method must be prepared to accept zero-value hcl.Range values and treat them as the absense of a range if accessing the ranges associated with attributes and blocks in resulting content.