github.com/hashicorp/hcl/v2@v2.20.0/cmd/hcldec/README.md (about)

     1  # hcldec
     2  
     3  `hcldec` is a command line tool that transforms HCL input into JSON output
     4  using a decoding specification given by the user.
     5  
     6  This tool is intended as a "glue" tool, with use-cases like the following:
     7  
     8  * Define a HCL-based configuration format for a third-party tool that takes
     9    JSON as input, and then translate the HCL configuration into JSON before
    10    running the tool. (See [the `npm-package` example](examples/npm-package).)
    11  
    12  * Use HCL from languages where a HCL parser/decoder is not yet available.
    13    At the time of writing, that's any language other than Go.
    14  
    15  * In particular, define a HCL-based configuration format for a shell script
    16    and then use `jq` to load the result into environment variables for
    17    further processing. (See [the `sh-config-file` example](examples/sh-config-file).)
    18  
    19  ## Installation
    20  
    21  If you have a working Go development environment, you can install this tool
    22  with `go get` in the usual way:
    23  
    24  ```
    25  $ go get -u github.com/hashicorp/hcl/v2/cmd/hcldec
    26  ```
    27  
    28  This will install `hcldec` in `$GOPATH/bin`, which usually places it into
    29  your shell `PATH` so you can then run it as `hcldec`.
    30  
    31  ## Usage
    32  
    33  ```
    34  usage: hcldec --spec=<spec-file> [options] [hcl-file ...]
    35    -o, --out string          write to the given file, instead of stdout
    36    -s, --spec string         path to spec file (required)
    37    -V, --vars json-or-file   provide variables to the given configuration file(s)
    38    -v, --version             show the version number and immediately exit
    39  ```
    40  
    41  The most important step in using `hcldec` is to write the specification that
    42  defines how to interpret the given configuration files and translate them
    43  into JSON. The following is a simple specification that creates a JSON
    44  object from two top-level attributes in the input configuration:
    45  
    46  ```hcl
    47  object {
    48    attr "name" {
    49      type     = string
    50      required = true
    51    }
    52    attr "is_member" {
    53      type = bool
    54    }
    55  }
    56  ```
    57  
    58  Specification files are conventionally kept in files with a `.hcldec`
    59  extension. We'll call this one `example.hcldec`.
    60  
    61  With the above specification, the following input file `example.conf` is
    62  valid:
    63  
    64  ```hcl
    65  name = "Raul"
    66  ```
    67  
    68  The spec and the input file can then be provided to `hcldec` to extract a
    69  JSON representation:
    70  
    71  ```
    72  $ hcldec --spec=example.hcldec example.conf
    73  {"name": "Raul"}
    74  ```
    75  
    76  The specification defines both how to map the input into a JSON data structure
    77  and what input is valid. The `required = true` specified for the `name`
    78  allows `hcldec` to detect and raise an error when an attribute of that name
    79  is not provided:
    80  
    81  ```
    82  $ hcldec --spec=example.hcldec typo.conf
    83  Error: Unsupported attribute
    84  
    85    on example.conf line 1:
    86     1: namme = "Juan"
    87  
    88  An attribute named "namme" is not expected here. Did you mean "name"?
    89  
    90  Error: Missing required attribute
    91  
    92    on example.conf line 2:
    93  
    94  The attribute "name" is required, but no definition was found.
    95  ```
    96  
    97  ## Further Reading
    98  
    99  For more details on the `.hcldec` specification file format, see
   100  [the spec file documentation](spec-format.md).