Crate hcl

source ·
Expand description

hcl-rs

Build Status crates.io docs.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
  • Evaluation of the HCL expression and template sub-languages

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

An example to serialize some terraform configuration:

use hcl::expr::Traversal;
use hcl::{Block, Body, Variable};

let body = Body::builder()
    .add_block(
        Block::builder("resource")
            .add_label("aws_sns_topic_subscription")
            .add_label("my-subscription")
            .add_attribute((
                "topic_arn",
                Traversal::builder(Variable::new("aws_sns_topic").unwrap())
                    .attr("my-topic")
                    .attr("arn")
                    .build(),
            ))
            .add_attribute(("protocol", "sqs"))
            .add_attribute((
                "endpoint",
                Traversal::builder(Variable::new("aws_sqs_queue").unwrap())
                    .attr("my-queue")
                    .attr("arn")
                    .build(),
            ))
            .build(),
    )
    .build();

let expected = r#"
resource "aws_sns_topic_subscription" "my-subscription" {
  topic_arn = aws_sns_topic.my-topic.arn
  protocol = "sqs"
  endpoint = aws_sqs_queue.my-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.

Expression evaluation

The eval module documentation contains more details and examples for expression and template evaluation, but here’s a very short example:

use hcl::Value;
use hcl::eval::{Context, Evaluate};
use hcl::expr::TemplateExpr;

let expr = TemplateExpr::from("Hello ${name}!");

let mut ctx = Context::new();
ctx.declare_var("name", "World");

assert_eq!(expr.evaluate(&ctx).unwrap(), Value::from("Hello World!"));

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.
eval
Evaluate HCL templates and expressions.
expr
Types to represent the HCL expression sub-language.
format
Format data structures as HCL.
ser
Serialize a Rust data structure into HCL data.
structure
Types to represent the HCL structural sub-language.
template
Types to represent 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.
body
Construct an hcl::Body from HCL blocks and attributes.
expression
Construct an hcl::Expression from an HCL attribute value expression literal.
structure
Construct an hcl::Structure which may be either an HCL attribute or block.
value
Construct an hcl::Value from an HCL attribute value value literal.

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.
Body
Represents an HCL config file body.
Identifier
Represents an HCL identifier.
Number
Represents an HCL number.
Template
The main type to represent the HCL template sub-languange.

Enums

BlockLabel
Represents an HCL block label.
Error
The error type used by this crate.
Expression
A type representing the expression sub-language. It is used in HCL attributes to specify values and in HCL templates.
ObjectKey
Represents an object key.
Structure
Represents an HCL structure.
Value
Represents any valid HCL value.

Functions

from_body
Interpret a hcl::Body as an instance of type T.
from_reader
Deserialize an instance of type T from an IO stream of HCL.
from_slice
Deserialize an instance of type T from a byte slice.
from_str
Deserialize an instance of type T from a string of HCL text.
parse
Parse a hcl::Body from a &str.
to_expression
Convert a T into hcl::Expression which is an enum that can represent any valid HCL attribute value expression.
to_string
Serialize the given value as an HCL string.
to_value
Convert a T into hcl::Value which is an enum that can represent any valid HCL value.
to_vec
Serialize the given value as an HCL byte vector.
to_writer
Serialize the given value as HCL into the IO stream.

Type Definitions

Map
The map type used for HCL objects.
Object
The object type used in the expression sub-language.
Result
The result type used by this crate.