menv 0.2.8

Pulling in arguments from environment variables
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
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166

//! # `menv`
//! This crate provides [a macro](require_envs) for asserting the presence of a list of environment
//! variables and accessing them as types which implement [`FromStr`](std::str::FromStr).

use std::ops::{Deref, DerefMut};
use std::str::FromStr;
/// Generate the following:
/// - A function which asserts the presence and well-formedness of a list of env vars
/// - A function which returns a `bool` representing whether any of the required vars are set
/// - A function which returns a `String` representing the collected help messages for the list of vars
/// - A list of functions, one for each environment variable required, which parse and return the associated env var
///
/// # Example
/// Here we fill an `env` module with required environment variables,
/// print help and exit if none of them are set, runs the asserts for them
/// if some are set, and proceeds.
///
/// Other parts of this program are now free, since the asserts were run at the start of main,
/// to access `env::server_port()` and `env::db_path()` as if they are infallible.
///
/// The getter function name can be suffixed with `?` to make an env var optional. In this example,
/// `plugin_dir`'s return type is `Option<String>`.
///
/// The getter function name can also, instead, be suffixed with `~` to make an env var use
/// the [`Default`] value of its type when unset. In this example, [`Flag`]'s default value is `false`.
/// ```
/// mod env {
///     use menv::require_envs;
///     require_envs! {
///         (assert_env_vars, any_set, gen_help);
///
///         server_port, "FERRISCRAFT_USERS_PORT", u16,
///         "FERRISCRAFT_USERS_PORT should be set to the desired server port";
///
///         db_path, "FERRISCRAFT_USERS_DB", String,
///         "FERRISCRAFT_USERS_DB should be set to the path to the users database";
///
///         plugin_dir?, "XLANG_PLUGIN_DIR", String,
///         "XLANG_PLUGIN_DIR, if set, overrides the directory that lccc looks for xlang plugins";
///
///         do_overflow_checks~, "DO_OVERFLOW_CHECKS", Flag,
///         "DO_OVERFLOW_CHECKS, if set, makes all additional overflow checks run";
///     }
/// }
/// fn main() {
///    if env::any_set() {
///         env::assert_env_vars();
///     } else {
///         println!("# Environment Variables Help\n{}", env::gen_help());
///         return
///     }
/// }
/// ```
#[macro_export]
macro_rules! require_envs {
    // We set a default visibility which is different from Rust's default to private.
    (@func $fname:ident ?, $ename:literal, $ty:ty, $etext:literal) => {
        $crate::require_envs! {@func pub $fname ?, $ename, $ty, $etext}
    };
    (@func $vis:vis $fname:ident ?, $ename:literal, $ty:ty, $etext:literal) => {
        #[doc = $crate::__private::trimmed_help!($etext)]
        $vis fn $fname() -> $crate::__private::Option<$ty> {
            let x = $crate::__private::env::var($ename).ok();
            x.and_then(|x| {
                $crate::__private::Option::Some($crate::__private::FromStr::from_str(&x).expect($etext))
            })
        }
    };
    (@func $fname:ident ~, $ename:literal, $ty:ty, $etext:literal) => {
        $crate::require_envs! {@func pub $fname ~, $ename, $ty, $etext}
    };
    (@func $vis:vis $fname:ident ~, $ename:literal, $ty:ty, $etext:literal) => {
        #[doc = $crate::__private::trimmed_help!($etext)]
        $vis fn $fname() -> $ty {
            let x = $crate::__private::env::var($ename).ok();
            let x = x.and_then(|x| {
                $crate::__private::Option::Some($crate::__private::FromStr::from_str(&x).expect($etext))
            });
            x.unwrap_or_default()
        }
    };
    (@func $fname:ident, $ename:literal, $ty:ty, $etext:literal) => {
        $crate::require_envs! {@func pub $fname, $ename, $ty, $etext}
    };
    (@func $vis:vis $fname:ident, $ename:literal, $ty:ty, $etext:literal) => {
        #[doc = $crate::__private::trimmed_help!($etext)]
        $vis fn $fname() -> $ty {
            $crate::__private::FromStr::from_str(&$crate::__private::env::var($ename).expect($etext)).expect($etext)
        }
    };
    // We do not assert the existence of optional variables.
    (@assert $vis:vis $fname:ident ?, $ename:literal, $ty:ty, $etext:literal) => {};
    (@assert $vis:vis $fname:ident ~, $ename:literal, $ty:ty, $etext:literal) => {};
    (@assert $vis:vis $fname:ident, $ename:literal, $ty:ty, $etext:literal) => {
        let _ = $fname();
    };
    (@get_res $vis:vis $fname:ident $(?)? $(~)?, $ename:literal, $ty:ty, $etext:literal) => {
        $crate::__private::env::var($ename)
    };
    (@etext $vis:vis $fname:ident $(?)? $(~)?, $ename:literal, $ty:ty, $etext:literal) => {
        $etext
    };
    (($assert_name:ident, $any_set_name:ident, $help_name:ident); $($stream:tt)*) => {
        // Note: While I now use a proc macro for dividing the input stream into declarations,
        // the below comments still accurately describe what that proc macro generates invocations of.
        pub fn $assert_name () {
            $crate::__private::assert_var_body! {$crate $($stream)*}
            // $(
            //     $crate::require_envs! {@assert $a $b $c $d $e $f $g $($h)?}
            // )*
        }
        pub fn $any_set_name() -> bool {
            $crate::__private::any_set_body! {$crate $($stream)*}.iter().any(|x| x.is_ok())
            // [$($crate::require_envs! {@get_res $a $b $c $d $e $f $g $($h)?}),*].iter().any(|x| x.is_ok())
        }
        pub fn $help_name() -> $crate::__private::String {
            $crate::__private::help_body!{$crate $($stream)*}.iter().fold($crate::__private::String::new(), |a, x| {
                a + x + "\n"
            })
            // $crate::__private::String::new() $(+ $crate::require_envs! {@etext $a $b $c $d $e $f $g $($h)?} + "\n")*
        }
        $crate::__private::getters! {$crate $($stream)*}
        // $(
        //     $crate::require_envs! {@func $a $b $c $d $e $f $g $($h)?}
        // )*
        $crate::__private::errors! {$crate $($stream)*}
    }
}

/// Use this type instead of a [`bool`] if you want a var to
/// evaluate to true if set to any value at all.
///
/// This is best used with the `~` getter modifier,
/// which causes an unset var to use its type's [`Default`] implementation.
#[derive(Default, Copy, Clone, Hash, Debug)]
pub struct Flag {
    pub val: bool,
}
impl FromStr for Flag {
    type Err = ::core::convert::Infallible;
    fn from_str(_: &str) -> Result<Self, Self::Err> {
        Ok(Self { val: true })
    }
}
impl Deref for Flag {
    type Target = bool;
    fn deref(&self) -> &Self::Target {
        &self.val
    }
}
impl DerefMut for Flag {
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut self.val
    }
}

/// This module holds private re-exports which are used by [`require_envs`]
/// to ensure it always refers to the right external items.
#[doc(hidden)]
pub mod __private {
    pub use ::menv_proc_macro::{any_set_body, assert_var_body, errors, getters, help_body, trimmed_help};
    pub use ::std::env;
    pub use ::std::option::Option;
    pub use ::std::str::FromStr;
    pub use ::std::string::String;
}