From e7e79bf32c385fa8c30a45be262ca3d6d8f1f653 Mon Sep 17 00:00:00 2001 From: Nadrieril Date: Sat, 13 Apr 2019 00:44:58 +0200 Subject: Document all of the API Closes #64 --- dhall/src/expr.rs | 13 +++++++++++-- dhall/src/lib.rs | 17 ++++++++++++++++- dhall/src/traits/deserialize.rs | 7 +++++++ dhall/src/traits/static_type.rs | 33 ++++++++++++++++++++++++++------- 4 files changed, 60 insertions(+), 10 deletions(-) (limited to 'dhall') diff --git a/dhall/src/expr.rs b/dhall/src/expr.rs index 6f9f280..a84b41d 100644 --- a/dhall/src/expr.rs +++ b/dhall/src/expr.rs @@ -50,7 +50,12 @@ pub(crate) struct Normalized<'a>( ); derive_other_traits!(Normalized); -/// An expression of type `Type` (like `Bool` or `Natural -> Text`, but not `Type`) +/// A Dhall expression representing a simple type. +/// +/// This captures what is usually simply called a "type", like +/// `Bool`, `{ x: Integer }` or `Natural -> Text`. +/// +/// For a more general notion of "type", see [Type]. #[derive(Debug, Clone, Eq)] pub struct SimpleType<'a>( pub(crate) SubExpr, @@ -58,13 +63,17 @@ pub struct SimpleType<'a>( ); derive_other_traits!(SimpleType); +/// A Dhall expression representing a (possibly higher-kinded) type. +/// +/// This includes [SimpleType]s but also higher-kinded expressions like +/// `Type`, `Kind` and `{ x: Type }`. #[derive(Debug, Clone, PartialEq, Eq)] pub struct Type<'a>(pub(crate) TypeInternal<'a>); #[derive(Debug, Clone, PartialEq, Eq)] pub(crate) enum TypeInternal<'a> { Expr(Box>), - // The type of `Sort` + /// The type of `Sort` SuperType, } diff --git a/dhall/src/lib.rs b/dhall/src/lib.rs index 73f3c1b..51fb6b7 100644 --- a/dhall/src/lib.rs +++ b/dhall/src/lib.rs @@ -13,7 +13,7 @@ //! [Dhall][dhall] is a programmable configuration language that provides a non-repetitive //! alternative to JSON and YAML. //! -//! You can think of Dhall as: JSON/YAML + types + imports + functions +//! 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]. @@ -130,10 +130,19 @@ mod typecheck; pub use crate::traits::{Deserialize, SimpleStaticType, StaticType}; #[doc(hidden)] pub use dhall_generator::SimpleStaticType; +/// When manipulating Dhall expressions goes wrong. pub mod error; pub mod expr; mod serde; +/// Deserialize an instance of type T from a string of Dhall text. +/// +/// This will recursively resolve all imports in the expression, and +/// typecheck it. More control over this process is not yet available +/// but will be in a coming verions of this crate. +/// +/// If a type is provided, this additionally checks that the provided +/// expression has that type. pub fn from_str<'a, T: Deserialize<'a>>( s: &'a str, ty: Option<&crate::expr::Type>, @@ -141,6 +150,12 @@ pub fn from_str<'a, T: Deserialize<'a>>( T::from_str(s, ty) } +/// Deserialize an instance of type T from a string of Dhall text, +/// additionally checking that it matches the type of T. +/// +/// This will recursively resolve all imports in the expression, and +/// typecheck it. More control over this process is not yet available +/// but will be in a coming verions of this crate. pub fn from_str_auto_type<'a, T: Deserialize<'a> + StaticType>( s: &'a str, ) -> crate::error::Result { diff --git a/dhall/src/traits/deserialize.rs b/dhall/src/traits/deserialize.rs index f1be054..e2e0b05 100644 --- a/dhall/src/traits/deserialize.rs +++ b/dhall/src/traits/deserialize.rs @@ -1,7 +1,14 @@ use crate::error::*; use crate::expr::*; +/// 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. pub trait Deserialize<'a>: Sized { + /// See [dhall::from_str][crate::from_str] fn from_str(s: &'a str, ty: Option<&Type>) -> Result; } diff --git a/dhall/src/traits/static_type.rs b/dhall/src/traits/static_type.rs index 35d91e1..444f464 100644 --- a/dhall/src/traits/static_type.rs +++ b/dhall/src/traits/static_type.rs @@ -2,15 +2,32 @@ use crate::expr::*; use dhall_core::*; use dhall_generator::*; +/// A value that has a statically-known Dhall type. +/// +/// This trait is strictly more general than [SimpleStaticType]. +/// The reason is that it allows an arbitrary [Type] to be returned +/// instead of just a [SimpleType]. +/// +/// For now the only interesting impl is [SimpleType] itself, who +/// has a statically-known type which is not itself a [SimpleType]. pub trait StaticType { fn get_static_type() -> Type<'static>; } -/// Trait for rust types that can be represented in dhall in -/// a single way, independent of the value. A typical example is `Option`, -/// represented by the dhall expression `Optional Bool`. A typical counterexample -/// is `HashMap` because dhall cannot represent records with a -/// variable number of fields. +/// A Rust type that can be represented as a Dhall type. +/// +/// A typical example is `Option`, +/// represented by the dhall expression `Optional Bool`. +/// +/// This trait can and should be automatically derived. +/// +/// The representation needs to be independent of the value. +/// For this reason, something like `HashMap` cannot implement +/// [SimpleStaticType] because each different value would +/// have a different Dhall record type. +/// +/// The `Simple` in `SimpleStaticType` indicates that the returned type is +/// a [SimpleType]. pub trait SimpleStaticType { fn get_simple_static_type<'a>() -> SimpleType<'a>; } @@ -31,6 +48,8 @@ impl StaticType for T { } impl<'a> StaticType for SimpleType<'a> { + /// By definition, a [SimpleType] has type `Type`. + /// This returns the Dhall expression `Type` fn get_static_type() -> Type<'static> { Type::const_type() } @@ -106,8 +125,8 @@ impl SimpleStaticType for Vec { } } -impl<'b, T: SimpleStaticType> SimpleStaticType for &'b T { - fn get_simple_static_type<'a>() -> SimpleType<'a> { +impl<'a, T: SimpleStaticType> SimpleStaticType for &'a T { + fn get_simple_static_type<'b>() -> SimpleType<'b> { T::get_simple_static_type() } } -- cgit v1.2.3