summaryrefslogtreecommitdiff
path: root/serde_dhall/src/lib.rs
blob: 48f311efd42ad3bfc9af6c8a9725d2b093a85178 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
#![feature(non_exhaustive)]

//! [Dhall][dhall] is a programmable configuration language that provides a non-repetitive
//! alternative to JSON and YAML.
//!
//! You can think of Dhall as: JSON + types + imports + functions
//!
//! For a description of the Dhall language, examples, tutorials, and more, see the [language
//! website][dhall].
//!
//! This crate provides support for consuming Dhall files the same way you would consume JSON or
//! YAML. It uses the [Serde][serde] serialization library to provide drop-in support for Dhall
//! for any datatype that supports serde (and that's a lot of them !).
//!
//! This library is limited to deserializing (reading) Dhall values; serializing (writing)
//! values to Dhall is not supported for now.
//!
//! # Examples
//!
//! ### Custom datatype
//!
//! If you have a custom datatype for which you derived [serde::Deserialize], chances are
//! you will be able to derive [StaticType] for it as well.
//! This allows easy type-safe deserializing.
//!
//! ```edition2018
//! use serde::Deserialize;
//! use serde_dhall::{de::Error, StaticType};
//!
//! #[derive(Debug, Deserialize, StaticType)]
//! struct Point {
//!     x: u64,
//!     y: u64,
//! }
//!
//! fn main() -> Result<(), Error> {
//!     // Some Dhall data
//!     let data = "{ x = 1, y = 1 + 1 }";
//!
//!     // Convert the Dhall string to a Point.
//!     let point: Point = serde_dhall::from_str_auto_type(data)?;
//!     assert_eq!(point.x, 1);
//!     assert_eq!(point.y, 2);
//!
//!     // Invalid data fails the type validation
//!     let invalid_data = "{ x = 1, z = 0.3 }";
//!     assert!(serde_dhall::from_str_auto_type::<Point>(invalid_data).is_err());
//!
//!     Ok(())
//! }
//! ```
//!
//! ### Loosely typed
//!
//! If you used to consume JSON or YAML in a loosely typed way, you can continue to do so
//! with Dhall. You only need to replace [serde_json::from_str] or [serde_yaml::from_str]
//! with [serde_dhall::from_str][from_str].
//! More generally, if the [StaticType] derive doesn't suit your
//! needs, you can still deserialize any valid Dhall file that serde can handle.
//!
//! [serde_json::from_str]: https://docs.serde.rs/serde_json/de/fn.from_str.html
//! [serde_yaml::from_str]: https://docs.serde.rs/serde_yaml/fn.from_str.html
//!
//! ```edition2018
//! # fn main() -> serde_dhall::de::Result<()> {
//! use std::collections::BTreeMap;
//!
//! // Some Dhall data
//! let data = "{ x = 1, y = 1 + 1 } : { x: Natural, y: Natural }";
//!
//! // Deserialize it to a Rust type.
//! let deserialized_map: BTreeMap<String, usize> = serde_dhall::from_str(data)?;
//!
//! let mut expected_map = BTreeMap::new();
//! expected_map.insert("x".to_string(), 1);
//! expected_map.insert("y".to_string(), 2);
//!
//! assert_eq!(deserialized_map, expected_map);
//! # Ok(())
//! # }
//! ```
//!
//! You can alternatively specify a Dhall type that the input should match.
//!
//! ```edition2018
//! # fn main() -> serde_dhall::de::Result<()> {
//! use std::collections::BTreeMap;
//!
//! // Parse a Dhall type
//! let point_type_str = "{ x: Natural, y: Natural }";
//! let point_type = serde_dhall::from_str(point_type_str)?;
//!
//! // Some Dhall data
//! let point_data = "{ x = 1, y = 1 + 1 }";
//!
//! // Deserialize the data to a Rust type. This ensures that
//! // the data matches the point type.
//! let deserialized_map: BTreeMap<String, usize> =
//!         serde_dhall::from_str_check_type(point_data, &point_type)?;
//!
//! let mut expected_map = BTreeMap::new();
//! expected_map.insert("x".to_string(), 1);
//! expected_map.insert("y".to_string(), 2);
//!
//! assert_eq!(deserialized_map, expected_map);
//! # Ok(())
//! # }
//! ```
//!
//! [dhall]: https://dhall-lang.org/
//! [serde]: https://docs.serde.rs/serde/
//! [serde::Deserialize]: https://docs.serde.rs/serde/trait.Deserialize.html

mod serde;
mod static_type;

#[doc(inline)]
pub use de::{from_str, from_str_auto_type, from_str_check_type};
#[doc(hidden)]
pub use dhall_proc_macros::StaticType;
pub use static_type::StaticType;
#[doc(inline)]
pub use value::Value;

// A Dhall value.
pub mod value {
    use dhall::core::value::TypedValue as TypedThunk;
    use dhall::core::value::Value as Thunk;
    use dhall::core::valuef::ValueF as DhallValue;
    use dhall::phase::{NormalizedSubExpr, Parsed, Type, Typed};
    use dhall_syntax::Builtin;

    use super::de::{Error, Result};

    /// A Dhall value
    #[derive(Debug, Clone, PartialEq, Eq)]
    pub struct Value(Typed);

