bb724af7fd
This is the hcldec interface to Body.JustAttributes, producing a map whose
keys are the child attribute names and whose values are the results of
evaluating those expressions.
We can't just expose a JustAttributes-style spec directly here because
it's not really compatible with how hcldec thinks about things, but we
can expose a spec that decodes a specific child block because that can
then compose properly with other specs at the same level without
interfering with their operation.
The primary use for this is to allow the use of the block syntax to define
a map:
dynamic_stuff {
foo = "bar"
}
JustAttributes is normally used in static analysis situations such as
enumerating the contents of a block to decide what to include in the
final EvalContext. That's not really possible with the hcldec model
because both structural decoding and expression evaluation happen
together. Therefore the use of this is pretty limited: it's useful if you
want to be compatible with an existing format based on legacy HCL where a
map was conventionally defined using block syntax, relying on the fact
that HCL did not make a strong distinction between attribute and block
syntax.
|
||
|---|---|---|
| .. | ||
| examples | ||
| main.go | ||
| README.md | ||
| spec_funcs.go | ||
| spec-format.md | ||
| spec.go | ||
| type_expr.go | ||
| vars.go | ||
hcldec
hcldec is a command line tool that transforms HCL input into JSON output
using a decoding specification given by the user.
This tool is intended as a "glue" tool, with use-cases like the following:
-
Define a HCL-based configuration format for a third-party tool that takes JSON as input, and then translate the HCL configuration into JSON before running the tool. (See the
npm-packageexample.) -
Use HCL from languages where a HCL parser/decoder is not yet available. At the time of writing, that's any language other than Go.
-
In particular, define a HCL-based configuration format for a shell script and then use
jqto load the result into environment variables for further processing. (See thesh-config-fileexample.)
Installation
If you have a working Go development environment, you can install this tool
with go get in the usual way:
$ go get -u github.com/hashicorp/hcl2/cmd/hcldec
This will install hcldec in $GOPATH/bin, which usually places it into
your shell PATH so you can then run it as hcldec.
Usage
usage: hcldec --spec=<spec-file> [options] [hcl-file ...]
-o, --out string write to the given file, instead of stdout
-s, --spec string path to spec file (required)
-V, --vars json-or-file provide variables to the given configuration file(s)
-v, --version show the version number and immediately exit
The most important step in using hcldec is to write the specification that
defines how to interpret the given configuration files and translate them
into JSON. The following is a simple specification that creates a JSON
object from two top-level attributes in the input configuration:
object {
attr "name" {
type = string
required = true
}
attr "is_member" {
type = bool
}
}
Specification files are conventionally kept in files with a .hcldec
extension. We'll call this one example.hcldec.
With the above specification, the following input file example.conf is
valid:
name = "Raul"
The spec and the input file can then be provided to hcldec to extract a
JSON representation:
$ hcldec --spec=example.hcldec example.conf
{"name": "Raul"}
The specification defines both how to map the input into a JSON data structure
and what input is valid. The required = true specified for the name
allows hcldec to detect and raise an error when an attribute of that name
is not provided:
$ hcldec --spec=example.hcldec typo.conf
Error: Unsupported attribute
on example.conf line 1:
1: namme = "Juan"
An attribute named "namme" is not expected here. Did you mean "name"?
Error: Missing required attribute
on example.conf line 2:
The attribute "name" is required, but no definition was found.
Further Reading
For more details on the .hcldec specification file format, see
the spec file documentation.