hcl2: github.com/hashicorp/hcl2/ext/transform Index | Files

package transform

import "github.com/hashicorp/hcl2/ext/transform"

Package transform is a helper package for writing extensions that work by applying transforms to bodies.

It defines a type for body transformers, and then provides utilities in terms of that type for working with transformers, including recursively applying such transforms as heirarchical block structures are extracted.


Package Files

doc.go error.go transform.go transformer.go

func BodyWithDiagnostics Uses

func BodyWithDiagnostics(body hcl.Body, diags hcl.Diagnostics) hcl.Body

BodyWithDiagnostics returns a hcl.Body that wraps another hcl.Body and emits the given diagnostics for any content-extraction method.

Unlike the result of NewErrorBody, a body with diagnostics still runs the extraction actions on the underlying body if (and only if) the given diagnostics do not contain errors, but prepends the given diagnostics with any diagnostics produced by the action.

If the given diagnostics is empty, the given body is returned verbatim.

This function is intended for conveniently reporting errors and/or warnings produced during a transform, ensuring that they will be seen when the caller eventually extracts content from the returned body.

func Deep Uses

func Deep(body hcl.Body, transformer Transformer) hcl.Body

Deep applies the given transform to the given body and then wraps the result such that any descendent blocks that are decoded will also have the transform applied to their bodies.

This allows for language extensions that define a particular block type for a particular body and all nested blocks within it.

Due to the wrapping behavior, the body resulting from this function will not be of the type returned by the transformer. Callers may call only the methods defined for interface hcl.Body, and may not type-assert to access other methods.

func NewErrorBody Uses

func NewErrorBody(diags hcl.Diagnostics) hcl.Body

NewErrorBody returns a hcl.Body that returns the given diagnostics whenever any of its content-access methods are called.

The given diagnostics must have at least one diagnostic of severity hcl.DiagError, or this function will panic.

This can be used to prepare a return value for a Transformer that can't complete due to an error. While the transform itself will succeed, the error will be returned as soon as a caller attempts to extract content from the resulting body.

func Shallow Uses

func Shallow(body hcl.Body, transformer Transformer) hcl.Body

Shallow is equivalent to calling transformer.TransformBody(body), and is provided only for completeness of the top-level API.

type Transformer Uses

type Transformer interface {
    TransformBody(hcl.Body) hcl.Body

A Transformer takes a given body, applies some (possibly no-op) transform to it, and returns the new body.

It must _not_ mutate the given body in-place.

The transform call cannot fail, but it _can_ return a body that immediately returns diagnostics when its methods are called. NewErrorBody is a utility to help with this.

func Chain Uses

func Chain(c []Transformer) Transformer

Chain takes a slice of transformers and returns a single new Transformer that applies each of the given transformers in sequence.

type TransformerFunc Uses

type TransformerFunc func(hcl.Body) hcl.Body

TransformerFunc is a function type that implements Transformer.

func (TransformerFunc) TransformBody Uses

func (f TransformerFunc) TransformBody(in hcl.Body) hcl.Body

TransformBody is an implementation of Transformer.TransformBody.

Package transform imports 1 packages (graph) and is imported by 2 packages. Updated 2018-12-22. Refresh now. Tools for package owners.