Expand description
hcl-rs
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
orserde::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 to learn how you can construct HCL blocks when serializing custom types.
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
Error
and Result
types used by this crate.Macros
hcl::Attribute
from a key and a value expression.hcl::Block
from a block identifier, optional block labels and a block body.hcl::Body
from HCL blocks and attributes.hcl::Expression
from an HCL attribute value expression literal.hcl::Structure
which may be either an HCL attribute or block.hcl::Value
from an HCL attribute value value literal.Structs
Enums
Functions
hcl::Body
as an instance of type T
.T
from an IO stream of HCL.T
from a byte slice.T
from a string of HCL text.hcl::Body
from a &str
.T
into hcl::Expression
which is an enum that can represent any valid HCL
attribute value expression.T
into hcl::Value
which is an enum that can represent any valid HCL value.