hcl2yaml

README

hcl2yaml

YAML syntax for HashiCorp Configuration Language Version 2

hcl2yaml is a go library that provides a YAML syntax for HCL2. It's basically an equivalent to HCL2's own JSON syntax, but for YAML.

The upstream HCL2 has both a native syntax for human and a JSON-based variant for machines. hcl2yaml adds one more variant for human.

The goal of hcl2yaml is to provide a solid foundation for building rich YAML-based DSLs with custom functions and variables.

Usage

Here's an example to show you the basic usage of the library.

Please also see integration/gohcl_integration_test.go for more concrete and working examples.

type Example struct {
	// Use the HCl2's native field tag `hcl:"..."` for mapping between HCL <-> Go
	Ary1 []map[string]string `hcl:"ary1,attr"`
	Ary2 []map[string]string `hcl:"ary2,attr"`
	Map1 map[string]string    `hcl:"map1,attr"`
	Map2 map[string]string    `hcl:"map2,attr"`
	Str1 string               `hcl:"str1,attr"`
	Int1 int                  `hcl:"int1,attr"`
}

yamlSource := `
# HCL2 and hcl2yaml is context-dependent.
# That is, the value for a array field can be any "expression" that evaluates to a YAML array.

# In the first array example, we only use a HCL expression in the value of the YAML hash in the array.
ary1:
# A YAML string is considered a HCL2's native "template" in which you can use the interpolation syntax.
# In the below example, "x${var.one}y" evaluates to "xONEy" when the variable `var.one` is set to `ONE` in the HCL2 eval context.
- a: "x${var.one}y"

# Unlike the JSON syntax, you can use HCL2 expression to build the whole array.
# Just prepend a YAML tag `!!exp` before starting a string of the expression
# In the below example, you call Terraform's "list" and "map" functions to build the array.
#
# See also:
# list: https://www.terraform.io/docs/configuration/functions/list.html
# map: https://www.terraform.io/docs/configuration/functions/map.html
# HCL2 Expression: https://github.com/hashicorp/hcl2/blob/master/hcl/hclsyntax/spec.md#expressions
ary2: !!exp list(map("a", "x${var.one}y"))

map1:
  foo: "x${var.one}y"

map2: !!exp map("foo", "x${var.one}y")

str1: "x${var.one}y"

int1: !!exp 1 + 2
`

file, diags := hcl2yaml.Parse(yamlSource, fileName)
if diags.HasErrors() {
	diagWriter.WriteDiagnostics(diags)
	os.Exit(1)
}

files := map[string]*hcl.File{
    fileName: file,
}

var example Example

if diags := gohcl.DecodeBody(file.Body, hclEavlCtx, &example); diags.HasErrors() {)
	diagWriter.WriteDiagnostics(diags))
	os.Exit(1))
}

fmt.Printf("%v\n", example)
// {[map[a:xONEy]] [map[a:xONEy]] map[foo:xONEy] map[foo:xONEy] xONEy 3}

Documentation

Index

• func DecodeBodyIntoMap(ctx *hcl.EvalContext, body hcl.Body, schema MapSchema, result interface{}) hcl.Diagnostics
• func Parse(src []byte, fileName string) (*hcl.File, hcl.Diagnostics)
• type Attribute
• type Block
  • func (b *Block) BodySchema() *hcl.BodySchema
• type MapSchema
  • func (m *MapSchema) BodySchema() *hcl.BodySchema
• type MappingExpression
  • func (e MappingExpression) Range() hcl.Range
  • func (e MappingExpression) StartRange() hcl.Range
  • func (e MappingExpression) Value(ctx *hcl.EvalContext) (cty.Value, hcl.Diagnostics)
  • func (e MappingExpression) Variables() []hcl.Traversal
• type SequenceExpression
  • func (e SequenceExpression) Range() hcl.Range
  • func (e SequenceExpression) StartRange() hcl.Range
  • func (e SequenceExpression) Value(ctx *hcl.EvalContext) (cty.Value, hcl.Diagnostics)
  • func (e SequenceExpression) Variables() []hcl.Traversal
• type YamlBody
  • func (f *YamlBody) Content(schema *hcl.BodySchema) (*hcl.BodyContent, hcl.Diagnostics)
  • func (f *YamlBody) JustAttributes() (hcl.Attributes, hcl.Diagnostics)
  • func (f *YamlBody) MissingItemRange() hcl.Range
  • func (f *YamlBody) PartialContent(schema *hcl.BodySchema) (*hcl.BodyContent, hcl.Body, hcl.Diagnostics)

Functions

func DecodeBodyIntoMap

func DecodeBodyIntoMap(ctx *hcl.EvalContext, body hcl.Body, schema MapSchema, result interface{}) hcl.Diagnostics

func Parse

func Parse(src []byte, fileName string) (*hcl.File, hcl.Diagnostics)

Types

type Attribute

type Attribute struct {
	Kind     reflect.Kind
	Optional bool
}

type Block

type Block struct {
	Plural string

	LabelNames []string

	Singleton bool

	Blocks     map[string]Block
	Attributes map[string]Attribute
}

func (*Block) BodySchema

func (b *Block) BodySchema() *hcl.BodySchema

type MapSchema

type MapSchema struct {
	Attributes map[string]Attribute
	Blocks     map[string]Block
}

func (*MapSchema) BodySchema

func (m *MapSchema) BodySchema() *hcl.BodySchema

type MappingExpression

type MappingExpression struct {
	Node *yaml.Node
	// contains filtered or unexported fields
}

func (MappingExpression) Range

func (e MappingExpression) Range() hcl.Range

func (MappingExpression) StartRange

func (e MappingExpression) StartRange() hcl.Range

func (MappingExpression) Value

func (e MappingExpression) Value(ctx *hcl.EvalContext) (cty.Value, hcl.Diagnostics)

func (MappingExpression) Variables

func (e MappingExpression) Variables() []hcl.Traversal

type SequenceExpression

type SequenceExpression struct {
	Node *yaml.Node
	// contains filtered or unexported fields
}

func (SequenceExpression) Range

func (e SequenceExpression) Range() hcl.Range

func (SequenceExpression) StartRange

func (e SequenceExpression) StartRange() hcl.Range

func (SequenceExpression) Value

func (e SequenceExpression) Value(ctx *hcl.EvalContext) (cty.Value, hcl.Diagnostics)

func (SequenceExpression) Variables

func (e SequenceExpression) Variables() []hcl.Traversal

type YamlBody

type YamlBody struct {
	// contains filtered or unexported fields
}

func (*YamlBody) Content

func (f *YamlBody) Content(schema *hcl.BodySchema) (*hcl.BodyContent, hcl.Diagnostics)

func (*YamlBody) JustAttributes

func (f *YamlBody) JustAttributes() (hcl.Attributes, hcl.Diagnostics)

func (*YamlBody) MissingItemRange

func (f *YamlBody) MissingItemRange() hcl.Range

func (*YamlBody) PartialContent

func (f *YamlBody) PartialContent(schema *hcl.BodySchema) (*hcl.BodyContent, hcl.Body, hcl.Diagnostics)