Crate hcl

source · [−]

Expand description

hcl-rs

MIT License

A rust library for interacting with the Hashicorp Configuration Language (HCL).

Features

A parser for the HCL syntax specification
Types for all HCL structures, e.g. body, blocks and attributes
Supporting macros like body! for constructing HCL data structures
Supports the expression and template sub-languages in attribute values
Support for deserializing and serializing arbitrary types that implement serde::Deserialize or serde::Serialize

Planned Features

Evaluation of HCL expressions and the template sub-language (currently in progress)

Deserialization examples

Deserialize arbitrary HCL according to the HCL JSON Specification:

use serde_json::{json, Value};

let input = r#"
    some_attr = {
      foo = [1, 2]
      bar = true
    }

    some_block "some_block_label" {
      attr = "value"
    }
"#;

let expected = json!({
    "some_attr": {
        "foo": [1, 2],
        "bar": true
    },
    "some_block": {
        "some_block_label": {
            "attr": "value"
        }
    }
});

let value: Value = hcl::from_str(input).unwrap();

assert_eq!(value, expected);

If you need to preserve context about the HCL structure, deserialize into hcl::Body instead:

use hcl::{Block, Body, Expression};

let input = r#"
    some_attr = {
      "foo" = [1, 2]
      "bar" = true
    }

    some_block "some_block_label" {
      attr = "value"
    }
"#;

let expected = Body::builder()
    .add_attribute((
        "some_attr",
        Expression::from_iter([
            ("foo", Expression::from(vec![1, 2])),
            ("bar", Expression::Bool(true)),
        ]),
    ))
    .add_block(
        Block::builder("some_block")
            .add_label("some_block_label")
            .add_attribute(("attr", "value"))
            .build(),
    )
    .build();

let body: Body = hcl::from_str(input).unwrap();

assert_eq!(body, expected);

Serialization examples

A simple example to serialize some terraform configuration:

use hcl::{Block, Body, RawExpression};

let body = Body::builder()
    .add_block(
        Block::builder("resource")
            .add_label("aws_sns_topic_subscription")
            .add_label("topic")
            .add_attribute(("topic_arn", RawExpression::new("aws_sns_topic.queue.arn")))
            .add_attribute(("protocol", "sqs"))
            .add_attribute(("endpoint", RawExpression::new("aws_sqs_queue.queue.arn")))
            .build(),
    )
    .build();

let expected = r#"
resource "aws_sns_topic_subscription" "topic" {
  topic_arn = aws_sns_topic.queue.arn
  protocol = "sqs"
  endpoint = aws_sqs_queue.queue.arn
}
"#.trim_start();

let serialized = hcl::to_string(&body).unwrap();

assert_eq!(serialized, expected);

Also have a look at the other examples provided in the documentation of the ser module.

Macros

This crate provides a couple of macros to ease building HCL data structures. Have a look at their documentation for usage examples.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before creating a PR.

License

The source code of hcl-rs is released under the MIT License. See the bundled LICENSE file for details.

Modules

de

Deserialize HCL data to a Rust data structure.

error

The Error and Result types used by this crate.

format

Format data structures as HCL.

ser

Serialize a Rust data structure into HCL data.

structure

Types to represent HCL structures.

template

This module implements the HCL template sub-language.

value

The Value enum, a loosely typed way of representing any valid HCL value.

Macros

attribute

Construct an hcl::Attribute from a key and a value expression.

block

Construct an hcl::Block from a block identifier, optional block labels and a block body.

block_label

Construct an hcl::BlockLabel.

body

Construct an hcl::Body from HCL blocks and attributes.

expression

Construct an hcl::Expression from an HCL attribute value expression literal.

object_key

Construct an hcl::ObjectKey.

structure

Construct an hcl::Structure which may be either an HCL attribute or block.

Structs

Attribute

Represents an HCL attribute which consists of an attribute key and a value expression.

BinaryOp

An operation that applies an operator to two expressions.

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.

BodyBuilder

BodyBuilder builds a HCL Body.

Conditional

The conditional operator allows selecting from one of two expressions based on the outcome of a boolean expression.

ForExpr

A for expression is a construct for constructing a collection by projecting the items from another collection.

FuncCall

Represents a function call expression with zero or more arguments.

FuncCallBuilder

A builder for function calls.

Heredoc

A heredoc template expression is introduced by a << sequence and defines a template via a multi-line sequence terminated by a user-chosen delimiter.

Identifier

Represents an HCL identifier.

Number

Represents a HCL number.

RawExpression

A type that holds the value of a raw expression. It can be used to serialize arbitrary HCL expressions.

Traversal

Traverse an expression to access attributes, object keys or element indices.

UnaryOp

An operation that applies an operator to one expression.