summaryrefslogtreecommitdiff
path: root/dhall/src/api
diff options
context:
space:
mode:
authorNadrieril2019-08-12 23:24:48 +0200
committerNadrieril2019-08-13 14:24:56 +0200
commit52f9ecfc4dac65d305fd920e8c7f748889a0804f (patch)
tree106a54c066d1a38e99a73644f0b8f20df280b7e7 /dhall/src/api
parent7d17d39005531cb77d8eaf32ed7de8938c66f874 (diff)
Move api into its own crate
Diffstat (limited to '')
-rw-r--r--serde_dhall/src/lib.rs (renamed from dhall/src/api/mod.rs)123
-rw-r--r--serde_dhall/src/serde.rs (renamed from dhall/src/api/serde.rs)20
-rw-r--r--serde_dhall/src/static_type.rs (renamed from dhall/src/api/static_type.rs)2
3 files changed, 125 insertions, 20 deletions
diff --git a/dhall/src/api/mod.rs b/serde_dhall/src/lib.rs
index 188b6c0..1dbbf99 100644
--- a/dhall/src/api/mod.rs
+++ b/serde_dhall/src/lib.rs
@@ -1,3 +1,108 @@
+//! [Dhall][dhall] is a programmable configuration language that provides a non-repetitive
+//! alternative to JSON and YAML.
+//!
+//! 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].
+//!
+//! This crate provides support for consuming dhall files the same way you would consume JSON or
+//! 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 for now.
+//!
+//! # Examples
+//!
+//! ### Custom datatype
+//!
+//! If you have a custom datatype for which you derived [serde::Deserialize], chances are
+//! you will be able to derive [StaticType][de::StaticType] for it as well.
+//! This gives you access to a dhall representation of your datatype that can be outputted
+//! to users, and allows easy type-safe deserializing.
+//!
+//! ```edition2018
+//! use serde::Deserialize;
+//! use serde_dhall::de::StaticType;
+//!
+//! #[derive(Debug, Deserialize, StaticType)]
+//! struct Point {
+//! x: u64,
+//! y: u64,
+//! }
+//!
+//! fn main() {
+//! // Some dhall data
+//! let data = "{ x = 1, y = 1 + 1 }";
+//!
+//! // Convert the dhall string to a Point.
+//! let point: Point =
+//! serde_dhall::de::from_str_auto_type(&data)
+//! .expect("An error ocurred !");
+//!
+//! // Prints "point = Point { x: 1, y: 2 }"
+//! println!("point = {:?}", point);
+//! }
+//! ```
+//!
+//! ### Loosely typed
+//!
+//! If you used to consume JSON or YAML in a loosely typed way, you can continue to do so
+//! with dhall. You only need to replace [serde_json::from_str] or [serde_yaml::from_str]
+//! with [serde_dhall::de::from_str][de::from_str].
+//! More generally, if the [StaticType][de::StaticType] derive doesn't suit your
+//! needs, you can still deserialize any valid dhall file that serde can handle.
+//!
+//! [serde_json::from_str]: https://docs.serde.rs/serde_json/de/fn.from_str.html
+//! [serde_yaml::from_str]: https://docs.serde.rs/serde_yaml/fn.from_str.html
+//!
+//! ```edition2018
+//! use std::collections::BTreeMap;
+//!
+//! let mut map = BTreeMap::new();
+//! map.insert("x".to_string(), 1);
+//! map.insert("y".to_string(), 2);
+//!
+//! // Some dhall data
+//! let data = "{ x = 1, y = 1 + 1 } : { x: Natural, y: Natural }";
+//!
+//! // Deserialize it to a Rust type.
+//! let deserialized_map: BTreeMap<String, usize> =
+//! serde_dhall::de::from_str(&data, None)
+//! .expect("Failed reading the data !");
+//! assert_eq!(map, deserialized_map);
+//! ```
+//!
+//! You can of course specify a dhall type that the input should match.
+//!
+//! ```edition2018
+//! use std::collections::BTreeMap;
+//!
+//! let mut map = BTreeMap::new();
+//! map.insert("x".to_string(), 1);
+//! map.insert("y".to_string(), 2);
+//!
+//! // Some dhall data
+//! let point_data = "{ x = 1, y = 1 + 1 }";
+//! let point_type_data = "{ x: Natural, y: Natural }";
+//!
+//! // Construct a type
+//! let point_type =
+//! serde_dhall::de::from_str(point_type_data, None)
+//! .expect("Could not parse the Point type");
+//!
+//! // Deserialize it to a Rust type.
+//! let deserialized_map: BTreeMap<String, usize> =
+//! serde_dhall::de::from_str(&point_data, Some(&point_type))
+//! .expect("Failed reading the data !");
+//! assert_eq!(map, deserialized_map);
+//! ```
+//!
+//! [dhall]: https://dhall-lang.org/
+//! [serde]: https://docs.serde.rs/serde/
+//! [serde::Deserialize]: https://docs.serde.rs/serde/trait.Deserialize.html
+
mod serde;
pub(crate) mod static_type;
@@ -5,8 +110,8 @@ pub use value::Value;
mod value {
use super::Type;
- use crate::error::Result;
- use crate::phase::{NormalizedSubExpr, Parsed, Typed};
+ use dhall::error::Result;
+ use dhall::phase::{NormalizedSubExpr, Parsed, Typed};
// A Dhall value
pub struct Value(Typed);
@@ -34,10 +139,10 @@ pub use typ::Type;
mod typ {
use dhall_syntax::Builtin;
- use crate::core::thunk::{Thunk, TypeThunk};
- use crate::core::value::Value;
- use crate::error::Result;
- use crate::phase::{NormalizedSubExpr, Typed};
+ use dhall::core::thunk::{Thunk, TypeThunk};
+ use dhall::core::value::Value;
+ use dhall::error::Result;
+ use dhall::phase::{NormalizedSubExpr, Typed};
/// A Dhall expression representing a type.
///
@@ -95,13 +200,13 @@ mod typ {
pub(crate) fn to_expr(&self) -> NormalizedSubExpr {
self.0.to_expr()
}
- pub(crate) fn to_type(&self) -> crate::phase::Type {
+ pub(crate) fn to_type(&self) -> dhall::phase::Type {
self.0.to_type()
}
}
impl crate::de::Deserialize for Type {
- fn from_dhall(v: &crate::api::Value) -> Result<Self> {
+ fn from_dhall(v: &super::Value) -> Result<Self> {
Ok(Type(v.to_typed()))
}
}
@@ -111,7 +216,7 @@ mod typ {
pub mod de {
pub use super::static_type::StaticType;
pub use super::{Type, Value};
- use crate::error::Result;
+ use dhall::error::Result;
#[doc(hidden)]
pub use dhall_proc_macros::StaticType;
diff --git a/dhall/src/api/serde.rs b/serde_dhall/src/serde.rs
index e1c8eef..3dad2d8 100644
--- a/dhall/src/api/serde.rs
+++ b/serde_dhall/src/serde.rs
@@ -1,5 +1,5 @@
-use crate::api::de::{Deserialize, Value};
-use crate::error::{Error, Result};
+use crate::de::{Deserialize, Value};
+use dhall::error::{Error, Result};
use dhall_syntax::{ExprF, SubExpr, X};
use std::borrow::Cow;
@@ -14,14 +14,14 @@ where
struct Deserializer<'a>(Cow<'a, SubExpr<X, X>>);
-impl serde::de::Error for Error {
- fn custom<T>(msg: T) -> Self
- where
- T: std::fmt::Display,
- {
- Error::Deserialize(msg.to_string())
- }
-}
+// impl serde::de::Error for Error {
+// fn custom<T>(msg: T) -> Self
+// where
+// T: std::fmt::Display,
+// {
+// Error::Deserialize(msg.to_string())
+// }
+// }
impl<'de: 'a, 'a> serde::de::IntoDeserializer<'de, Error> for Deserializer<'a> {
type Deserializer = Deserializer<'a>;
diff --git a/dhall/src/api/static_type.rs b/serde_dhall/src/static_type.rs
index 906bcef..13d5d70 100644
--- a/dhall/src/api/static_type.rs
+++ b/serde_dhall/src/static_type.rs
@@ -1,6 +1,6 @@
use dhall_syntax::{Builtin, Integer, Natural};
-use crate::api::Type;
+use crate::Type;
/// A Rust type that can be represented as a Dhall type.
///