Derive Macro FromEnv

#[derive(FromEnv)]
{
    // Attributes available to this derive:
    #[from_env]
}

The derive(FromEnv) macro.

This macro generates a FromEnv implementation for the struct it is applied to. It will generate a from_env function that loads the struct from the environment. It will also generate an inventory function that returns a list of all environment variables that are required to load the struct.

The macro also generates a __EnvError type that captures errors that can occur when trying to create an instance of the struct from environment variables. This error type is used in the FromEnv trait implementation.

Conditions of use

There are a few usage requirements:

• Struct props MUST implement either FromEnvVar or FromEnv.
• If the prop implements FromEnvVar, it must be tagged as follows:
  • var = "ENV_VAR_NAME": The environment variable name to load.
  • desc = "description": A description of the environment variable.
• If the prop is an Option<T>, it must be tagged as follows:
  • optional
• If the prop’s associated error type is Infallible, it must be tagged as follows:
  • infallible
• If used within this crate (init4_bin_base), the entire struct must be tagged with #[from_env(crate)] (see the SlotCalculator for an example).

Examples

The following example shows how to use the macro:

use init4_bin_base::utils::from_env::{FromEnv};

#[derive(Debug, FromEnv)]
pub struct MyCfg {
    #[from_env(var = "COOL_DUDE", desc = "Some u8 we like :o)")]
    pub my_cool_u8: u8,

    #[from_env(var = "CHUCK", desc = "Charles is a u64")]
    pub charles: u64,

    #[from_env(
        var = "PERFECT",
        desc = "A bold and neat string",
        infallible,
    )]
    pub strings_cannot_fail: String,

    #[from_env(
        var = "MAYBE_NOT_NEEDED",
        desc = "This is an optional string",
        optional,
        infallible,
    )]
    maybe_not_needed: Option<String>,
}

// The `FromEnv` trait is implemented for the struct, and the struct can
// be loaded from the environment.
if let Err(missing) = MyCfg::check_inventory() {
    println!("Missing environment variables:");
    for var in missing {
        println!("{}: {}", var.var, var.description);
    }
}

This will generate a FromEnv implementation for the struct, and a MyCfgEnvError type that is used to represent errors that can occur when loading from the environment. The error generated will look like this:

pub enum MyCfgEnvError {
    MyCoolU8(<u8 as FromEnvVar>::Error),
    Charles(<u64 as FromEnvVar>::Error),
    // No variants for infallible errors.
}

This macro generates an implementation of the FromEnv trait for a struct. See the documenetation in init4_bin_base for more details.