foundation_core 0.0.6

Central crate for all foundation crates for the ewe-platform project
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

use serde::de::DeserializeOwned;
use serde::Serialize;

use super::ValueError;

///  Extension trait that allows us define a conversion of a JSON value to
/// more native rust types.
///
/// It's implemented for bool, u32/64, f64, i32/64 and str
pub trait AsType<'a, T>: Sized {
    /// # Errors
    /// Returns an error if the value cannot be converted to the target type.
    fn from_value(value: &'a T) -> ValueResult<Self, ValueError>;
}

pub type ValueResult<T, E> = core::result::Result<T, E>;

/// `PointerValueExt` defines method to pull value from an underlying value.
pub trait PointerValueExt {
    type Item;
    type Error;

    /// Returns a reference to the underlying type identified by `PointerValueExt::Item`.
    ///
    /// # Errors
    /// Returns an error if the path is invalid or the value cannot be retrieved.
    fn get_path(&self, name_or_pointer: &str) -> ValueResult<&Self::Item, Self::Error>;

    /// Returns a reference to the underlying type identified by `PointerValueExt::Item`.
    ///
    /// # Errors
    /// Returns an error if the path is invalid or the value cannot be taken.
    fn take_path(&mut self, name_or_pointer: &str) -> ValueResult<Self::Item, Self::Error>;
}

/// `DynamicValueExt` defines a core expectation for dynamically generated
/// value containers such as those in json, toml or yaml.
/// This trait is focused on making interactions directly with these types
/// easily and affordable without specifically dragging then need to serialize
/// into specific type. This brings the joy of Data Oriented programming
/// to rust.
pub trait DynamicValueExt {
    type Item;
    type Error;

    fn d_new() -> Self::Item;

    /// Returns an owned type `T` for a given name or pointer path.
    /// - `name_or_pointer`: Can be a direct name or a pointer path (path starting with `/`),
    ///
    /// # Errors
    /// Returns an error if the path is invalid or deserialization fails.
    fn d_get<T: DeserializeOwned>(&self, name_or_pointer: &str) -> ValueResult<T, Self::Error>;

    /// Returns an reference of type `T` (or value for copy type) for a given name or pointer path.
    /// - `name_or_pointer`: Can be a direct name or a pointer path (path starting with `/`),
    ///
    /// # Errors
    /// Returns an error if the path is invalid or type conversion fails.
    fn d_get_as<'a, V: AsType<'a, Self::Item>>(
        &'a self,
        name_or_pointer: &str,
    ) -> ValueResult<V, Self::Error>;

    /// Returns an owned type `T` for a given name or pointer path replacing with `Null`.
    /// - `name_or_pointer`: Can be a direct name or a pointer path (path starting with `/`),
    ///
    /// # Errors
    /// Returns an error if the path is invalid or deserialization fails.
    fn d_take<T: DeserializeOwned>(&mut self, name_or_pointer: &str)
        -> ValueResult<T, Self::Error>;

    /// Inserts a new value of type `T` at the specified name or pointer path.
    /// It creates a missing `Value::Object` entries as needed.
    ///
    /// # Errors
    /// Returns an error if the path is invalid or serialization fails.
    fn d_insert<T: Serialize>(
        &mut self,
        name_or_pointer: &str,
        value: T,
    ) -> ValueResult<(), Self::Error>;

    /// Returns a pretty-printed string representation of the JSON value.
    ///
    /// # Errors
    /// Returns an error if pretty-printing fails.
    fn d_pretty(&self) -> ValueResult<String, Self::Error>;
}