hcl/cmd/hcldec/README.md

101 lines
2.9 KiB
Markdown
Raw Normal View History

# 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-package` example](examples/npm-package).)
* 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 `jq` to load the result into environment variables for
further processing. (See [the `sh-config-file` example](examples/sh-config-file).)
## 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/hcl/v2/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:
```hcl
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:
```hcl
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](spec-format.md).