rpkl 0.8.0

Bindings and codegen for Apple's Pkl configuration language
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
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

pub mod api;
#[cfg(feature = "codegen")]
pub mod codegen;
mod context;
mod decoder;
pub mod error;
mod internal;
pub mod pkl;
mod utils;
pub mod value;

pub use error::{Error, Result};

pub use api::evaluator::{EvaluatorOptions, HttpOptions, HttpProxy};

pub use value::PklValue as Value;

use pkl::Deserializer;
use pkl::IntoPklMap;

#[cfg(feature = "build-script")]
pub use codegen::build_script;

/// Evaluates a `.pkl` file and deserializes it as `T`. If you need to pass options to the evaluator, such as properties, use [`from_config_with_options`].
///
/// `path`: The path to the `.pkl` file
///
/// # Example
///
/// ```ignore
/// ip = "127.0.0.1"
/// database {
///     username = "root"
///     password = "password"
/// }
/// ```
/// -------------
/// ```no_run
///
/// use serde::Deserialize;
///
/// #[derive(Deserialize)]
/// struct Config {
///     ip: String,
///     database: Database,
/// }
///
/// #[derive(Deserialize)]
/// struct Database {
///     username: String,
///     password: String,
/// }
///
/// # fn main() -> Result<(), rpkl::Error> {
/// let config: Config = rpkl::from_config("config.pkl")?;
/// #    Ok(())
/// # }
/// ```
///
/// # Errors
/// - `DeserializeError`: If the deserialization fails.
/// - `PklError`: If the PKL module fails to serialize.
/// - If the evaluator fails to evaluate the module.
pub fn from_config<T>(path: impl AsRef<std::path::Path>) -> Result<T>
where
    T: Sized + for<'de> serde::Deserialize<'de>,
{
    from_config_with_options(path, EvaluatorOptions::default())
}

/// Allows for passing options to the evaluator, such as properties (e.g. `read("prop:username")`). See [`EvaluatorOptions`] for more information.
///
/// # Example
///
/// ```ignore
/// ip = "127.0.0.1"
/// credentials {
///     username = read("prop:username")
///     password = read("prop:password")
/// }
/// ```
/// -------------
/// ```no_run
///
/// use serde::Deserialize;
/// use rpkl::api::evaluator::EvaluatorOptions;
///
/// #[derive(Deserialize)]
/// struct Config {
///     ip: String,
///     database: Credentials,
/// }
///
/// #[derive(Deserialize)]
/// struct Credentials {
///     username: String,
///     password: String,
/// }
///
/// # fn main() -> Result<(), rpkl::Error> {
/// let options = EvaluatorOptions::default()
///     .properties([("username", "root"), ("password", "password123")]);
/// let config: Config = rpkl::from_config_with_options("config.pkl", options)?;
/// #    Ok(())
/// # }
/// ```
/// # Errors
/// - `DeserializeError`: If the deserialization fails.
/// - `PklError`: If the PKL module fails to serialize.
/// - If the evaluator fails to evaluate the module.
pub fn from_config_with_options<T>(
    path: impl AsRef<std::path::Path>,
    options: EvaluatorOptions,
) -> Result<T>
where
    T: Sized + for<'de> serde::Deserialize<'de>,
{
    let mut evaluator = api::Evaluator::new_from_options(options)?;
    let pkl_mod = evaluator.evaluate_module(path.as_ref())?;

    let pkld = pkl_mod.into_pkl_map();

    utils::macros::_trace!("serialized pkl data {:?}", pkld);

    T::deserialize(&mut Deserializer::from_pkl_map(&pkld))
        .map_err(|e| Error::DeserializeError(format!("{e}")))
}