vendor/github.com/hashicorp/hil/README.md

   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.