diff options
author | Jake Champlin <jake.champlin.27@gmail.com> | 2017-06-06 12:40:07 -0400 |
---|---|---|
committer | Jake Champlin <jake.champlin.27@gmail.com> | 2017-06-06 12:40:07 -0400 |
commit | bae9f6d2fd5eb5bc80929bd393932b23f14d7c93 (patch) | |
tree | ca9ab12a7d78b1fc27a8f734729081357ce6d252 /vendor/github.com/hashicorp/hcl/README.md | |
parent | 254c495b6bebab3fb72a243c4bce858d79e6ee99 (diff) | |
download | terraform-provider-statuscake-bae9f6d2fd5eb5bc80929bd393932b23f14d7c93.tar.gz terraform-provider-statuscake-bae9f6d2fd5eb5bc80929bd393932b23f14d7c93.tar.zst terraform-provider-statuscake-bae9f6d2fd5eb5bc80929bd393932b23f14d7c93.zip |
Initial transfer of provider code
Diffstat (limited to 'vendor/github.com/hashicorp/hcl/README.md')
-rw-r--r-- | vendor/github.com/hashicorp/hcl/README.md | 125 |
1 files changed, 125 insertions, 0 deletions
diff --git a/vendor/github.com/hashicorp/hcl/README.md b/vendor/github.com/hashicorp/hcl/README.md new file mode 100644 index 0000000..c822332 --- /dev/null +++ b/vendor/github.com/hashicorp/hcl/README.md | |||
@@ -0,0 +1,125 @@ | |||
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. | ||