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

   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.