diff options
| -rw-r--r-- | serde_dhall/src/shortcuts.rs | 41 | ||||
| -rw-r--r-- | serde_dhall/src/static_type.rs | 33 | ||||
| -rw-r--r-- | serde_dhall/src/value.rs | 10 |
3 files changed, 58 insertions, 26 deletions
diff --git a/serde_dhall/src/shortcuts.rs b/serde_dhall/src/shortcuts.rs index d88b9ac..54888c5 100644 --- a/serde_dhall/src/shortcuts.rs +++ b/serde_dhall/src/shortcuts.rs @@ -4,11 +4,13 @@ use crate::{options, Deserialize, Result, SimpleType, StaticType}; /// /// This will recursively resolve all imports in the expression, and typecheck it before /// deserialization. Relative imports will be resolved relative to the current directory. -/// See [`options`][`options`] for more control over this process. +/// See [`options`] for more control over this process. /// -/// For additional type safety, prefer [`from_str_static_type`][`from_str_static_type`] or -/// [`from_str_manual_type`][`from_str_manual_type`]. +/// For additional type safety, prefer [`from_str_static_type`] or [`from_str_manual_type`]. /// +/// [`options`]: options/index.html +/// [`from_str_manual_type`]: fn.from_str_manual_type.html +/// [`from_str_static_type`]: fn.from_str_static_type.html /// /// # Example /// @@ -16,6 +18,7 @@ use crate::{options, Deserialize, Result, SimpleType, StaticType}; /// # fn main() -> serde_dhall::Result<()> { /// use serde::Deserialize; /// +/// // We use serde's derive feature /// #[derive(Debug, Deserialize)] /// struct Point { /// x: u64, @@ -25,18 +28,15 @@ use crate::{options, Deserialize, Result, SimpleType, StaticType}; /// // Some Dhall data /// let data = "{ x = 1, y = 1 + 1 } : { x: Natural, y: Natural }"; /// -/// // Convert the Dhall string to a Point. +/// // Parse the Dhall string as a Point. /// let point: Point = serde_dhall::from_str(data)?; +/// /// assert_eq!(point.x, 1); /// assert_eq!(point.y, 2); /// /// # Ok(()) /// # } /// ``` -/// -/// [`options`]: options/index.html -/// [`from_str_manual_type`]: fn.from_str_manual_type.html -/// [`from_str_static_type`]: fn.from_str_static_type.html pub fn from_str<T>(s: &str) -> Result<T> where T: Deserialize, @@ -47,8 +47,16 @@ where /// 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. +/// This will recursively resolve all imports in the expression, and typecheck it against the +/// supplied type before deserialization. Relative imports will be resolved relative to the current +/// directory. See [`options`] for more control over this process. +/// +/// See also [`from_str_static_type`]. +/// +/// [`options`]: options/index.html +/// [`from_str_static_type`]: fn.from_str_static_type.html +/// +/// # Example /// /// ```rust /// # fn main() -> serde_dhall::Result<()> { @@ -75,8 +83,6 @@ where /// # Ok(()) /// # } /// ``` -/// -/// TODO pub fn from_str_manual_type<T>(s: &str, ty: &SimpleType) -> Result<T> where T: Deserialize, @@ -87,9 +93,14 @@ where /// 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. +/// `T` must implement the [`StaticType`] trait. +/// +/// This will recursively resolve all imports in the expression, and typecheck it against the +/// type of `T`. Relative imports will be resolved relative to the current +/// directory. See [`options`] for more control over this process. +/// +/// [`options`]: options/index.html +/// [`StaticType`]: trait.StaticType.html /// /// TODO pub fn from_str_static_type<T>(s: &str) -> Result<T> diff --git a/serde_dhall/src/static_type.rs b/serde_dhall/src/static_type.rs index ffbc3ad..19f1202 100644 --- a/serde_dhall/src/static_type.rs +++ b/serde_dhall/src/static_type.rs @@ -2,16 +2,33 @@ use crate::SimpleType; /// A Rust type that can be represented as a Dhall type. /// -/// A typical example is `Option<bool>`, -/// represented by the dhall expression `Optional Bool`. +/// A typical example is `Option<bool>`, represented by the Dhall expression `Optional Bool`. /// -/// This trait can and should be automatically derived. +/// This trait can be automatically derived, and this is the recommended way of implementing it. /// -/// The representation needs to be independent of the value. -/// For this reason, something like `HashMap<String, bool>` cannot implement -/// [StaticType] because each different value would -/// have a different Dhall record type. -/// TODO +/// Some Rust types cannot implement this trait, because there isn't a single Dhall type that +/// corresponds to them. For example, `HashMap<String, u64>` could correspond to multiple different +/// Dhall types, e.g. `{ foo: Natural, bar: Natural }` and `{ baz: Natural }`. +/// +/// # Example +/// +/// ```rust +/// # fn main() -> serde_dhall::Result<()> { +/// use serde_dhall::{SimpleType, StaticType}; +/// +/// #[derive(StaticType)] +/// struct Foo { +/// x: bool, +/// y: Vec<u64>, +/// } +/// +/// let ty: SimpleType = +/// serde_dhall::from_str("{ x: Bool, y: List Natural }")?; +/// +/// assert_eq!(Foo::static_type(), ty); +/// # Ok(()) +/// # } +/// ``` pub trait StaticType { fn static_type() -> SimpleType; } diff --git a/serde_dhall/src/value.rs b/serde_dhall/src/value.rs index f542f0a..bdc914f 100644 --- a/serde_dhall/src/value.rs +++ b/serde_dhall/src/value.rs @@ -36,11 +36,15 @@ pub(crate) enum SimpleValue { /// mismatch happened. /// /// You would typically not manipulate `SimpleType`s by hand but rather let Rust infer it for your -/// datatype using the [`StaticType`][TODO] trait, and methods that require it like -/// [`from_file_static_type`][TODO] and [`Options::static_type_annotation`][TODO]. If you need to supply a +/// datatype using the [`StaticType`] trait, and methods that require it like +/// [`from_file_static_type`] and [`Options::static_type_annotation`]. If you need to supply a /// `SimpleType` manually however, you can deserialize it like any other Dhall value using the /// functions provided by this crate. /// +/// [`StaticType`]: trait.StaticType.html +/// [`from_file_static_type`]: fn.from_file_static_type.html +/// [`Options::static_type_annotation`]: options/struct.Options.html#method.static_type_annotation +/// /// # Examples /// /// ```rust @@ -72,7 +76,7 @@ pub(crate) enum SimpleValue { /// let ty: SimpleType = /// serde_dhall::from_str("{ x: Bool, y: List Natural }")?; /// -/// assert_eq!(ty, Foo::static_type()); +/// assert_eq!(Foo::static_type(), ty); /// # Ok(()) /// # } /// ``` |