hcl/expr/
mod.rs

1//! Types to represent the HCL expression sub-language.
2//!
3//! The module contains the [`Expression`] enum which can represent any valid HCL expression in
4//! HCL attribute values and templates.
5
6mod conditional;
7pub(crate) mod de;
8mod edit;
9mod for_expr;
10mod func_call;
11mod operation;
12pub(crate) mod ser;
13mod template_expr;
14mod traversal;
15mod variable;
16
17use self::ser::ExpressionSerializer;
18pub use self::{
19    conditional::Conditional,
20    for_expr::ForExpr,
21    func_call::{FuncCall, FuncCallBuilder, FuncName},
22    operation::{BinaryOp, BinaryOperator, Operation, UnaryOp, UnaryOperator},
23    template_expr::{Heredoc, HeredocStripMode, TemplateExpr},
24    traversal::{Traversal, TraversalBuilder, TraversalOperator},
25    variable::Variable,
26};
27use crate::format;
28use crate::ser::with_internal_serialization;
29use crate::{Identifier, Number, Result, Value};
30use serde::{Deserialize, Serialize};
31use std::borrow::Cow;
32use std::fmt::{self, Display};
33
34/// The object type used in the expression sub-language.
35pub type Object<K, V> = vecmap::VecMap<K, V>;
36
37/// A type representing the expression sub-language. It is used in HCL attributes to specify
38/// values and in HCL templates.
39#[derive(Debug, Clone, PartialEq, Eq)]
40#[non_exhaustive]
41pub enum Expression {
42    /// Represents a null value.
43    Null,
44    /// Represents a boolean.
45    Bool(bool),
46    /// Represents a number, either integer or float.
47    Number(Number),
48    /// Represents a string that does not contain any template interpolations or template
49    /// directives.
50    String(String),
51    /// Represents array.
52    Array(Vec<Expression>),
53    /// Represents an object.
54    Object(Object<ObjectKey, Expression>),
55    /// A quoted string or heredoc that embeds a program written in the template sub-language.
56    TemplateExpr(Box<TemplateExpr>),
57    /// Represents a variable name identifier.
58    Variable(Variable),
59    /// Represents an attribute or element traversal.
60    Traversal(Box<Traversal>),
61    /// Represents a function call.
62    FuncCall(Box<FuncCall>),
63    /// Represents a sub-expression that is wrapped in parenthesis.
64    Parenthesis(Box<Expression>),
65    /// A conditional operator which selects one of two rexpressions based on the outcome of a
66    /// boolean expression.
67    Conditional(Box<Conditional>),
68    /// An operation which applies a particular operator to either one or two expression terms.
69    Operation(Box<Operation>),
70    /// A construct for constructing a collection by projecting the items from another collection.
71    ForExpr(Box<ForExpr>),
72}
73
74impl Expression {
75    #[doc(hidden)]
76    pub fn from_serializable<T>(value: &T) -> Result<Expression>
77    where
78        T: ?Sized + Serialize,
79    {
80        with_internal_serialization(|| value.serialize(ExpressionSerializer))
81    }
82}
83
84impl From<Expression> for Value {
85    fn from(expr: Expression) -> Self {
86        match expr {
87            Expression::Null => Value::Null,
88            Expression::Bool(b) => Value::Bool(b),
89            Expression::Number(n) => Value::Number(n),
90            Expression::String(s) => Value::String(s),
91            Expression::Array(array) => array.into_iter().collect(),
92            Expression::Object(object) => object.into_iter().collect(),
93            Expression::TemplateExpr(expr) => Value::String(expr.to_string()),
94            Expression::Parenthesis(expr) => Value::from(*expr),
95            other => Value::String(format::to_interpolated_string(&other).unwrap()),
96        }
97    }
98}
99
100impl From<Value> for Expression {
101    fn from(value: Value) -> Self {
102        match value {
103            Value::Null => Expression::Null,
104            Value::Bool(b) => Expression::Bool(b),
105            Value::Number(n) => Expression::Number(n),
106            Value::String(s) => Expression::String(s),
107            Value::Array(array) => array.into_iter().collect(),
108            Value::Object(object) => object.into_iter().collect(),
109        }
110    }
111}
112
113macro_rules! impl_from_integer {
114    ($($ty:ty),*) => {
115        $(
116            impl From<$ty> for Expression {
117                fn from(n: $ty) -> Self {
118                    Expression::Number(n.into())
119                }
120            }
121        )*
122    };
123}
124
125impl_from_integer!(i8, i16, i32, i64, isize);
126impl_from_integer!(u8, u16, u32, u64, usize);
127
128impl From<f32> for Expression {
129    fn from(f: f32) -> Self {
130        From::from(f as f64)
131    }
132}
133
134impl From<f64> for Expression {
135    fn from(f: f64) -> Self {
136        Number::from_f64(f).map_or(Expression::Null, Expression::Number)
137    }
138}
139
140impl From<Number> for Expression {
141    fn from(num: Number) -> Self {
142        Expression::Number(num)
143    }
144}
145
146impl From<bool> for Expression {
147    fn from(b: bool) -> Self {
148        Expression::Bool(b)
149    }
150}
151
152impl From<String> for Expression {
153    fn from(s: String) -> Self {
154        Expression::String(s)
155    }
156}
157
158impl From<&str> for Expression {
159    fn from(s: &str) -> Self {
160        Expression::String(s.to_string())
161    }
162}
163
164impl<'a> From<Cow<'a, str>> for Expression {
165    fn from(s: Cow<'a, str>) -> Self {
166        Expression::String(s.into_owned())
167    }
168}
169
170impl From<Object<ObjectKey, Expression>> for Expression {
171    fn from(f: Object<ObjectKey, Expression>) -> Self {
172        Expression::Object(f)
173    }
174}
175
176impl<T: Into<Expression>> From<Vec<T>> for Expression {
177    fn from(f: Vec<T>) -> Self {
178        Expression::Array(f.into_iter().map(Into::into).collect())
179    }
180}
181
182impl<'a, T: Clone + Into<Expression>> From<&'a [T]> for Expression {
183    fn from(f: &'a [T]) -> Self {
184        Expression::Array(f.iter().cloned().map(Into::into).collect())
185    }
186}
187
188impl<T: Into<Expression>> FromIterator<T> for Expression {
189    fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self {
190        Expression::Array(iter.into_iter().map(Into::into).collect())
191    }
192}
193
194impl<K: Into<ObjectKey>, V: Into<Expression>> FromIterator<(K, V)> for Expression {
195    fn from_iter<I: IntoIterator<Item = (K, V)>>(iter: I) -> Self {
196        Expression::Object(
197            iter.into_iter()
198                .map(|(k, v)| (k.into(), v.into()))
199                .collect(),
200        )
201    }
202}
203
204impl From<()> for Expression {
205    fn from((): ()) -> Self {
206        Expression::Null
207    }
208}
209
210impl From<Traversal> for Expression {
211    fn from(traversal: Traversal) -> Self {
212        Expression::Traversal(Box::new(traversal))
213    }
214}
215
216impl From<FuncCall> for Expression {
217    fn from(func_call: FuncCall) -> Self {
218        Expression::FuncCall(Box::new(func_call))
219    }
220}
221
222impl From<Conditional> for Expression {
223    fn from(cond: Conditional) -> Self {
224        Expression::Conditional(Box::new(cond))
225    }
226}
227
228impl From<Operation> for Expression {
229    fn from(op: Operation) -> Self {
230        Expression::Operation(Box::new(op))
231    }
232}
233
234impl From<UnaryOp> for Expression {
235    fn from(op: UnaryOp) -> Self {
236        Expression::from(Operation::Unary(op))
237    }
238}
239
240impl From<BinaryOp> for Expression {
241    fn from(op: BinaryOp) -> Self {
242        Expression::from(Operation::Binary(op))
243    }
244}
245
246impl From<ForExpr> for Expression {
247    fn from(expr: ForExpr) -> Self {
248        Expression::ForExpr(Box::new(expr))
249    }
250}
251
252impl From<TemplateExpr> for Expression {
253    fn from(expr: TemplateExpr) -> Self {
254        Expression::TemplateExpr(Box::new(expr))
255    }
256}
257
258impl From<Heredoc> for Expression {
259    fn from(heredoc: Heredoc) -> Self {
260        Expression::from(TemplateExpr::Heredoc(heredoc))
261    }
262}
263
264impl From<Variable> for Expression {
265    fn from(variable: Variable) -> Self {
266        Expression::Variable(variable)
267    }
268}
269
270impl Display for Expression {
271    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
272        // Formatting an `Expression` as string cannot fail.
273        let formatted =
274            format::to_string(self).expect("an Expression failed to format unexpectedly");
275        f.write_str(&formatted)
276    }
277}
278
279/// Represents an object key.
280#[derive(Deserialize, Serialize, Debug, Clone, PartialEq, Eq)]
281#[non_exhaustive]
282pub enum ObjectKey {
283    /// Represents an unquoted identifier used as object key.
284    Identifier(Identifier),
285    /// Any valid HCL expression can be an object key.
286    Expression(Expression),
287}
288
289impl<T> From<T> for ObjectKey
290where
291    T: Into<Expression>,
292{
293    fn from(value: T) -> Self {
294        ObjectKey::Expression(value.into())
295    }
296}
297
298impl From<Identifier> for ObjectKey {
299    fn from(ident: Identifier) -> Self {
300        ObjectKey::Identifier(ident)
301    }
302}
303
304impl From<ObjectKey> for String {
305    fn from(key: ObjectKey) -> Self {
306        key.to_string()
307    }
308}
309
310impl From<ObjectKey> for Value {
311    fn from(key: ObjectKey) -> Self {
312        match key {
313            ObjectKey::Expression(expr) => expr.into(),
314            ObjectKey::Identifier(ident) => Value::String(ident.into_inner()),
315        }
316    }
317}
318
319impl Display for ObjectKey {
320    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
321        match self {
322            ObjectKey::Identifier(ident) => Display::fmt(ident, f),
323            ObjectKey::Expression(expr) => match expr {
324                Expression::String(string) => Display::fmt(string, f),
325                expr => Display::fmt(expr, f),
326            },
327        }
328    }
329}
330
331/// Convert a `T` into `hcl::Expression` which is an enum that can represent any valid HCL
332/// attribute value expression.
333///
334/// # Errors
335///
336/// This conversion can fail if `T`'s implementation of `Serialize` decides to
337/// fail, or if `T` contains a map with non-string keys.
338pub fn to_expression<T>(value: T) -> Result<Expression>
339where
340    T: Serialize,
341{
342    Expression::from_serializable(&value)
343}
hcl/expr/mod.rs

hcl/expr/
mod.rs
