From e070270c3f1f10d46281ed7751ff95e15092e7f4 Mon Sep 17 00:00:00 2001 From: Nadrieril Date: Sun, 10 May 2020 22:09:43 +0100 Subject: Implement serialization --- serde_dhall/src/options/de.rs | 372 +++++++++++++++++++++++++++++++++++++++++ serde_dhall/src/options/mod.rs | 2 + serde_dhall/src/options/ser.rs | 67 ++++++++ 3 files changed, 441 insertions(+) create mode 100644 serde_dhall/src/options/de.rs create mode 100644 serde_dhall/src/options/mod.rs create mode 100644 serde_dhall/src/options/ser.rs (limited to 'serde_dhall/src/options') diff --git a/serde_dhall/src/options/de.rs b/serde_dhall/src/options/de.rs new file mode 100644 index 0000000..8ff794d --- /dev/null +++ b/serde_dhall/src/options/de.rs @@ -0,0 +1,372 @@ +use std::path::{Path, PathBuf}; + +use dhall::Parsed; + +use crate::SimpleType; +use crate::{Error, ErrorKind, FromDhall, Result, StaticType, Value}; + +#[derive(Debug, Clone)] +enum Source<'a> { + Str(&'a str), + File(PathBuf), + // Url(&'a str), +} + +#[derive(Debug, Clone, Copy)] +pub struct NoAnnot; +#[derive(Debug, Clone, Copy)] +pub struct ManualAnnot<'ty>(&'ty SimpleType); +#[derive(Debug, Clone, Copy)] +pub struct StaticAnnot; + +pub trait OptionalAnnot { + fn get_annot(a: &A) -> Option; +} +impl OptionalAnnot for T { + fn get_annot(_: &NoAnnot) -> Option { + None + } +} +impl<'ty, T> OptionalAnnot> for T { + fn get_annot(a: &ManualAnnot<'ty>) -> Option { + Some(a.0.clone()) + } +} +impl OptionalAnnot for T { + fn get_annot(_: &StaticAnnot) -> Option { + Some(T::static_type()) + } +} + +/// Controls how a Dhall value is read. +/// +/// This builder exposes the ability to configure how a value is deserialized and what operations +/// are permitted during evaluation. +/// +/// Generally speaking, when using [`Deserializer`], you'll create it with [`from_str`] or [`from_file`], then +/// chain calls to methods to set each option, then call [`parse`]. This will give you a +/// [`Result`] where `T` is a deserializable type of your choice. +/// +/// [`Deserializer`]: struct.Deserializer.html +/// [`from_str`]: fn.from_str.html +/// [`from_file`]: fn.from_file.html +/// [`parse`]: struct.Deserializer.html#method.parse +/// [`Result`]: type.Result.html +/// +/// # Examples +/// +/// Reading from a file: +/// +/// ```no_run +/// # fn main() -> serde_dhall::Result<()> { +/// use serde_dhall::from_file; +/// +/// let data = from_file("foo.dhall").parse::()?; +/// # Ok(()) +/// # } +/// ``` +/// +/// Reading from a file and checking the value against a provided type: +/// +/// ```no_run +/// # fn main() -> serde_dhall::Result<()> { +/// use std::collections::HashMap; +/// use serde_dhall::{from_file, from_str}; +/// +/// let ty = from_str("{ x: Natural, y: Natural }").parse()?; +/// let data = from_file("foo.dhall") +/// .type_annotation(&ty) +/// .parse::>()?; +/// # Ok(()) +/// # } +/// ``` +#[derive(Debug, Clone)] +pub struct Deserializer<'a, A> { + source: Source<'a>, + annot: A, + allow_imports: bool, + // allow_remote_imports: bool, + // use_cache: bool, +} + +impl<'a> Deserializer<'a, NoAnnot> { + fn default_with_source(source: Source<'a>) -> Self { + Deserializer { + source, + annot: NoAnnot, + allow_imports: true, + // allow_remote_imports: true, + // use_cache: true, + } + } + fn from_str(s: &'a str) -> Self { + Self::default_with_source(Source::Str(s)) + } + fn from_file>(path: P) -> Self { + Self::default_with_source(Source::File(path.as_ref().to_owned())) + } + // fn from_url(url: &'a str) -> Self { + // Self::default_with_source(Source::Url(url)) + // } + + /// Ensures that the parsed value matches the provided type. + /// + /// 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 std::collections::HashMap; + /// use serde::Deserialize; + /// use serde_dhall::{from_str, SimpleType}; + /// + /// // Parse a Dhall type + /// let type_str = "{ x: Natural, y: Natural }"; + /// let ty = from_str(type_str).parse::()?; + /// + /// // Parse some Dhall data. + /// let data = "{ x = 1, y = 1 + 1 }"; + /// let point = from_str(data) + /// .type_annotation(&ty) + /// .parse::>()?; + /// assert_eq!(point.get("y"), Some(&2)); + /// + /// // Invalid data fails the type validation; deserialization would have succeeded otherwise. + /// let invalid_data = "{ x = 1, z = 3 }"; + /// assert!( + /// from_str(invalid_data) + /// .type_annotation(&ty) + /// .parse::>() + /// .is_err() + /// ); + /// # Ok(()) + /// # } + /// ``` + /// + /// [`static_type_annotation`]: struct.Deserializer.html#method.static_type_annotation + /// [`StaticType`]: trait.StaticType.html + pub fn type_annotation<'ty>( + self, + ty: &'ty SimpleType, + ) -> Deserializer<'a, ManualAnnot<'ty>> { + Deserializer { + annot: ManualAnnot(ty), + source: self.source, + allow_imports: self.allow_imports, + } + } + + /// Ensures that the parsed value matches the type of `T`. + /// + /// `T` must implement the [`StaticType`] trait. If it doesn't, you can use [`type_annotation`] + /// to provide a type manually. + /// + /// # Example + /// + /// ``` + /// # fn main() -> serde_dhall::Result<()> { + /// use serde::Deserialize; + /// use serde_dhall::StaticType; + /// + /// #[derive(Deserialize, StaticType)] + /// struct Point { + /// x: u64, + /// y: Option, + /// } + /// + /// // Some Dhall data + /// let data = "{ x = 1, y = Some (1 + 1) }"; + /// + /// // Convert the Dhall string to a Point. + /// let point = serde_dhall::from_str(data) + /// .static_type_annotation() + /// .parse::()?; + /// assert_eq!(point.x, 1); + /// assert_eq!(point.y, Some(2)); + /// + /// // Invalid data fails the type validation; deserialization would have succeeded otherwise. + /// let invalid_data = "{ x = 1 }"; + /// assert!( + /// serde_dhall::from_str(invalid_data) + /// .static_type_annotation() + /// .parse::() + /// .is_err() + /// ); + /// # Ok(()) + /// # } + /// ``` + /// + /// [`type_annotation`]: struct.Deserializer.html#method.type_annotation + /// [`StaticType`]: trait.StaticType.html + pub fn static_type_annotation(self) -> Deserializer<'a, StaticAnnot> { + Deserializer { + annot: StaticAnnot, + source: self.source, + allow_imports: self.allow_imports, + } + } +} + +impl<'a, A> Deserializer<'a, A> { + /// Sets whether to enable imports. + /// + /// By default, imports are enabled. + /// + /// # Example + /// + /// ``` + /// # fn main() -> serde_dhall::Result<()> { + /// use serde::Deserialize; + /// use serde_dhall::SimpleType; + /// + /// let data = "12 + ./other_file.dhall : Natural"; + /// assert!( + /// serde_dhall::from_str(data) + /// .imports(false) + /// .parse::() + /// .is_err() + /// ); + /// # Ok(()) + /// # } + /// ``` + /// + /// [`static_type_annotation`]: struct.Deserializer.html#method.static_type_annotation + /// [`StaticType`]: trait.StaticType.html + pub fn imports(self, imports: bool) -> Self { + Deserializer { + allow_imports: imports, + ..self + } + } + + // /// TODO + // pub fn remote_imports(&mut self, imports: bool) -> &mut Self { + // self.allow_remote_imports = imports; + // if imports { + // self.allow_imports = true; + // } + // self + // } + + fn _parse(&self) -> dhall::error::Result + where + T: OptionalAnnot, + { + let parsed = match &self.source { + Source::Str(s) => Parsed::parse_str(s)?, + Source::File(p) => Parsed::parse_file(p.as_ref())?, + }; + let resolved = if self.allow_imports { + parsed.resolve()? + } else { + parsed.skip_resolve()? + }; + let typed = match &T::get_annot(&self.annot) { + None => resolved.typecheck()?, + Some(ty) => resolved.typecheck_with(ty.to_value().as_hir())?, + }; + Ok(Value::from_nir(typed.normalize().as_nir())) + } + + /// Parses the chosen dhall value with the options provided. + /// + /// If you enabled static annotations, `T` is required to implement [`StaticType`]. + /// + /// + /// # Example + /// + /// ``` + /// # fn main() -> serde_dhall::Result<()> { + /// let data = serde_dhall::from_str("6 * 7").parse::()?; + /// assert_eq!(data, 42); + /// # Ok(()) + /// # } + /// ``` + /// [`StaticType`]: trait.StaticType.html + pub fn parse(&self) -> Result + where + T: FromDhall + OptionalAnnot, + { + let val = self + ._parse::() + .map_err(ErrorKind::Dhall) + .map_err(Error)?; + T::from_dhall(&val) + } +} + +/// Deserialize a value from a string of Dhall text. +/// +/// This returns a [`Deserializer`] object. Call the [`parse`] method to get the deserialized +/// value, or use other [`Deserializer`] methods to control the deserialization process. +/// +/// Imports will be resolved relative to the current directory. +/// +/// # Example +/// +/// ```rust +/// # fn main() -> serde_dhall::Result<()> { +/// use serde::Deserialize; +/// +/// // We use serde's derive feature +/// #[derive(Deserialize)] +/// struct Point { +/// x: u64, +/// y: u64, +/// } +/// +/// // Some Dhall data +/// let data = "{ x = 1, y = 1 + 1 } : { x: Natural, y: Natural }"; +/// +/// // Parse the Dhall string as a Point. +/// let point: Point = serde_dhall::from_str(data).parse()?; +/// +/// assert_eq!(point.x, 1); +/// assert_eq!(point.y, 2); +/// # Ok(()) +/// # } +/// ``` +/// +/// [`Deserializer`]: struct.Deserializer.html +/// [`parse`]: struct.Deserializer.html#method.parse +pub fn from_str(s: &str) -> Deserializer<'_, NoAnnot> { + Deserializer::from_str(s) +} + +/// Deserialize a value from a Dhall file. +/// +/// This returns a [`Deserializer`] object. Call the [`parse`] method to get the deserialized +/// value, or use other [`Deserializer`] methods to control the deserialization process. +/// +/// Imports will be resolved relative to the provided file's path. +/// +/// # Example +/// +/// ```no_run +/// # fn main() -> serde_dhall::Result<()> { +/// use serde::Deserialize; +/// +/// // We use serde's derive feature +/// #[derive(Deserialize)] +/// struct Point { +/// x: u64, +/// y: u64, +/// } +/// +/// // Parse the Dhall file as a Point. +/// let point: Point = serde_dhall::from_file("foo.dhall").parse()?; +/// # Ok(()) +/// # } +/// ``` +/// +/// [`Deserializer`]: struct.Deserializer.html +/// [`parse`]: struct.Deserializer.html#method.parse +pub fn from_file<'a, P: AsRef>(path: P) -> Deserializer<'a, NoAnnot> { + Deserializer::from_file(path) +} + +// pub fn from_url(url: &str) -> Deserializer<'_, NoAnnot> { +// Deserializer::from_url(url) +// } diff --git a/serde_dhall/src/options/mod.rs b/serde_dhall/src/options/mod.rs new file mode 100644 index 0000000..384f318 --- /dev/null +++ b/serde_dhall/src/options/mod.rs @@ -0,0 +1,2 @@ +pub(crate) mod de; +pub(crate) mod ser; diff --git a/serde_dhall/src/options/ser.rs b/serde_dhall/src/options/ser.rs new file mode 100644 index 0000000..026dd21 --- /dev/null +++ b/serde_dhall/src/options/ser.rs @@ -0,0 +1,67 @@ +use crate::{Result, SimpleType, StaticType, ToDhall}; + +#[derive(Debug, Clone, Copy)] +pub struct NoAnnot; +#[derive(Debug, Clone, Copy)] +pub struct ManualAnnot<'ty>(&'ty SimpleType); +#[derive(Debug, Clone, Copy)] +pub struct StaticAnnot; + +pub trait RequiredAnnot { + fn get_annot(a: &A) -> SimpleType; +} +impl<'ty, T> RequiredAnnot> for T { + fn get_annot(a: &ManualAnnot<'ty>) -> SimpleType { + a.0.clone() + } +} +impl RequiredAnnot for T { + fn get_annot(_: &StaticAnnot) -> SimpleType { + T::static_type() + } +} + +#[derive(Debug, Clone)] +pub struct Serializer<'a, T, A> { + data: &'a T, + annot: A, +} + +impl<'a, T> Serializer<'a, T, NoAnnot> { + pub fn type_annotation<'ty>( + self, + ty: &'ty SimpleType, + ) -> Serializer<'a, T, ManualAnnot<'ty>> { + Serializer { + annot: ManualAnnot(ty), + data: self.data, + } + } + + pub fn static_type_annotation(self) -> Serializer<'a, T, StaticAnnot> { + Serializer { + annot: StaticAnnot, + data: self.data, + } + } +} + +impl<'a, T, A> Serializer<'a, T, A> { + pub fn to_string(&self) -> Result + where + T: ToDhall + RequiredAnnot, + { + let val = self.data.to_dhall(&T::get_annot(&self.annot))?; + Ok(val.to_string()) + } +} + +pub fn serialize<'a, T>(data: &'a T) -> Serializer<'a, T, NoAnnot> +where + T: ToDhall, +{ + Serializer { + data, + annot: NoAnnot, + } +} -- cgit v1.2.3 From 3b728aff86a086f71f013b77a715c33748d9f6a8 Mon Sep 17 00:00:00 2001 From: Nadrieril Date: Wed, 28 Oct 2020 21:45:42 +0000 Subject: Make type annotation optional to allow serializing SimpleValue --- serde_dhall/src/options/de.rs | 37 +++++++------------------------------ serde_dhall/src/options/mod.rs | 34 ++++++++++++++++++++++++++++++++++ serde_dhall/src/options/ser.rs | 33 ++++++++------------------------- 3 files changed, 49 insertions(+), 55 deletions(-) (limited to 'serde_dhall/src/options') diff --git a/serde_dhall/src/options/de.rs b/serde_dhall/src/options/de.rs index 8ff794d..e4f3456 100644 --- a/serde_dhall/src/options/de.rs +++ b/serde_dhall/src/options/de.rs @@ -2,8 +2,9 @@ use std::path::{Path, PathBuf}; use dhall::Parsed; +use crate::options::{HasAnnot, ManualAnnot, NoAnnot, StaticAnnot, TypeAnnot}; use crate::SimpleType; -use crate::{Error, ErrorKind, FromDhall, Result, StaticType, Value}; +use crate::{Error, ErrorKind, FromDhall, Result, Value}; #[derive(Debug, Clone)] enum Source<'a> { @@ -12,32 +13,6 @@ enum Source<'a> { // Url(&'a str), } -#[derive(Debug, Clone, Copy)] -pub struct NoAnnot; -#[derive(Debug, Clone, Copy)] -pub struct ManualAnnot<'ty>(&'ty SimpleType); -#[derive(Debug, Clone, Copy)] -pub struct StaticAnnot; - -pub trait OptionalAnnot { - fn get_annot(a: &A) -> Option; -} -impl OptionalAnnot for T { - fn get_annot(_: &NoAnnot) -> Option { - None - } -} -impl<'ty, T> OptionalAnnot> for T { - fn get_annot(a: &ManualAnnot<'ty>) -> Option { - Some(a.0.clone()) - } -} -impl OptionalAnnot for T { - fn get_annot(_: &StaticAnnot) -> Option { - Some(T::static_type()) - } -} - /// Controls how a Dhall value is read. /// /// This builder exposes the ability to configure how a value is deserialized and what operations @@ -252,7 +227,8 @@ impl<'a, A> Deserializer<'a, A> { fn _parse(&self) -> dhall::error::Result where - T: OptionalAnnot, + A: TypeAnnot, + T: HasAnnot, { let parsed = match &self.source { Source::Str(s) => Parsed::parse_str(s)?, @@ -263,7 +239,7 @@ impl<'a, A> Deserializer<'a, A> { } else { parsed.skip_resolve()? }; - let typed = match &T::get_annot(&self.annot) { + let typed = match &T::get_annot(self.annot) { None => resolved.typecheck()?, Some(ty) => resolved.typecheck_with(ty.to_value().as_hir())?, }; @@ -287,7 +263,8 @@ impl<'a, A> Deserializer<'a, A> { /// [`StaticType`]: trait.StaticType.html pub fn parse(&self) -> Result where - T: FromDhall + OptionalAnnot, + A: TypeAnnot, + T: FromDhall + HasAnnot, { let val = self ._parse::() diff --git a/serde_dhall/src/options/mod.rs b/serde_dhall/src/options/mod.rs index 384f318..9241c45 100644 --- a/serde_dhall/src/options/mod.rs +++ b/serde_dhall/src/options/mod.rs @@ -1,2 +1,36 @@ +use crate::{SimpleType, StaticType}; + pub(crate) mod de; pub(crate) mod ser; + +#[derive(Debug, Clone, Copy)] +pub struct NoAnnot; +#[derive(Debug, Clone, Copy)] +pub struct ManualAnnot<'ty>(&'ty SimpleType); +#[derive(Debug, Clone, Copy)] +pub struct StaticAnnot; + +pub trait TypeAnnot: Copy {} +pub trait HasAnnot { + fn get_annot(a: A) -> Option; +} + +impl TypeAnnot for NoAnnot {} +impl TypeAnnot for ManualAnnot<'_> {} +impl TypeAnnot for StaticAnnot {} + +impl HasAnnot for T { + fn get_annot(_: NoAnnot) -> Option { + None + } +} +impl HasAnnot> for T { + fn get_annot(a: ManualAnnot<'_>) -> Option { + Some(a.0.clone()) + } +} +impl HasAnnot for T { + fn get_annot(_: StaticAnnot) -> Option { + Some(T::static_type()) + } +} diff --git a/serde_dhall/src/options/ser.rs b/serde_dhall/src/options/ser.rs index 026dd21..ea5d16a 100644 --- a/serde_dhall/src/options/ser.rs +++ b/serde_dhall/src/options/ser.rs @@ -1,25 +1,5 @@ -use crate::{Result, SimpleType, StaticType, ToDhall}; - -#[derive(Debug, Clone, Copy)] -pub struct NoAnnot; -#[derive(Debug, Clone, Copy)] -pub struct ManualAnnot<'ty>(&'ty SimpleType); -#[derive(Debug, Clone, Copy)] -pub struct StaticAnnot; - -pub trait RequiredAnnot { - fn get_annot(a: &A) -> SimpleType; -} -impl<'ty, T> RequiredAnnot> for T { - fn get_annot(a: &ManualAnnot<'ty>) -> SimpleType { - a.0.clone() - } -} -impl RequiredAnnot for T { - fn get_annot(_: &StaticAnnot) -> SimpleType { - T::static_type() - } -} +use crate::options::{HasAnnot, ManualAnnot, NoAnnot, StaticAnnot, TypeAnnot}; +use crate::{Result, SimpleType, ToDhall}; #[derive(Debug, Clone)] pub struct Serializer<'a, T, A> { @@ -46,12 +26,15 @@ impl<'a, T> Serializer<'a, T, NoAnnot> { } } -impl<'a, T, A> Serializer<'a, T, A> { +impl<'a, T, A> Serializer<'a, T, A> +where + A: TypeAnnot, +{ pub fn to_string(&self) -> Result where - T: ToDhall + RequiredAnnot, + T: ToDhall + HasAnnot, { - let val = self.data.to_dhall(&T::get_annot(&self.annot))?; + let val = self.data.to_dhall(T::get_annot(self.annot).as_ref())?; Ok(val.to_string()) } } -- cgit v1.2.3 From 27377f045a2449c86ea3b680d168d2224c90e5e3 Mon Sep 17 00:00:00 2001 From: Nadrieril Date: Wed, 28 Oct 2020 21:59:14 +0000 Subject: Add missing documentation --- serde_dhall/src/options/ser.rs | 184 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 184 insertions(+) (limited to 'serde_dhall/src/options') 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`] 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`]: 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 = 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 where T: ToDhall + HasAnnot, @@ -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, -- cgit v1.2.3 From af16e9699799f8cfbd228e2832e1d5df3653116b Mon Sep 17 00:00:00 2001 From: Nadrieril Date: Wed, 28 Oct 2020 23:31:57 +0000 Subject: Fix clippy and formatting --- serde_dhall/src/options/ser.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'serde_dhall/src/options') diff --git a/serde_dhall/src/options/ser.rs b/serde_dhall/src/options/ser.rs index 3332735..d74beb0 100644 --- a/serde_dhall/src/options/ser.rs +++ b/serde_dhall/src/options/ser.rs @@ -223,7 +223,7 @@ where /// [`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> +pub fn serialize(data: &T) -> Serializer<'_, T, NoAnnot> where T: ToDhall, { -- cgit v1.2.3