]>
Commit | Line | Data |
---|---|---|
bae9f6d2 JC |
1 | # HCL |
2 | ||
3 | [![GoDoc](https://godoc.org/github.com/hashicorp/hcl?status.png)](https://godoc.org/github.com/hashicorp/hcl) [![Build Status](https://travis-ci.org/hashicorp/hcl.svg?branch=master)](https://travis-ci.org/hashicorp/hcl) | |
4 | ||
5 | HCL (HashiCorp Configuration Language) is a configuration language built | |
6 | by HashiCorp. The goal of HCL is to build a structured configuration language | |
7 | that is both human and machine friendly for use with command-line tools, but | |
8 | specifically targeted towards DevOps tools, servers, etc. | |
9 | ||
10 | HCL is also fully JSON compatible. That is, JSON can be used as completely | |
11 | valid input to a system expecting HCL. This helps makes systems | |
12 | interoperable with other systems. | |
13 | ||
14 | HCL is heavily inspired by | |
15 | [libucl](https://github.com/vstakhov/libucl), | |
16 | nginx configuration, and others similar. | |
17 | ||
18 | ## Why? | |
19 | ||
20 | A common question when viewing HCL is to ask the question: why not | |
21 | JSON, YAML, etc.? | |
22 | ||
23 | Prior to HCL, the tools we built at [HashiCorp](http://www.hashicorp.com) | |
24 | used a variety of configuration languages from full programming languages | |
25 | such as Ruby to complete data structure languages such as JSON. What we | |
26 | learned is that some people wanted human-friendly configuration languages | |
27 | and some people wanted machine-friendly languages. | |
28 | ||
29 | JSON fits a nice balance in this, but is fairly verbose and most | |
30 | importantly doesn't support comments. With YAML, we found that beginners | |
31 | had a really hard time determining what the actual structure was, and | |
32 | ended up guessing more often than not whether to use a hyphen, colon, etc. | |
33 | in order to represent some configuration key. | |
34 | ||
35 | Full programming languages such as Ruby enable complex behavior | |
36 | a configuration language shouldn't usually allow, and also forces | |
37 | people to learn some set of Ruby. | |
38 | ||
39 | Because of this, we decided to create our own configuration language | |
40 | that is JSON-compatible. Our configuration language (HCL) is designed | |
41 | to be written and modified by humans. The API for HCL allows JSON | |
42 | as an input so that it is also machine-friendly (machines can generate | |
43 | JSON instead of trying to generate HCL). | |
44 | ||
45 | Our goal with HCL is not to alienate other configuration languages. | |
46 | It is instead to provide HCL as a specialized language for our tools, | |
47 | and JSON as the interoperability layer. | |
48 | ||
49 | ## Syntax | |
50 | ||
51 | For a complete grammar, please see the parser itself. A high-level overview | |
52 | of 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 | |
72 | hello | |
73 | world | |
74 | FOO | |
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 | ||
99 | Objects and nested objects are created using the structure shown below: | |
100 | ||
101 | ``` | |
102 | variable "ami" { | |
103 | description = "the AMI to use" | |
104 | } | |
105 | ``` | |
106 | This 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 | ||
119 | Thanks 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. |