    impl Value {
        pub fn from_str(s: &str, ty: Option<&Value>) -> Result<Self> {
            Value::from_str_using_dhall_error_type(s, ty).map_err(Error::Dhall)
        }
        fn from_str_using_dhall_error_type(
            s: &str,
            ty: Option<&Value>,
        ) -> dhall::error::Result<Self> {
            let resolved = Parsed::parse_str(s)?.resolve()?;
            let typed = match ty {
                None => resolved.typecheck()?,
                Some(t) => resolved.typecheck_with(&t.to_type())?,
            };
            Ok(Value(typed))
        }
        pub(crate) fn to_expr(&self) -> NormalizedSubExpr {
            self.0.to_expr()
        }
        pub(crate) fn to_value(&self) -> Thunk {
            self.0.to_value()
        }
        pub(crate) fn to_type(&self) -> Type {
            self.0.to_type()
        }

        /// Assumes that the given value has type `Type`.
        pub(crate) fn make_simple_type(v: DhallValue) -> Self {
            Value(Typed::from_valuef_and_type(v, Type::const_type()))
        }
        pub(crate) fn make_builtin_type(b: Builtin) -> Self {
            Self::make_simple_type(DhallValue::from_builtin(b))
        }
        pub(crate) fn make_optional_type(t: Value) -> Self {
            Self::make_simple_type(
                DhallValue::from_builtin(Builtin::Optional)
                    .app_value(t.to_value()),
            )
        }
        pub(crate) fn make_list_type(t: Value) -> Self {
            Self::make_simple_type(
                DhallValue::from_builtin(Builtin::List).app_value(t.to_value()),
            )
        }
        // Made public for the StaticType derive macro
        #[doc(hidden)]
        pub fn make_record_type(
            kts: impl Iterator<Item = (String, Value)>,
        ) -> Self {
            Self::make_simple_type(DhallValue::RecordType(
                kts.map(|(k, t)| {
                    (k.into(), TypedThunk::from_value_simple_type(t.to_value()))
                })
                .collect(),
            ))
        }
        #[doc(hidden)]
        pub fn make_union_type(
            kts: impl Iterator<Item = (String, Option<Value>)>,
        ) -> Self {
            Self::make_simple_type(DhallValue::UnionType(
                kts.map(|(k, t)| {
                    (
                        k.into(),
                        t.map(|t| {
                            TypedThunk::from_value_simple_type(t.to_value())
                        }),
                    )
                })
                .collect(),
            ))
        }
    }

    impl super::de::Deserialize for Value {
        fn from_dhall(v: &Value) -> Result<Self> {
            Ok(v.clone())
        }
    }
}

/// Deserialize Dhall data to a Rust data structure.
pub mod de {
    use super::StaticType;
    use super::Value;
    pub use error::{Error, Result};

    mod error {
        use dhall::error::Error as DhallError;

        pub type Result<T> = std::result::Result<T, Error>;

        #[derive(Debug)]
        #[non_exhaustive]
        pub enum Error {
            Dhall(DhallError),
            Deserialize(String),
        }

        impl std::fmt::Display for Error {
            fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
                match self {
                    Error::Dhall(err) => write!(f, "{}", err),
                    Error::Deserialize(err) => write!(f, "{}", err),
                }
            }
        }

        impl std::error::Error for Error {}

        impl serde::de::Error for Error {
            fn custom<T>(msg: T) -> Self
            where
                T: std::fmt::Display,
            {
                Error::Deserialize(msg.to_string())
            }
        }
    }

    /// A data structure that can be deserialized from a Dhall expression
    ///
    /// This is automatically implemented for any type that [serde][serde]
    /// can deserialize.
    ///
    /// This trait cannot be implemented manually.
    // TODO: seal trait
    pub trait Deserialize: Sized {
        /// See [serde_dhall::from_str][crate::from_str]
        fn from_dhall(v: &Value) -> Result<Self>;
    }

    /// Deserialize an instance of type `T` from a string of Dhall text.
    ///
    /// This will recursively resolve all imports in the expression, and
    /// typecheck it before deserialization. Relative imports will be resolved relative to the
    /// provided file. More control over this process is not yet available
    /// but will be in a coming version of this crate.
    pub fn from_str<T>(s: &str) -> Result<T>
    where
        T: Deserialize,
    {
        T::from_dhall(&Value::from_str(s, None)?)
    }

    /// Deserialize an instance of type `T` from a string of Dhall text,
    /// additionally checking that it matches the supplied type.
    ///
    /// Like [from_str], but this additionally checks that
    /// the type of the provided expression matches the supplied type.
    pub fn from_str_check_type<T>(s: &str, ty: &Value) -> Result<T>
    where
        T: Deserialize,
    {
        T::from_dhall(&Value::from_str(s, Some(ty))?)
    }

    /// Deserialize an instance of type `T` from a string of Dhall text,
    /// additionally checking that it matches the type of `T`.
    ///
    /// Like [from_str], but this additionally checks that
    /// the type of the provided expression matches the output type `T`. The [StaticType] trait
    /// captures Rust types that are valid Dhall types.
    pub fn from_str_auto_type<T>(s: &str) -> Result<T>
    where
        T: Deserialize + StaticType,
    {
        from_str_check_type(s, &<T as StaticType>::static_type())
    }
}