hclsimple

Documentation

Overview

Package hclsimple is a higher-level entry point for loading HCL configuration files directly into Go struct values in a single step.

This package is more opinionated than the rest of the HCL API. See the documentation for function Decode for more information.

Example (JsonSyntax)

package main

import (
	"fmt"
	"log"

	"github.com/hashicorp/hcl/v2/hclsimple"
)

func main() {
	type Config struct {
		Foo string `hcl:"foo"`
		Baz string `hcl:"baz"`
	}

	const exampleConfig = `
	{
		"foo": "bar",
		"baz": "boop"
	}
	`

	var config Config
	err := hclsimple.Decode(
		"example.json", []byte(exampleConfig),
		nil, &config,
	)
	if err != nil {
		log.Fatalf("Failed to load configuration: %s", err)
	}
	fmt.Printf("Configuration is %v\n", config)

}

Output:

Configuration is {bar boop}

Example (NativeSyntax)

package main

import (
	"fmt"
	"log"

	"github.com/hashicorp/hcl/v2/hclsimple"
)

func main() {
	type Config struct {
		Foo string `hcl:"foo"`
		Baz string `hcl:"baz"`
	}

	const exampleConfig = `
	foo = "bar"
	baz = "boop"
	`

	var config Config
	err := hclsimple.Decode(
		"example.hcl", []byte(exampleConfig),
		nil, &config,
	)
	if err != nil {
		log.Fatalf("Failed to load configuration: %s", err)
	}
	fmt.Printf("Configuration is %v\n", config)

}

Output:

Configuration is {bar boop}

Index

• func Decode(filename string, src []byte, ctx *hcl.EvalContext, target interface{}) error
• func DecodeFile(filename string, ctx *hcl.EvalContext, target interface{}) error

Examples

• Package (JsonSyntax)
• Package (NativeSyntax)

Functions

func Decode

func Decode(filename string, src []byte, ctx *hcl.EvalContext, target interface{}) error

Decode parses, decodes, and evaluates expressions in the given HCL source code, in a single step.

The main HCL API is built to allow applications that need to decompose the processing steps into a pipeline, with different tasks done by different parts of the program: parsing the source code into an abstract representation, analysing the block structure, evaluating expressions, and then extracting the results into a form consumable by the rest of the program.

This function does all of those steps in one call, going directly from source code to a populated Go struct value.

The "filename" and "src" arguments describe the input configuration. The filename is used to add source location context to any returned error messages and its suffix will choose one of the two supported syntaxes: ".hcl" for native syntax, and ".json" for HCL JSON. The src must therefore contain a sequence of bytes that is valid for the selected syntax.

The "ctx" argument provides variables and functions for use during expression evaluation. Applications that need no variables nor functions can just pass nil.

The "target" argument must be a pointer to a value of a struct type, with struct tags as defined by the sibling package "gohcl".

The return type is error but any non-nil error is guaranteed to be type-assertable to hcl.Diagnostics for applications that wish to access the full error details.

This is a very opinionated function that is intended to serve the needs of applications that are just using HCL for simple configuration and don't need detailed control over the decoding process. Because this function is just wrapping functionality elsewhere, if it doesn't meet your needs then please consider copying it into your program and adapting it as needed.

func DecodeFile

func DecodeFile(filename string, ctx *hcl.EvalContext, target interface{}) error

DecodeFile is a wrapper around Decode that first reads the given filename from disk. See the Decode documentation for more information.