diff options
Diffstat (limited to 'vendor/github.com/hashicorp/hil/README.md')
-rw-r--r-- | vendor/github.com/hashicorp/hil/README.md | 102 |
1 files changed, 102 insertions, 0 deletions
diff --git a/vendor/github.com/hashicorp/hil/README.md b/vendor/github.com/hashicorp/hil/README.md new file mode 100644 index 0000000..186ed25 --- /dev/null +++ b/vendor/github.com/hashicorp/hil/README.md | |||
@@ -0,0 +1,102 @@ | |||
1 | # HIL | ||
2 | |||
3 | [![GoDoc](https://godoc.org/github.com/hashicorp/hil?status.png)](https://godoc.org/github.com/hashicorp/hil) [![Build Status](https://travis-ci.org/hashicorp/hil.svg?branch=master)](https://travis-ci.org/hashicorp/hil) | ||
4 | |||
5 | HIL (HashiCorp Interpolation Language) is a lightweight embedded language used | ||
6 | primarily for configuration interpolation. The goal of HIL is to make a simple | ||
7 | language for interpolations in the various configurations of HashiCorp tools. | ||
8 | |||
9 | HIL is built to interpolate any string, but is in use by HashiCorp primarily | ||
10 | with [HCL](https://github.com/hashicorp/hcl). HCL is _not required_ in any | ||
11 | way for use with HIL. | ||
12 | |||
13 | HIL isn't meant to be a general purpose language. It was built for basic | ||
14 | configuration interpolations. Therefore, you can't currently write functions, | ||
15 | have conditionals, set intermediary variables, etc. within HIL itself. It is | ||
16 | possible some of these may be added later but the right use case must exist. | ||
17 | |||
18 | ## Why? | ||
19 | |||
20 | Many of our tools have support for something similar to templates, but | ||
21 | within the configuration itself. The most prominent requirement was in | ||
22 | [Terraform](https://github.com/hashicorp/terraform) where we wanted the | ||
23 | configuration to be able to reference values from elsewhere in the | ||
24 | configuration. Example: | ||
25 | |||
26 | foo = "hi ${var.world}" | ||
27 | |||
28 | We originally used a full templating language for this, but found it | ||
29 | was too heavy weight. Additionally, many full languages required bindings | ||
30 | to C (and thus the usage of cgo) which we try to avoid to make cross-compilation | ||
31 | easier. We then moved to very basic regular expression based | ||
32 | string replacement, but found the need for basic arithmetic and function | ||
33 | calls resulting in overly complex regular expressions. | ||
34 | |||
35 | Ultimately, we wrote our own mini-language within Terraform itself. As | ||
36 | we built other projects such as [Nomad](https://nomadproject.io) and | ||
37 | [Otto](https://ottoproject.io), the need for basic interpolations arose | ||
38 | again. | ||
39 | |||
40 | Thus HIL was born. It is extracted from Terraform, cleaned up, and | ||
41 | better tested for general purpose use. | ||
42 | |||
43 | ## Syntax | ||
44 | |||
45 | For a complete grammar, please see the parser itself. A high-level overview | ||
46 | of the syntax and grammer is listed here. | ||
47 | |||
48 | Code begins within `${` and `}`. Outside of this, text is treated | ||
49 | literally. For example, `foo` is a valid HIL program that is just the | ||
50 | string "foo", but `foo ${bar}` is an HIL program that is the string "foo " | ||
51 | concatened with the value of `bar`. For the remainder of the syntax | ||
52 | docs, we'll assume you're within `${}`. | ||
53 | |||
54 | * Identifiers are any text in the format of `[a-zA-Z0-9-.]`. Example | ||
55 | identifiers: `foo`, `var.foo`, `foo-bar`. | ||
56 | |||
57 | * Strings are double quoted and can contain any UTF-8 characters. | ||
58 | Example: `"Hello, World"` | ||
59 | |||
60 | * Numbers are assumed to be base 10. If you prefix a number with 0x, | ||
61 | it is treated as a hexadecimal. If it is prefixed with 0, it is | ||
62 | treated as an octal. Numbers can be in scientific notation: "1e10". | ||
63 | |||
64 | * Unary `-` can be used for negative numbers. Example: `-10` or `-0.2` | ||
65 | |||
66 | * Boolean values: `true`, `false` | ||
67 | |||
68 | * The following arithmetic operations are allowed: +, -, *, /, %. | ||
69 | |||
70 | * Function calls are in the form of `name(arg1, arg2, ...)`. Example: | ||
71 | `add(1, 5)`. Arguments can be any valid HIL expression, example: | ||
72 | `add(1, var.foo)` or even nested function calls: | ||
73 | `add(1, get("some value"))`. | ||
74 | |||
75 | * Within strings, further interpolations can be opened with `${}`. | ||
76 | Example: `"Hello ${nested}"`. A full example including the | ||
77 | original `${}` (remember this list assumes were inside of one | ||
78 | already) could be: `foo ${func("hello ${var.foo}")}`. | ||
79 | |||
80 | ## Language Changes | ||
81 | |||
82 | We've used this mini-language in Terraform for years. For backwards compatibility | ||
83 | reasons, we're unlikely to make an incompatible change to the language but | ||
84 | we're not currently making that promise, either. | ||
85 | |||
86 | The internal API of this project may very well change as we evolve it | ||
87 | to work with more of our projects. We recommend using some sort of dependency | ||
88 | management solution with this package. | ||
89 | |||
90 | ## Future Changes | ||
91 | |||
92 | The following changes are already planned to be made at some point: | ||
93 | |||
94 | * Richer types: lists, maps, etc. | ||
95 | |||
96 | * Convert to a more standard Go parser structure similar to HCL. This | ||
97 | will improve our error messaging as well as allow us to have automatic | ||
98 | formatting. | ||
99 | |||
100 | * Allow interpolations to result in more types than just a string. While | ||
101 | within the interpolation basic types are honored, the result is always | ||
102 | a string. | ||