terraform/vendor/github.com/hashicorp/hcl
Kristin Laemmert 5f8916b4fd
configs/configupgrade: do not panic on HEREDOCs. (#20281)
Previously, configupgrade would panic if it encountered a HEREDOC. For
the time being, we will simply print out the HEREDOC as-is.

Unfortunately, we discovered that terraform 0.11's version of HCL
allowed for HEREDOCs with the termination delimiter inline (instead of
on a newline, which is technically correct). Since 0.12configupgrade
needs to be bug-compatible with terraform 0.11, we must roll back to the
same version of HCL used in terraform 0.11.
2019-02-08 15:51:53 -08:00
..
hcl configs/configupgrade: do not panic on HEREDOCs. (#20281) 2019-02-08 15:51:53 -08:00
json configs/configupgrade: do not panic on HEREDOCs. (#20281) 2019-02-08 15:51:53 -08:00
.gitignore vendor: update to latest github.com/zclconf/go-cty 2018-10-16 19:14:11 -07:00
.travis.yml configs/configupgrade: do not panic on HEREDOCs. (#20281) 2019-02-08 15:51:53 -08:00
LICENSE Vendor all dependencies w/ Godep 2016-01-29 15:08:48 -06:00
Makefile Update github.com/hashicorp/hcl 2016-09-16 09:06:26 -04:00
README.md update HCL vendor 2016-09-02 09:58:05 -07:00
appveyor.yml update vendored hcl 2017-05-04 17:08:18 -04:00
decoder.go configs/configupgrade: do not panic on HEREDOCs. (#20281) 2019-02-08 15:51:53 -08:00
hcl.go Vendor all dependencies w/ Godep 2016-01-29 15:08:48 -06:00
lex.go deps: Update github.com/hashicorp/hcl 2016-03-21 14:48:28 +00:00
parse.go deps: Update github.com/hashicorp/hcl 2016-03-21 14:48:28 +00:00

README.md

HCL

GoDoc Build Status

HCL (HashiCorp Configuration Language) is a configuration language built by HashiCorp. The goal of HCL is to build a structured configuration language that is both human and machine friendly for use with command-line tools, but specifically targeted towards DevOps tools, servers, etc.

HCL is also fully JSON compatible. That is, JSON can be used as completely valid input to a system expecting HCL. This helps makes systems interoperable with other systems.

HCL is heavily inspired by libucl, nginx configuration, and others similar.

Why?

A common question when viewing HCL is to ask the question: why not JSON, YAML, etc.?

Prior to HCL, the tools we built at HashiCorp used a variety of configuration languages from full programming languages such as Ruby to complete data structure languages such as JSON. What we learned is that some people wanted human-friendly configuration languages and some people wanted machine-friendly languages.

JSON fits a nice balance in this, but is fairly verbose and most importantly doesn't support comments. With YAML, we found that beginners had a really hard time determining what the actual structure was, and ended up guessing more often than not whether to use a hyphen, colon, etc. in order to represent some configuration key.

Full programming languages such as Ruby enable complex behavior a configuration language shouldn't usually allow, and also forces people to learn some set of Ruby.

Because of this, we decided to create our own configuration language that is JSON-compatible. Our configuration language (HCL) is designed to be written and modified by humans. The API for HCL allows JSON as an input so that it is also machine-friendly (machines can generate JSON instead of trying to generate HCL).

Our goal with HCL is not to alienate other configuration languages. It is instead to provide HCL as a specialized language for our tools, and JSON as the interoperability layer.

Syntax

For a complete grammar, please see the parser itself. A high-level overview of the syntax and grammar is listed here.

  • Single line comments start with # or //

  • Multi-line comments are wrapped in /* and */. Nested block comments are not allowed. A multi-line comment (also known as a block comment) terminates at the first */ found.

  • Values are assigned with the syntax key = value (whitespace doesn't matter). The value can be any primitive: a string, number, boolean, object, or list.

  • Strings are double-quoted and can contain any UTF-8 characters. Example: "Hello, World"

  • Multi-line strings start with <<EOF at the end of a line, and end with EOF on its own line (here documents). Any text may be used in place of EOF. Example:

<<FOO
hello
world
FOO
  • Numbers are assumed to be base 10. If you prefix a number with 0x, it is treated as a hexadecimal. If it is prefixed with 0, it is treated as an octal. Numbers can be in scientific notation: "1e10".

  • Boolean values: true, false

  • Arrays can be made by wrapping it in []. Example: ["foo", "bar", 42]. Arrays can contain primitives, other arrays, and objects. As an alternative, lists of objects can be created with repeated blocks, using this structure:

    service {
        key = "value"
    }
    
    service {
        key = "value"
    }
    

Objects and nested objects are created using the structure shown below:

variable "ami" {
    description = "the AMI to use"
}

This would be equivalent to the following json:

{
  "variable": {
      "ami": {
          "description": "the AMI to use"
        }
    }
}

Thanks

Thanks to:

  • @vstakhov - The original libucl parser and syntax that HCL was based off of.

  • @fatih - The rewritten HCL parser in pure Go (no goyacc) and support for a printer.