The HashiCorp Configuration Language (HCL) is a specialized configuration language developed by HashiCorp, primarily designed for use with its suite of tools, including Terraform, Vault, and Nomad.
Since Rougail is designed to centralize the variables from your various projects, it may be useful to export the variables and values defined in Rougail to an HCL file.
Please note that the goal here is not to manage all your HCL files, but to export the variables and values to them.
## Attributes
Attributes assigns a value to a particular name.
An attribute is therefore the name of a variable or a family to which a value is assigned.
### Primitive Types
Value has those primitive types: `string`, `integer`, `bool` or `null`
```hcl
a_string = "a value"
an_integer = 1
a_boolean = true
null_value = null
```
Nothing particular in Rougail:
```yaml
%YAML 1.2
---
version: 1.1
a_string: a value # An attribute with a string
an_integer: 1 # An attribute with a integer
a_boolean: true # A boolean attribute
null_value:
description: A nullable value
mandatory: false
...
```
### Complex Types
Value could be `list`, `set`, `tuple`, `map` or `object`.
#### `list`, `set` or `tuple`
The `set` type is an unordered `list` (the elements are all of the same type) with no duplicates. Rougail lists also do not allow duplicates by default (though this can be enabled), but their values are ordered.
The type `tuple` (where each element has its own type) is not allowed in Rougail, so hasn't equivalent for now.
Syntactically, there is no difference between a list, a set, and a tuple.
In Rougail, you must therefore declare a variable of a specific type and set the “multi” parameter to True.
```hcl
a_list = [
"value 1",
"value 2",
]
an_integer_list = [
1,
2,
]
```
```yaml
%YAML 1.2
---
version: 1.1
a_list: ["value 1", "value 2"] # An attribute with a list of strings
an_integer_list: [1, 2] # An attribute with a list of integer
...
```
#### `map` or `object`
The difference between `map` and `object` in HCL is analogous to that between `list` and `tuple`: the values in a `map` are all of the same type, whereas the values in an `object` can be of different.
In Rougail, this corresponds to a family.
```hcl
a_map = {
key_1 = "value 1"
key_2 = "value 2"
key_3 = "value 3"
}
an_object = {
a_string = "a value"
an_integer = 1
a_boolean = true
}
```
```yaml
%YAML 1.2
---
version: 1.1
a_map: # A map is simply a collection of variables of the same type
key_1: value 1 # A first attribute
key_2: value 2 # A second attribute
key_3: value 3 # A third attribute
an_object: # A object is just a family
a_string: a value # An attribute with a string
an_integer: 1 # An attribute with a integer
a_boolean: true # A boolean attribute
...
```
### Variable
```hcl
a_first_string: "a value"
a_second_string: a_first_string
```
A string, for now, must be enclosed in quotes. But a variable must not be enclosed in quotes.
You need to calculate the value directly in Rougail.
```yaml
%YAML 1.2
---
version: 1.1
a_first_string: "a value" # Take a first value
a_second_string:
description: An expressions is just a string
default:
variable: _.a_first_string
...
```
Or use basic expression (see after).
### Expressions
Expressions allow for dynamic configuration.
#### Basic
```hcl
a_first_string = "a value"
a_second_string = a_first_string
a_third_string = "combine ${a_first_string}"
```
A string, for now, must be enclosed in quotes. But a variable must not be enclosed in quotes (see below).
You have tu use basic expression in this case:
```yaml
%YAML 1.2
---
version: 1.1
a_first_string: "a value" # Take a first value
a_second_string:
description: A variable could also use expression to get value
hcl_quoted_string: false
default: a_first_string
a_third_string: combine ${a_first_string} # An expressions is just a string
...
```
#### Conditional Expressions
```hcl
a_first_string = "a value"
a_second_string = a_first_string == "a value" ? 2 : 1
```
A string, for now, must be enclosed in quotes. But a conditional expression must not be enclosed in quotes.
You need to calculate the value directly in Rougail.
```yaml
%YAML 1.2
---
version: 1.1
a_first_string: "a value" # Take a first value
a_second_string:
description: An expressions is just a string
hcl_quoted_string: false
default: "a_first_string == \"a value\" ? 2 : 1"
...
```
#### Function
HCL includes a variety of built-in functions that you can use to manipulate data and perform calculations.
```hcl
content = file("config.json")
```
A string, for now, must be enclosed in quotes. But a conditional expression must not be enclosed in quotes.
## Block
A `block` is a container for configuration.
### A basic block
There is no equivalent to a `block` in Rougail. To define a `block`, you must define a family and add an `hcl_type` parameter set to `block`.
[!NOTE] The `hcl` structural module must be loaded for this type to be recognized.
```hcl
a_block {
an_attribute = "a value"
}
```
```yaml
%YAML 1.2
---
version: 1.1
a_block:
description: A block is a family with hcl_type attribute
hcl_type: block
an_attribute: a value # An attribute in a block
...
```
### A block in a block
Blocks can have a tree-like structure, like family in Rougail.
```hcl
a_block {
a_second_block {
an_attribute = "a value"
}
}
```
```yaml
%YAML 1.2
---
version: 1.1
a_block:
description: A block is a family with hcl_type attribute
hcl_type: block
a_second_block:
description: We can add a block inside a block
hcl_type: block
an_attribute: a value # An attribute in a block
...
```
### A block with a label
Blocks have a block type and can have zero or more labels.
There is no equivalent to a `label` in Rougail. To define a `label`, you must define a family and add an `hcl_type` parameter set to `label`. A `label` must be defined within a `block`.
[!NOTE] The `hcl` structural module must be loaded for this type to be recognized.
```hcl
a_block "a_label" {
an_attribute = "a value"
}
```
```yaml
%YAML 1.2
---
version: 1.1
a_block:
description: A block is a family with hcl_type attribute
hcl_type: block
a_label:
description: A label is also a family with hcl_type attribute
hcl_type: label
an_attribute: a value # An attribute in a block
...
```
### A block with some labels
```hcl
a_block "a_first_label" "a_second_label" {
an_attribute = "a value"
}
```
```yaml
%YAML 1.2
---
version: 1.1
a_block:
description: A block is a family with hcl_type attribute
hcl_type: block
a_first_label:
description: A label is also a family with hcl_type attribute
hcl_type: label
a_second_label:
description: A label is also a family with hcl_type attribute
hcl_type: label
an_attribute: a value # An attribute in a block
...
```
### Block inside a label block
A `block` could be in a `label` block.
```hcl
a_block "a_first_label" "a_second_label" {
a_sub_block {
a_string = "a value"
}
}
```
```yaml
%YAML 1.2
---
version: 1.1
a_block:
description: A block is a family with hcl_type attribute
hcl_type: block
a_first_label:
description: A label is also a family with hcl_type attribute
hcl_type: label
a_second_label:
description: A label is also a family with hcl_type attribute
hcl_type: label
a_sub_block:
description: A block insible label block
hcl_type: block
a_string: a value # An attribute in a block
...
```
### Block with a label inside a block
And a `label` block could be in a `block`.
```hcl
a_block {
a_sub_block "a_first_label" "a_second_label" {
a_string = "a value"
}
}
```
```yaml
%YAML 1.2
---
version: 1.1
a_block:
description: A block is a family with hcl_type attribute
hcl_type: block
a_sub_block:
description: A label block insible block
hcl_type: block
a_first_label:
description: A label is also a family with hcl_type attribute
hcl_type: label
a_second_label:
description: A label is also a family with hcl_type attribute
hcl_type: label
a_string: a value # An attribute in a block
...
```
### Duplicate block name
In Rougail, it's not possible to have two families with the same name.
```hcl
a_block {
a_sub_block "a_label" {
an_attribut = [
"value 1",
"value2",
]
}
a_sub_block "a_label" {
an_attribut = [
"value 3",
]
}
}
```
```yaml
%YAML 1.2
---
version: 1.1
a_block:
description: A block is a family with hcl_type attribute
hcl_type: block
a_sub_block_1:
description: A label block insible block
hcl_type: block
hcl_name: a_sub_block
a_label:
description: Add a label
hcl_type: label
an_attribut: # An attribute
- value 1
- value2
a_sub_block_2:
description: Add a label
hcl_type: block
hcl_name: a_sub_block
a_label:
hcl_type: label
an_attribut: # An attribute
- value 3
...
```
### Variable block
The variable block define variables within your HCL configuration.
```hcl
variable "environment" {
description = "The deployment environment"
type = string
}
```
```yaml
%YAML 1.2
---
version: 1.1
variable:
description: Variable block
hcl_type: block
environment:
description: The deployment environment
hcl_type: label
description: The deployment environment # The environment description
