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::ser::with_internal_serialization;
28use crate::{format, Error, Identifier, Number, Result, Value};
29use serde::{Deserialize, Serialize};
30use std::borrow::Cow;
31use std::fmt::{self, Display};
32use std::str::FromStr;
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 FromStr for Expression {
85    type Err = Error;
86
87    #[inline]
88    fn from_str(s: &str) -> Result<Self, Self::Err> {
89        let expr: hcl_edit::expr::Expression = s.parse()?;
90        Ok(expr.into())
91    }
92}
93
94impl From<Expression> for Value {
95    fn from(expr: Expression) -> Self {
96        match expr {
97            Expression::Null => Value::Null,
98            Expression::Bool(b) => Value::Bool(b),
99            Expression::Number(n) => Value::Number(n),
100            Expression::String(s) => Value::String(s),
101            Expression::Array(array) => array.into_iter().collect(),
102            Expression::Object(object) => object.into_iter().collect(),
103            Expression::TemplateExpr(expr) => Value::String(expr.to_string()),
104            Expression::Parenthesis(expr) => Value::from(*expr),
105            other => Value::String(format::to_interpolated_string(&other).unwrap()),
106        }
107    }
108}
109
110impl From<Value> for Expression {
111    fn from(value: Value) -> Self {
112        match value {
113            Value::Null => Expression::Null,
114            Value::Bool(b) => Expression::Bool(b),
115            Value::Number(n) => Expression::Number(n),
116            Value::String(s) => Expression::String(s),
117            Value::Array(array) => array.into_iter().collect(),
118            Value::Object(object) => object.into_iter().collect(),
119        }
120    }
121}
122
123macro_rules! impl_from_integer {
124    ($($ty:ty),*) => {
125        $(
126            impl From<$ty> for Expression {
127                fn from(n: $ty) -> Self {
128                    Expression::Number(n.into())
129                }
130            }
131        )*
132    };
133}
134
135impl_from_integer!(i8, i16, i32, i64, isize);
136impl_from_integer!(u8, u16, u32, u64, usize);
137
138impl From<f32> for Expression {
139    fn from(f: f32) -> Self {
140        From::from(f as f64)
141    }
142}
143
144impl From<f64> for Expression {
145    fn from(f: f64) -> Self {
146        Number::from_f64(f).map_or(Expression::Null, Expression::Number)
147    }
148}
149
150impl From<Number> for Expression {
151    fn from(num: Number) -> Self {
152        Expression::Number(num)
153    }
154}
155
156impl From<bool> for Expression {
157    fn from(b: bool) -> Self {
158        Expression::Bool(b)
159    }
160}
161
162impl From<String> for Expression {
163    fn from(s: String) -> Self {
164        Expression::String(s)
165    }
166}
167
168impl From<&str> for Expression {
169    fn from(s: &str) -> Self {
170        Expression::String(s.to_string())
171    }
172}
173
174impl<'a> From<Cow<'a, str>> for Expression {
175    fn from(s: Cow<'a, str>) -> Self {
176        Expression::String(s.into_owned())
177    }
178}
179
180impl From<Object<ObjectKey, Expression>> for Expression {
181    fn from(f: Object<ObjectKey, Expression>) -> Self {
182        Expression::Object(f)
183    }
184}
185
186impl<T: Into<Expression>> From<Vec<T>> for Expression {
187    fn from(f: Vec<T>) -> Self {
188        Expression::Array(f.into_iter().map(Into::into).collect())
189    }
190}
191
192impl<'a, T: Clone + Into<Expression>> From<&'a [T]> for Expression {
193    fn from(f: &'a [T]) -> Self {
194        Expression::Array(f.iter().cloned().map(Into::into).collect())
195    }
196}
197
198impl<T: Into<Expression>> FromIterator<T> for Expression {
199    fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self {
200        Expression::Array(iter.into_iter().map(Into::into).collect())
201    }
202}
203
204impl<K: Into<ObjectKey>, V: Into<Expression>> FromIterator<(K, V)> for Expression {
205    fn from_iter<I: IntoIterator<Item = (K, V)>>(iter: I) -> Self {
206        Expression::Object(
207            iter.into_iter()
208                .map(|(k, v)| (k.into(), v.into()))
209                .collect(),
210        )
211    }
212}
213
214impl From<()> for Expression {
215    fn from((): ()) -> Self {
216        Expression::Null
217    }
218}
219
220impl From<Traversal> for Expression {
221    fn from(traversal: Traversal) -> Self {
222        Expression::Traversal(Box::new(traversal))
223    }
224}
225
226impl From<FuncCall> for Expression {
227    fn from(func_call: FuncCall) -> Self {
228        Expression::FuncCall(Box::new(func_call))
229    }
230}
231
232impl From<Conditional> for Expression {
233    fn from(cond: Conditional) -> Self {
234        Expression::Conditional(Box::new(cond))
235    }
236}
237
238impl From<Operation> for Expression {
239    fn from(op: Operation) -> Self {
240        Expression::Operation(Box::new(op))
241    }
242}
243
244impl From<UnaryOp> for Expression {
245    fn from(op: UnaryOp) -> Self {
246        Expression::from(Operation::Unary(op))
247    }
248}
249
250impl From<BinaryOp> for Expression {
251    fn from(op: BinaryOp) -> Self {
252        Expression::from(Operation::Binary(op))
253    }
254}
255
256impl From<ForExpr> for Expression {
257    fn from(expr: ForExpr) -> Self {
258        Expression::ForExpr(Box::new(expr))
259    }
260}
261
262impl From<TemplateExpr> for Expression {
263    fn from(expr: TemplateExpr) -> Self {
264        Expression::TemplateExpr(Box::new(expr))
265    }
266}
267
268impl From<Heredoc> for Expression {
269    fn from(heredoc: Heredoc) -> Self {
270        Expression::from(TemplateExpr::Heredoc(heredoc))
271    }
272}
273
274impl From<Variable> for Expression {
275    fn from(variable: Variable) -> Self {
276        Expression::Variable(variable)
277    }
278}
279
280impl Display for Expression {
281    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
282        // Formatting an `Expression` as string cannot fail.
283        let formatted =
284            format::to_string(self).expect("an Expression failed to format unexpectedly");
285        f.write_str(&formatted)
286    }
287}
288
289/// Represents an object key.
290#[derive(Deserialize, Serialize, Debug, Clone, PartialEq, Eq)]
291#[non_exhaustive]
292pub enum ObjectKey {
293    /// Represents an unquoted identifier used as object key.
294    Identifier(Identifier),
295    /// Any valid HCL expression can be an object key.
296    Expression(Expression),
297}
298
299impl<T> From<T> for ObjectKey
300where
301    T: Into<Expression>,
302{
303    fn from(value: T) -> Self {
304        ObjectKey::Expression(value.into())
305    }
306}
307
308impl From<Identifier> for ObjectKey {
309    fn from(ident: Identifier) -> Self {
310        ObjectKey::Identifier(ident)
311    }
312}
313
314impl From<ObjectKey> for String {
315    fn from(key: ObjectKey) -> Self {
316        key.to_string()
317    }
318}
319
320impl From<ObjectKey> for Value {
321    fn from(key: ObjectKey) -> Self {
322        match key {
323            ObjectKey::Expression(expr) => expr.into(),
324            ObjectKey::Identifier(ident) => Value::String(ident.into_inner()),
325        }
326    }
327}
328
329impl Display for ObjectKey {
330    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
331        match self {
332            ObjectKey::Identifier(ident) => Display::fmt(ident, f),
333            ObjectKey::Expression(expr) => match expr {
334                Expression::String(string) => Display::fmt(string, f),
335                expr => Display::fmt(expr, f),
336            },
337        }
338    }
339}
340
341/// Convert a `T` into `hcl::Expression` which is an enum that can represent any valid HCL
342/// attribute value expression.
343///
344/// # Errors
345///
346/// This conversion can fail if `T`'s implementation of `Serialize` decides to
347/// fail, or if `T` contains a map with non-string keys.
348pub fn to_expression<T>(value: T) -> Result<Expression>
349where
350    T: Serialize,
351{
352    Expression::from_serializable(&value)
353}
hcl/expr/mod.rs

hcl/expr/
mod.rs
