summaryrefslogtreecommitdiff
path: root/dhall/src
diff options
context:
space:
mode:
authorNadrieril2019-04-13 00:44:58 +0200
committerNadrieril2019-04-13 00:44:58 +0200
commite7e79bf32c385fa8c30a45be262ca3d6d8f1f653 (patch)
tree769651e0c22c9d15069f8fee24c82a3eecfb1f1d /dhall/src
parentca0939f4cdf373ca735f25926d0a02c698d7f1cf (diff)
Document all of the API
Closes #64
Diffstat (limited to 'dhall/src')
-rw-r--r--dhall/src/expr.rs13
-rw-r--r--dhall/src/lib.rs17
-rw-r--r--dhall/src/traits/deserialize.rs7
-rw-r--r--dhall/src/traits/static_type.rs33
4 files changed, 60 insertions, 10 deletions
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<X, X>,
@@ -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<Normalized<'a>>),
- // 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<T> {
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<Self>;
}
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<bool>`,
-/// represented by the dhall expression `Optional Bool`. A typical counterexample
-/// is `HashMap<Text, bool>` 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<bool>`,
+/// 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<String, bool>` 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<T: SimpleStaticType> 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<T: SimpleStaticType> SimpleStaticType for Vec<T> {
}
}
-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()
}
}