Struct serde_dhall::Deserializer

pub struct Deserializer<'a, A> { /* private fields */ }

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<T> where T is a deserializable type of your choice.

Examples

Reading from a file:

use serde_dhall::from_file;

let data = from_file("foo.dhall").parse::<u64>()?;

Reading from a file and checking the value against a provided type:

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::<HashMap<String, u64>>()?;

Implementations

impl<'a> Deserializer<'a, NoAnnot>

pub fn type_annotation<'ty>(
    self,
    ty: &'ty SimpleType
) -> Deserializer<'a, ManualAnnot<'ty>>

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

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::<SimpleType>()?;

// Parse some Dhall data.
let data = "{ x = 1, y = 1 + 1 }";
let point = from_str(data)
    .type_annotation(&ty)
    .parse::<HashMap<String, u64>>()?;
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::<HashMap<String, u64>>()
        .is_err()
);

pub fn static_type_annotation(self) -> Deserializer<'a, StaticAnnot>

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

use serde::Deserialize;
use serde_dhall::StaticType;

#[derive(Deserialize, StaticType)]
struct Point {
    x: u64,
    y: Option<u64>,
}

// 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::<Point>()?;
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::<Point>()
        .is_err()
);

impl<'a, A> Deserializer<'a, A>

pub fn imports(self, imports: bool) -> Self

Sets whether to enable imports.

By default, imports are enabled.

Example

use serde::Deserialize;
use serde_dhall::SimpleType;

let data = "12 + ./other_file.dhall : Natural";
assert!(
    serde_dhall::from_str(data)
        .imports(false)
        .parse::<u64>()
        .is_err()
);

pub fn with_builtin_types(
    self,
    tys: impl IntoIterator<Item = (String, SimpleType)>
) -> Self

Makes a set of types available to the parsed dhall code. This is similar to how builtins like Natural work: they are provided by dhall and accessible in any file.

This is especially useful when exposing rust types exposing the rust types to dhall, since this avoids having to define them in both languages and keep both definitions in sync.

Warning: the new builtins will only be accessible to the current file. If this file has imports, the imported values will not have access to the builtins.

See also [with_builtin_type()]. [with_builtin_type()]: Deserializer::with_builtin_type()

Example

use serde::Deserialize;
use serde_dhall::StaticType;
use std::collections::HashMap;

#[derive(Deserialize, StaticType, Debug, PartialEq)]
enum Newtype {
  Foo,
  Bar(u64)
}

let mut builtins = HashMap::new();
builtins.insert("Newtype".to_string(), Newtype::static_type());

let data = "Newtype.Bar 0";

let deserialized = serde_dhall::from_str(data)
  .with_builtin_types(builtins)
  .parse::<Newtype>()
  .unwrap();

assert_eq!(deserialized, Newtype::Bar(0));

pub fn with_builtin_type(self, name: String, ty: SimpleType) -> Self

Makes a type available to the parsed dhall code. This is similar to how builtins like Natural work: they are provided by dhall and accessible in any file.

This is especially useful when exposing rust types exposing the rust types to dhall, since this avoids having to define them in both languages and keep both definitions in sync.

Warning: the new builtins will only be accessible to the current file. If this file has imports, the imported values will not have access to the builtins.

See also [with_builtin_types()]. [with_builtin_types()]: Deserializer::with_builtin_types()

Example

use serde::Deserialize;
use serde_dhall::StaticType;
use std::collections::HashMap;

#[derive(Deserialize, StaticType, Debug, PartialEq)]
enum Newtype {
  Foo,
  Bar(u64)
}

let data = "Newtype.Bar 0";

let deserialized = serde_dhall::from_str(data)
  .with_builtin_type("Newtype".to_string(), Newtype::static_type())
  .parse::<Newtype>()
  .unwrap();

assert_eq!(deserialized, Newtype::Bar(0));

pub fn parse<T>(&self) -> Result<T>where
    A: TypeAnnot,
    T: FromDhall + HasAnnot<A>,

Parses the chosen dhall value with the options provided.

If you enabled static annotations, T is required to implement StaticType.

Example

let data = serde_dhall::from_str("6 * 7").parse::<u64>()?;
assert_eq!(data, 42);

Trait Implementations

impl<'a, A: Clone> Clone for Deserializer<'a, A>

fn clone(&self) -> Deserializer<'a, A>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a, A: Debug> Debug for Deserializer<'a, A>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.