Module hcl_builder

Expand description

The HCL builder: a Terraform module is built as hcl-rs structures (Block, Attribute, Expression) and written once.

Values go in as values: a string is an Expression::String, escaped by hcl-rs (quotes, backslashes, newlines, and Terraform’s ${ and %{ markers). Text that holds Terraform expressions is a Template: its text is escaped the same way and its expressions are interpolated, so nothing in a value can end the string or start an interpolation.
Module writes the blocks in the layout terraform fmt keeps: two-space indents, the = of consecutive one-line attributes aligned, one blank line between top-level blocks. A list, an object or a function call is written on one line when it fits in WIDTH characters, else one item a line (a call keeps its last argument hugged: f(a, [).
Comments go above a top-level block (Module::commented): hcl-rs has none inside.

Structs§

Attribute: Represents an HCL attribute which consists of an attribute key and a value expression.
Block: Represents an HCL block which consists of a block identifier, zero or more block labels and a block body.
BlockBuilder: BlockBuilder builds an HCL Block.
Body: Represents an HCL config file body.
Module: A Terraform file: its preamble (comment lines), then top-level blocks, each with the comment above it.
Template: A quoted HCL template: text, escaped when written, and expressions, interpolated as ${...}. Text can never become an interpolation, whatever it holds.

BinaryOperator: An operator that can be applied to two expressions.
Expression: A type representing the expression sub-language. It is used in HCL attributes to specify values and in HCL templates.
Piece: A piece of a template: text, or an interpolated expression.
Structure: Represents an HCL structure.

WIDTH: A list, an object or a call longer than this, on one line, is written across lines.

attr: expr.name: an attribute of an expression that isn’t a plain path (list[0].id).
binary: lhs <op> rhs.
boolean: true or false.
call: A function call.
conditional: cond ? yes : no.
entry: expr["key"]: a map’s entry by its key.
for_list: [for <var> in <collection> : <value> if <cond>].
index: expr[i].
list: A list.
not: !expr.
null: null.
number: A whole number.
object: An object, in the order given. A key that is an identifier is written bare, any other quoted.
reference: A reference by its dotted path: var.node, aws_vpc.env.id. Each part is an identifier (resource names come from res, which keeps them so).
string: A string value (escaped when written).

Error: Why a module couldn’t be written (hcl-rs documents formatting as infallible: kept typed rather than assumed).