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
§Cargo features
perf
: enables parser performance optimizations such as inlining of small strings on the stack. This feature is disabled by default.
§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 licensed under either of Apache License, Version 2.0 or MIT license at your option.
Re-exports§
pub use hcl_edit as edit;
Modules§
- Deserialize HCL data to a Rust data structure.
- The
Error
andResult
types used by this crate. - Evaluate HCL templates and expressions.
- Types to represent the HCL expression sub-language.
- Format data structures as HCL.
- Serialize a Rust data structure into HCL data.
- Types to represent the HCL structural sub-language.
- Types to represent the HCL template sub-language.
- The Value enum, a loosely typed way of representing any valid HCL value.
Macros§
- Construct an
hcl::Attribute
from a key and a value expression. - Construct an
hcl::Block
from a block identifier, optional block labels and a block body. - Construct an
hcl::Body
from HCL blocks and attributes. - Construct an
hcl::Expression
from an HCL attribute value expression literal. - Construct an
hcl::Structure
which may be either an HCL attribute or block. - Construct an
hcl::Value
from an HCL attribute value value literal.
Structs§
- Represents an HCL attribute which consists of an attribute key and a value expression.
- Represents an HCL block which consists of a block identifier, zero or more block labels and a block body.
- Represents an HCL config file body.
- Represents an HCL identifier.
- An opaque string storage which inlines small strings on the stack if the
perf
feature is enabled. - Represents an HCL number.
- The main type to represent the HCL template sub-languange.
Enums§
- Represents an HCL block label.
- The error type used by this crate.
- A type representing the expression sub-language. It is used in HCL attributes to specify values and in HCL templates.
- Represents an object key.
- Represents an HCL structure.
- Represents any valid HCL value.
Functions§
- Interpret a
hcl::Body
as an instance of typeT
. - Deserialize an instance of type
T
from an IO stream of HCL. - Deserialize an instance of type
T
from a byte slice. - Deserialize an instance of type
T
from a string of HCL text. - Convert a
hcl::Value
into a typeT
that implementsserde::Deserialize
. - Parse a
hcl::Body
from a&str
. - Convert a
T
intohcl::Expression
which is an enum that can represent any valid HCL attribute value expression. - Serialize the given value as an HCL string.
- Convert a
T
intohcl::Value
which is an enum that can represent any valid HCL value. - Serialize the given value as an HCL byte vector.
- Serialize the given value as HCL into the IO stream.
Type Aliases§
- The map type used for HCL objects.
- The object type used in the expression sub-language.
- The result type used by this crate.