Table of Contents

• HCL
• Attributes
• Primitive Types
• Complex Types
• list, set or tuple
• map or object
• Variable
• Expressions
• Basic
• Conditional Expressions
• Function
• Block
• A basic block
• A block in a block
• A block with a label
• A block with some labels
• Block inside a label block
• Block with a label inside a block
• Duplicate block name
• Variable block

HCL

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

a_string = "a value"
an_integer = 1
a_boolean = true
null_value = null

Nothing particular in Rougail:

%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.

a_list = [
  "value 1",
  "value 2",
]
an_integer_list = [
  1,
  2,
]

%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.

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 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

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 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

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 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

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 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.

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.

a_block {
  an_attribute = "a value"
}

%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.

a_block {
  a_second_block {
    an_attribute = "a value"
  }
}

%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.

a_block "a_label" {
  an_attribute = "a value"
}

%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

a_block "a_first_label" "a_second_label" {
  an_attribute = "a value"
}

%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.

a_block "a_first_label" "a_second_label" {
  a_sub_block {
    a_string = "a value"
  }
}

%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.

a_block {
  a_sub_block "a_first_label" "a_second_label" {
    a_string = "a value"
  }
}

%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.

a_block {
  a_sub_block "a_label" {
    an_attribut = [
      "value 1",
      "value2",
    ]
  }
  

  a_sub_block "a_label" {
    an_attribut = [
      "value 3",
    ]
  }
}

%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.

variable "environment" {
  description = "The deployment environment"
  type        = string
}

%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
  
    type:
      description: The type description
      hcl_quoted_string: false
      default: string
...