1# HCL
2
3[](https://godoc.org/github.com/hashicorp/hcl) [](https://travis-ci.org/hashicorp/hcl)
4
5HCL (HashiCorp Configuration Language) is a configuration language built
6by HashiCorp. The goal of HCL is to build a structured configuration language
7that is both human and machine friendly for use with command-line tools, but
8specifically targeted towards DevOps tools, servers, etc.
9
10HCL is also fully JSON compatible. That is, JSON can be used as completely
11valid input to a system expecting HCL. This helps makes systems
12interoperable with other systems.
13
14HCL is heavily inspired by
15[libucl](https://github.com/vstakhov/libucl),
16nginx configuration, and others similar.
17
18## Why?
19
20A common question when viewing HCL is to ask the question: why not
21JSON, YAML, etc.?
22
23Prior to HCL, the tools we built at [HashiCorp](http://www.hashicorp.com)
24used a variety of configuration languages from full programming languages
25such as Ruby to complete data structure languages such as JSON. What we
26learned is that some people wanted human-friendly configuration languages
27and some people wanted machine-friendly languages.
28
29JSON fits a nice balance in this, but is fairly verbose and most
30importantly doesn't support comments. With YAML, we found that beginners
31had a really hard time determining what the actual structure was, and
32ended up guessing more often than not whether to use a hyphen, colon, etc.
33in order to represent some configuration key.
34
35Full programming languages such as Ruby enable complex behavior
36a configuration language shouldn't usually allow, and also forces
37people to learn some set of Ruby.
38
39Because of this, we decided to create our own configuration language
40that is JSON-compatible. Our configuration language (HCL) is designed
41to be written and modified by humans. The API for HCL allows JSON
42as an input so that it is also machine-friendly (machines can generate
43JSON instead of trying to generate HCL).
44
45Our goal with HCL is not to alienate other configuration languages.
46It is instead to provide HCL as a specialized language for our tools,
47and JSON as the interoperability layer.
48
49## Syntax
50
51For a complete grammar, please see the parser itself. A high-level overview
52of the syntax and grammar is listed here.
53
54 * Single line comments start with `#` or `//`
55
56 * Multi-line comments are wrapped in `/*` and `*/`. Nested block comments
57 are not allowed. A multi-line comment (also known as a block comment)
58 terminates at the first `*/` found.
59
60 * Values are assigned with the syntax `key = value` (whitespace doesn't
61 matter). The value can be any primitive: a string, number, boolean,
62 object, or list.
63
64 * Strings are double-quoted and can contain any UTF-8 characters.
65 Example: `"Hello, World"`
66
67 * Multi-line strings start with `<<EOF` at the end of a line, and end
68 with `EOF` on its own line ([here documents](https://en.wikipedia.org/wiki/Here_document)).
69 Any text may be used in place of `EOF`. Example:
70```
71<<FOO
72hello
73world
74FOO
75```
76
77 * Numbers are assumed to be base 10. If you prefix a number with 0x,
78 it is treated as a hexadecimal. If it is prefixed with 0, it is
79 treated as an octal. Numbers can be in scientific notation: "1e10".
80
81 * Boolean values: `true`, `false`
82
83 * Arrays can be made by wrapping it in `[]`. Example:
84 `["foo", "bar", 42]`. Arrays can contain primitives,
85 other arrays, and objects. As an alternative, lists
86 of objects can be created with repeated blocks, using
87 this structure:
88
89 ```hcl
90 service {
91 key = "value"
92 }
93
94 service {
95 key = "value"
96 }
97 ```
98
99Objects and nested objects are created using the structure shown below:
100
101```
102variable "ami" {
103 description = "the AMI to use"
104}
105```
106This would be equivalent to the following json:
107``` json
108{
109 "variable": {
110 "ami": {
111 "description": "the AMI to use"
112 }
113 }
114}
115```
116
117## Thanks
118
119Thanks to:
120
121 * [@vstakhov](https://github.com/vstakhov) - The original libucl parser
122 and syntax that HCL was based off of.
123
124 * [@fatih](https://github.com/fatih) - The rewritten HCL parser
125 in pure Go (no goyacc) and support for a printer.
View as plain text