README.md
HIL
HIL (HashiCorp Interpolation Language) is a lightweight embedded language used primarily for configuration interpolation. The goal of HIL is to make a simple language for interpolations in the various configurations of HashiCorp tools.
HIL is built to interpolate any string, but is in use by HashiCorp primarily with HCL. HCL is not required in any way for use with HIL.
HIL isn't meant to be a general purpose language. It was built for basic configuration interpolations. Therefore, you can't currently write functions, have conditionals, set intermediary variables, etc. within HIL itself. It is possible some of these may be added later but the right use case must exist.
Why?
Many of our tools have support for something similar to templates, but within the configuration itself. The most prominent requirement was in Terraform where we wanted the configuration to be able to reference values from elsewhere in the configuration. Example:
foo = "hi ${var.world}"
We originally used a full templating language for this, but found it was too heavy weight. Additionally, many full languages required bindings to C (and thus the usage of cgo) which we try to avoid to make cross-compilation easier. We then moved to very basic regular expression based string replacement, but found the need for basic arithmetic and function calls resulting in overly complex regular expressions.
Ultimately, we wrote our own mini-language within Terraform itself. As we built other projects such as Nomad and Otto, the need for basic interpolations arose again.
Thus HIL was born. It is extracted from Terraform, cleaned up, and better tested for general purpose use.
Syntax
For a complete grammar, please see the parser itself. A high-level overview of the syntax and grammer is listed here.
Code begins within ${ and }. Outside of this, text is treated
literally. For example, foo is a valid HIL program that is just the
string "foo", but foo ${bar} is an HIL program that is the string "foo "
concatened with the value of bar. For the remainder of the syntax
docs, we'll assume you're within ${}.
-
Identifiers are any text in the format of
[a-zA-Z0-9-.]. Example identifiers:foo,var.foo,foo-bar. -
Strings are double quoted and can contain any UTF-8 characters. Example:
"Hello, World" -
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".
-
Unary
-can be used for negative numbers. Example:-10or-0.2 -
Boolean values:
true,false -
The following arithmetic operations are allowed: +, -, *, /, %.
-
Function calls are in the form of
name(arg1, arg2, ...). Example:add(1, 5). Arguments can be any valid HIL expression, example:add(1, var.foo)or even nested function calls:add(1, get("some value")). -
Within strings, further interpolations can be opened with
${}. Example:"Hello ${nested}". A full example including the original${}(remember this list assumes were inside of one already) could be:foo ${func("hello ${var.foo}")}.
Language Changes
We've used this mini-language in Terraform for years. For backwards compatibility reasons, we're unlikely to make an incompatible change to the language but we're not currently making that promise, either.
The internal API of this project may very well change as we evolve it to work with more of our projects. We recommend using some sort of dependency management solution with this package.
Future Changes
The following changes are already planned to be made at some point:
-
Richer types: lists, maps, etc.
-
Convert to a more standard Go parser structure similar to HCL. This will improve our error messaging as well as allow us to have automatic formatting.
-
Allow interpolations to result in more types than just a string. While within the interpolation basic types are honored, the result is always a string.