diff options
| -rw-r--r-- | serde_dhall/src/lib.rs | 114 | ||||
| -rw-r--r-- | serde_dhall/src/options/ser.rs | 184 | ||||
| -rw-r--r-- | serde_dhall/src/serialize.rs | 28 |
3 files changed, 316 insertions, 10 deletions
diff --git a/serde_dhall/src/lib.rs b/serde_dhall/src/lib.rs index e236e37..387278b 100644 --- a/serde_dhall/src/lib.rs +++ b/serde_dhall/src/lib.rs @@ -12,13 +12,12 @@ //! 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. -//! //! # Basic usage //! -//! The main entrypoint of this library is the [`from_str`](fn.from_str.html) function. It reads a string -//! containing a Dhall expression and deserializes it into any serde-compatible type. +//! ## Deserialization (reading) +//! +//! The entrypoint for deserialization is the [`from_str`](fn.from_str.html) function. It reads a +//! string containing a Dhall expression and deserializes it into any serde-compatible type. //! //! This could mean a common Rust type like `HashMap`: //! @@ -65,16 +64,69 @@ //! # } //! ``` //! +//! ## Serialization (writing) +//! +//! The entrypoint for serialization is the [`serialize`](fn.serialize.html) function. It takes a +//! serde-compatible type value and serializes it to a string containing a Dhall expression. +//! +//! This could mean a common Rust type like `HashMap`: +//! +//! ```rust +//! # fn main() -> serde_dhall::Result<()> { +//! use std::collections::HashMap; +//! +//! let mut map = HashMap::new(); +//! map.insert("x".to_string(), 1u64); +//! map.insert("y".to_string(), 2u64); +//! +//! let string = serde_dhall::serialize(&map).to_string()?; +//! assert_eq!( +//! string, +//! "{ x = 1, y = 2 }".to_string(), +//! ); +//! # Ok(()) +//! # } +//! ``` +//! +//! or a custom datatype, using serde's `derive` mechanism: +//! +//! ```rust +//! # fn main() -> serde_dhall::Result<()> { +//! use serde::Serialize; +//! +//! #[derive(Serialize)] +//! struct Point { +//! x: u64, +//! y: u64, +//! } +//! +//! let data = Point { x: 1, y: 2 }; +//! let string = serde_dhall::serialize(&data).to_string()?; +//! assert_eq!( +//! string, +//! "{ x = 1, y = 2 }".to_string(), +//! ); +//! # Ok(()) +//! # } +//! ``` +//! +//! Beware that in order to serialize empty options, empty lists or enums correctly, you will need +//! to provide a type annotation! +//! //! # Replacing `serde_json` or `serde_yaml` //! //! If you used to consume JSON or YAML, you only need to replace [`serde_json::from_str`] or //! [`serde_yaml::from_str`] with [`serde_dhall::from_str(…).parse()`](fn.from_str.html). +//! If you used to produce JSON or YAML, you only need to replace [`serde_json::to_string`] or +//! [`serde_yaml::to_string`] with [`serde_dhall::serialize(…).to_string()`](fn.serialize.html). //! //! [`serde_json::from_str`]: https://docs.serde.rs/serde_json/fn.from_str.html //! [`serde_yaml::from_str`]: https://docs.serde.rs/serde_yaml/fn.from_str.html +//! [`serde_json::to_string`]: https://docs.serde.rs/serde_json/fn.to_string.html +//! [`serde_yaml::to_string`]: https://docs.serde.rs/serde_yaml/fn.to_string.html //! //! -//! # Additional Dhall typechecking +//! # Additional type annotations //! //! When deserializing, normal type checking is done to ensure that the returned value is a valid //! Dhall value. However types are @@ -82,11 +134,16 @@ //! matches a given Dhall type. That way, a type error will be caught on the Dhall side, and have //! pretty and explicit errors that point to the source file. //! -//! There are two ways to typecheck a Dhall value in this way: you can provide the type manually or -//! you can let Rust infer it for you. +//! It is also possible to provide a type annotation when serializing. This is useful in particular +//! for types like `HashMap` or [`SimpleValue`] that do not have a fixed type as Dhall values. +//! +//! Moreover, some values (namely empty options, empty lists, and enums) _require_ a type annotation +//! in order to be converted to Dhall, because the resulting Dhall value will contain the type +//! explicitly. //! -//! To let Rust infer the appropriate Dhall type, use the [StaticType](trait.StaticType.html) -//! trait. +//! There are two ways to provide a type in this way: you can provide it manually or you can let +//! Rust infer it for you. To let Rust infer the appropriate Dhall type, use the +//! [StaticType](trait.StaticType.html) trait. //! //! ```rust //! # fn main() -> serde_dhall::Result<()> { @@ -121,6 +178,28 @@ //! # } //! ``` //! +//! ``` +//! # fn main() -> serde_dhall::Result<()> { +//! use serde::Serialize; +//! use serde_dhall::{serialize, StaticType}; +//! +//! #[derive(Serialize, StaticType)] +//! enum MyOption { +//! MyNone, +//! MySome(u64), +//! } +//! +//! let data = MyOption::MySome(0); +//! let string = serialize(&data) +//! .static_type_annotation() +//! .to_string()?; +//! // The resulting Dhall string depends on the type annotation; it could not have been +//! // printed without it. +//! assert_eq!(string, "< MyNone | MySome: Natural >.MySome 0".to_string()); +//! # Ok(()) +//! # } +//! ``` +//! //! To provide a type manually, you need a [`SimpleType`](enum.SimpleType.html) value. You //! can parse it from some Dhall text like you would parse any other value. //! @@ -151,12 +230,27 @@ //! # } //! ``` //! +//! ``` +//! # fn main() -> serde_dhall::Result<()> { +//! use serde_dhall::{serialize, from_str, SimpleValue}; +//! +//! let ty = from_str("< A | B: Bool >").parse()?; +//! let data = SimpleValue::Union("A".to_string(), None); +//! let string = serialize(&data) +//! .type_annotation(&ty) +//! .to_string()?; +//! assert_eq!(string, "< A | B: Bool >.A".to_string()); +//! # Ok(()) +//! # } +//! ``` +//! //! # Controlling deserialization //! //! If you need more control over the process of reading Dhall values, e.g. disabling //! imports, see the [`Deserializer`] methods. //! //! [`Deserializer`]: struct.Deserializer.html +//! [`SimpleValue`]: enum.SimpleValue.html //! [dhall]: https://dhall-lang.org/ //! [serde]: https://docs.serde.rs/serde/ //! [serde::Deserialize]: https://docs.serde.rs/serde/trait.Deserialize.html diff --git a/serde_dhall/src/options/ser.rs b/serde_dhall/src/options/ser.rs index ea5d16a..3332735 100644 --- a/serde_dhall/src/options/ser.rs +++ b/serde_dhall/src/options/ser.rs @@ -1,6 +1,49 @@ use crate::options::{HasAnnot, ManualAnnot, NoAnnot, StaticAnnot, TypeAnnot}; use crate::{Result, SimpleType, ToDhall}; +/// Controls how a Dhall value is written. +/// +/// This builder exposes the ability to configure how a value is serialized, and to set type +/// annotations. +/// +/// When using [`Serializer`], you'll create it with [`serialize`], then chain calls to methods to +/// set each option, then call [`to_string`]. This will give you a [`Result<String>`] containing +/// the input serialized to Dhall. +/// +/// Note that if you do not provide a type annotation, some values may not be convertible to Dhall, +/// like empty lists or enums. +/// +/// [`Serializer`]: struct.Serializer.html +/// [`serialize`]: fn.serialize.html +/// [`to_string`]: struct.Serializer.html#method.to_string +/// [`Result<String>`]: type.Result.html +/// +/// # Examples +/// +/// Serializing without a type annotation: +/// +/// ```rust +/// # fn main() -> serde_dhall::Result<()> { +/// use serde_dhall::serialize; +/// +/// let string = serialize(&1i64).to_string()?; +/// assert_eq!(string, "+1".to_string()); +/// # Ok(()) +/// # } +/// ``` +/// +/// Serializing with an automatic type annotation: +/// +/// ```rust +/// # fn main() -> serde_dhall::Result<()> { +/// use serde_dhall::serialize; +/// +/// let data: Option<u64> = None; +/// let string = serialize(&data).static_type_annotation().to_string()?; +/// assert_eq!(string, "None Natural".to_string()); +/// # Ok(()) +/// # } +/// ``` #[derive(Debug, Clone)] pub struct Serializer<'a, T, A> { data: &'a T, @@ -8,6 +51,40 @@ pub struct Serializer<'a, T, A> { } impl<'a, T> Serializer<'a, T, NoAnnot> { + /// Provides a type to the serialization process. The provided value will be checked against + /// that type, and the type will be used when Dhall needs it, like for empty lists or for + /// unions. + /// + /// In many cases the Dhall type that corresponds to a Rust type can be inferred automatically. + /// See the [`StaticType`] trait and the [`static_type_annotation`] method for that. + /// + /// # Example + /// + /// ``` + /// # fn main() -> serde_dhall::Result<()> { + /// use serde_dhall::{serialize, from_str, SimpleType, SimpleValue}; + /// + /// let ty = from_str("< A | B: Bool >").parse()?; + /// let data = SimpleValue::Union("A".to_string(), None); + /// let string = serialize(&data) + /// .type_annotation(&ty) + /// .to_string()?; + /// assert_eq!(string, "< A | B: Bool >.A".to_string()); + /// + /// // Invalid data fails the type validation; serialization would have succeeded otherwise. + /// let ty = SimpleType::Integer; + /// assert!( + /// serialize(&Some(0u64)) + /// .type_annotation(&ty) + /// .to_string() + /// .is_err() + /// ); + /// # Ok(()) + /// # } + /// ``` + /// + /// [`static_type_annotation`]: struct.Serializer.html#method.static_type_annotation + /// [`StaticType`]: trait.StaticType.html pub fn type_annotation<'ty>( self, ty: &'ty SimpleType, @@ -18,6 +95,37 @@ impl<'a, T> Serializer<'a, T, NoAnnot> { } } + /// Uses the type of `T` in the serialization process. This will be used when Dhall needs it, + /// like for empty lists or for unions. + /// + /// `T` must implement the [`StaticType`] trait. If it doesn't, you can use [`type_annotation`] + /// + /// # Example + /// + /// ``` + /// # fn main() -> serde_dhall::Result<()> { + /// use serde::Serialize; + /// use serde_dhall::{serialize, StaticType}; + /// + /// #[derive(Serialize, StaticType)] + /// enum MyOption { + /// MyNone, + /// MySome(u64), + /// } + /// + /// let data = MyOption::MySome(0); + /// let string = serialize(&data) + /// .static_type_annotation() + /// .to_string()?; + /// // The resulting Dhall string depends on the type annotation; it could not have been + /// // printed without it. + /// assert_eq!(string, "< MyNone | MySome: Natural >.MySome 0".to_string()); + /// # Ok(()) + /// # } + /// ``` + /// + /// [`type_annotation`]: struct.Serializer.html#method.type_annotation + /// [`StaticType`]: trait.StaticType.html pub fn static_type_annotation(self) -> Serializer<'a, T, StaticAnnot> { Serializer { annot: StaticAnnot, @@ -30,6 +138,27 @@ impl<'a, T, A> Serializer<'a, T, A> where A: TypeAnnot, { + /// Prints the chosen value with the options provided. + /// + /// If you enabled static annotations, `T` is required to implement [`StaticType`]. + /// + /// Note that if you do not provide a type annotation, some values may not be convertible to + /// Dhall, like empty lists or enums. + /// + /// + /// # Example + /// + /// ```rust + /// # fn main() -> serde_dhall::Result<()> { + /// use serde_dhall::serialize; + /// + /// let string = serialize(&1i64).static_type_annotation().to_string()?; + /// assert_eq!(string, "+1".to_string()); + /// # Ok(()) + /// # } + /// ``` + /// + /// [`StaticType`]: trait.StaticType.html pub fn to_string(&self) -> Result<String> where T: ToDhall + HasAnnot<A>, @@ -39,6 +168,61 @@ where } } +/// Serialize a value to a string of Dhall text. +/// +/// This returns a [`Serializer`] object. Call the [`to_string`] method to get the serialized +/// value, or use other [`Serializer`] methods to control the serialization process. +/// +/// In order to process certain values (like unions or empty lists) correctly, it is necessary to +/// add a type annotation (with [`static_type_annotation`] or [`type_annotation`]). +/// +/// # Examples +/// +/// ```rust +/// # fn main() -> serde_dhall::Result<()> { +/// use serde::Serialize; +/// use serde_dhall::{serialize, StaticType}; +/// +/// #[derive(Serialize)] +/// struct Point { +/// x: u64, +/// y: u64, +/// } +/// +/// +/// let data = Point { x: 0, y: 0 }; +/// let string = serialize(&data).to_string()?; +/// assert_eq!(string, "{ x = 0, y = 0 }"); +/// # Ok(()) +/// # } +/// ``` +/// +/// ```rust +/// # fn main() -> serde_dhall::Result<()> { +/// use serde::Serialize; +/// use serde_dhall::{serialize, StaticType}; +/// +/// #[derive(Serialize, StaticType)] +/// enum MyOption { +/// MyNone, +/// MySome(u64), +/// } +/// +/// let data = MyOption::MySome(0); +/// let string = serialize(&data) +/// .static_type_annotation() +/// .to_string()?; +/// // The resulting Dhall string depends on the type annotation; it could not have been +/// // printed without it. +/// assert_eq!(string, "< MyNone | MySome: Natural >.MySome 0".to_string()); +/// # Ok(()) +/// # } +/// ``` +/// +/// [`Serializer`]: struct.Serializer.html +/// [`type_annotation`]: struct.Serializer.html#method.type_annotation +/// [`static_type_annotation`]: struct.Serializer.html#method.static_type_annotation +/// [`to_string`]: struct.Serializer.html#method.to_string pub fn serialize<'a, T>(data: &'a T) -> Serializer<'a, T, NoAnnot> where T: ToDhall, diff --git a/serde_dhall/src/serialize.rs b/serde_dhall/src/serialize.rs index 21b1931..632dace 100644 --- a/serde_dhall/src/serialize.rs +++ b/serde_dhall/src/serialize.rs @@ -9,6 +9,34 @@ use SimpleValue::*; pub trait Sealed {} +/// A data structure that can be serialized from a Dhall expression. +/// +/// This is automatically implemented for any type that [serde] can serialize. +/// In fact, this trait cannot be implemented manually. To implement it for your type, +/// use serde's derive mechanism. +/// +/// # Example +/// +/// ```rust +/// # fn main() -> serde_dhall::Result<()> { +/// use serde::Serialize; +/// +/// // Use serde's derive +/// #[derive(Serialize)] +/// struct Point { +/// x: u64, +/// y: u64, +/// } +/// +/// // Convert a Point to a Dhall string. +/// let point = Point { x: 0, y: 0 }; +/// let point_str = serde_dhall::serialize(&point).to_string()?; +/// assert_eq!(point_str, "{ x = 0, y = 0 }".to_string()); +/// # Ok(()) +/// # } +/// ``` +/// +/// [serde]: https://serde.rs pub trait ToDhall: Sealed { #[doc(hidden)] fn to_dhall(&self, ty: Option<&SimpleType>) -> Result<Value>; |