summaryrefslogtreecommitdiff
path: root/serde_dhall
diff options
context:
space:
mode:
authorNadrieril2020-10-28 21:59:14 +0000
committerNadrieril2020-10-28 22:52:41 +0000
commit27377f045a2449c86ea3b680d168d2224c90e5e3 (patch)
tree547ace1bb05b27c87615326eebced52ef9a1e55b /serde_dhall
parent3b728aff86a086f71f013b77a715c33748d9f6a8 (diff)
Add missing documentation
Diffstat (limited to 'serde_dhall')
-rw-r--r--serde_dhall/src/lib.rs114
-rw-r--r--serde_dhall/src/options/ser.rs184
-rw-r--r--serde_dhall/src/serialize.rs28
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>;