Crate envmnt

Expand description

§envmnt

Environment variables utility functions.

This library has many helper functions to access/modify/check environment variables.

§Examples

§Get/Set/Remove environment variables

use envmnt::{ExpandOptions, ExpansionType};

fn main() {
    if !envmnt::exists("MY_ENV_VAR") {
        envmnt::set("MY_ENV_VAR", "SOME VALUE");
    }

    let mut value = envmnt::get_or("MY_ENV_VAR", "DEFAULT_VALUE");
    println!("Env Value: {}", &value);

    value = envmnt::get_or_panic("MY_ENV_VAR");
    println!("Env Value: {}", &value);

    let pre_value = envmnt::get_set("MY_ENV_VAR", "SOME NEW VALUE");

    let value = envmnt::get_or("MY_ENV_VAR", "DEFAULT_VALUE");
    println!("New Env Value: {}", &value);
    println!("Previous Env Value: {:?}", &pre_value);

    let var_was_set = envmnt::set_optional("MY_ENV_VAR", &Some("OPTIONAL VALUE"));
    println!("Env Was Modified: {}", var_was_set);

    let all_vars = envmnt::vars(); // returned as Vec<(String, String)>

    for (key, value) in all_vars {
        println!("{}: {}", key, value);
    }

    envmnt::set("MY_ENV_VAR2", "SOME VALUE2");

    let value = envmnt::get_any(&vec!["MY_ENV_VAR1", "MY_ENV_VAR2"], "default");
    println!("MY_ENV_VAR1 exists: {}", envmnt::exists("MY_ENV_VAR1"));
    println!("MY_ENV_VAR2 exists: {}", envmnt::exists("MY_ENV_VAR2"));
    println!("Found value: {}", value);

    let mut options = ExpandOptions::new();
    options.expansion_type = Some(ExpansionType::Unix);
    let mut value = envmnt::expand("Env: MY_ENV value is: ${MY_ENV}", Some(options));
    println!("Expanded: {}", &value);
    options.expansion_type = Some(ExpansionType::UnixBracketsWithDefaults);
    value = envmnt::expand(
        "Env: MY_ENV_NOT_FOUND value is: ${MY_ENV_NOT_FOUND:default value}",
        Some(options),
    );
    println!("Expanded: {}", &value);
}

§Get/Set boolean environment variables and other comparisons

fn main() {
    envmnt::set_bool("FLAG_VAR", true);
    let mut flag_value = envmnt::is_or("FLAG_VAR", false);
    println!("Bool Flag: {}", &flag_value);

    flag_value = envmnt::is("FLAG_VAR");
    assert!(flag_value);

    envmnt::set_bool("FLAG_VAR", true);
    assert!(envmnt::is_equal("FLAG_VAR", "true"));

    envmnt::set("MY_ENV_VAR", "SOME VALUE");
    let same = envmnt::is_equal("MY_ENV_VAR", "SOME VALUE");
    println!("Value Is Same: {}", &same);
    let mut contains = envmnt::contains("MY_ENV_VAR", "_ENV_");
    println!("Value Contained: {}", &contains);
    contains = envmnt::contains_ignore_case("MY_ENV_VAR", "_env_");
    println!("Value Contained (case insensitive): {}", &contains);
}

§Get/Set numeric environment variables

fn main() {
    // all numeric data types: u8/i8/u16/i16/u32/i32/u64/i64/u128/i128/f32/f64/isize/usize
    // are supported by specific set/get functions.
    envmnt::set_u8("U8_TEST_ENV", 50);
    let mut value_u8 = envmnt::get_u8("U8_TEST_ENV", 5);
    println!("u8 value: {}", value_u8);

    envmnt::set_isize("ISIZE_TEST_ENV", -50);
    let mut value_isize = envmnt::get_isize("ISIZE_TEST_ENV", 5);
    println!("isize value: {}", value_isize);

    // increment/decrement values
    value_isize = envmnt::increment("U8_TEST_ENV");
    assert_eq!(value_isize, 51);
    value_u8 = envmnt::get_u8("U8_TEST_ENV", 5);
    assert_eq!(value_u8, 51);
    value_isize = envmnt::decrement("U8_TEST_ENV");
    assert_eq!(value_isize, 50);
    value_u8 = envmnt::get_u8("U8_TEST_ENV", 5);
    assert_eq!(value_u8, 50);
}

§Get and parse any type T that implements FromStr

fn main() {
    envmnt::set("ENV_VAR", "123");

    let value: i16 = envmnt::get_parse("ENV_VAR").unwrap();
    assert_eq!(value, 123);

    let value: String = envmnt::get_parse("ENV_VAR").unwrap();
    assert_eq!(value, "123");

    let value: i32 = envmnt::get_parse_or("ENV_VAR", 123).unwrap();
    assert_eq!(value, 123);

    let value: i64 = envmnt::get_parse_or("ENV_UNDEFINED", 321).unwrap();
    assert_eq!(value, 321);
}

§Get/Set list environment variables

fn main() {
    envmnt::set_list(
        "LIST_TEST_ENV",
        &vec!["1".to_string(), "2".to_string(), "3".to_string()],
    );

    let mut values = envmnt::get_list("LIST_TEST_ENV").unwrap();
    println!("List Values: {:?}", values);

    let mut same = envmnt::is_equal("LIST_TEST_ENV", "1;2;3");
    println!("Same: {}", same);

    let mut options = envmnt::ListOptions::new();
    options.separator = Some(",".to_string());
    envmnt::set_list_with_options(
        "LIST_TEST_ENV",
        &vec!["1".to_string(), "2".to_string(), "3".to_string()],
        &options,
    );

    values = envmnt::get_list_with_options("LIST_TEST_ENV", &options).unwrap();
    println!("List Values: {:?}", values);

    same = envmnt::is_equal("LIST_TEST_ENV", "1,2,3");
    println!("Same: {}", same);
}

§Bulk Operations

use indexmap::IndexMap;

fn main() {
    let mut env: IndexMap<String, String> = IndexMap::new();
    env.insert("ENV_VAR1".to_string(), "MY VALUE".to_string());
    env.insert("ENV_VAR2".to_string(), "MY VALUE2".to_string());

    envmnt::set_all(&env);

    let value = envmnt::get_or_panic("ENV_VAR1");
    println!("Value Is: {}", &value);

    let mut found = envmnt::is_any_exists(&vec!["ENV_VAR1", "ENV_VAR2"]);

    println!("Any Found: {}", &found);

    found = envmnt::is_all_exists(&vec!["ENV_VAR1", "ENV_VAR2"]);

    println!("All Found: {}", &found);

    envmnt::remove_all(&vec!["ENV_VAR1", "ENV_VAR2"]);

    found = envmnt::is_any_exists(&vec!["ENV_VAR1", "ENV_VAR2"]);

    println!("Any Found: {}", &found);

    env = IndexMap::new();
    env.insert("ENV_VAR1".to_string(), "MY VALUE".to_string());
    env.insert("ENV_VAR2".to_string(), "MY VALUE2".to_string());

    let eval_env = |key: String, value: String| {
        let mut updated_key = String::from("KEY-");
        updated_key.push_str(&key);
        let mut updated_value = String::from("VALUE-");
        updated_value.push_str(&value);
        Some((updated_key, updated_value))
    };

    envmnt::evaluate_and_set_all(&env, eval_env);

    let value = envmnt::get_or_panic("KEY-ENV_VAR1");
    println!("Value Is: {}", &value);
}

§File Operations

fn main() {
    let mut output = envmnt::load_file("./src/test/var.env");
    assert!(output.is_ok());

    let eval_env = |key: String, value: String| {
        let mut updated_value = String::from("PREFIX-");
        updated_value.push_str(&value);
        Some((key, updated_value))
    };

    output = envmnt::evaluate_and_load_file("./src/test/var.env", eval_env);
    assert!(output.is_ok());
}

§Installation

In order to use this library, just add it as a dependency:

[dependencies]
envmnt = "*"

§Contributing

See contributing guide

§License

Developed by Sagie Gur-Ari and licensed under the Apache 2 open source license.

Modules§

errors: errors
types: types

Functions§

checkpoint: Create a new checkpoint, for the current environment of the process, at a later date a checkpoint can be restored using [Checkpoint::restore], which will rollback the environment to all values present at the time this function was called.
contains: Returns true if the provided environment variable is defined and contains the provided value.
contains_ignore_case: Returns true if the provided environment variable is defined and contains the provided value regardless of the case.
decrement: Decrements and returns the new value stored by the given environment variable key. In case the variable does not exist, it will decrement to -1. The updated value will be returned.
evaluate_and_load_file: Parses the provided env file and loads all environment variables.
evaluate_and_set_all: Sets all the provided env key/value pairs.
exists: Returns true environment variable is defined.
expand: Expands the provided string value by replacing the environment variables defined in it. The syntax of the environment variables is based on the type requested.
get_any: Returns the first environment variable found.
get_f32: Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.
get_f64: Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.
get_i8: Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.
get_i16: Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.
get_i32: Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.
get_i64: Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.
get_i128: Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.
get_isize: Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.
get_list: Returns the requested environment variable as a string vector.
get_list_with_options: Returns the requested environment variable as a string vector.
get_or: Returns the environment variable value or if is not defined, the default value will be returned.
get_or_panic: Returns the environment variable value. If the variable is not defined, this function will panic.
get_parse: Returns the parsed environment variable value.
get_parse_or: Returns the parsed environment variable value or if is not defined, the default value will be returned.
get_remove: Removes the provided environment variable and returns its previous value (if any).
get_set: Sets the environment variable value and returns the previous value.
get_u8: Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.
get_u16: Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.
get_u32: Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.
get_u64: Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.
get_u128: Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.
get_usize: Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.
increment: Increments and returns the new value stored by the given environment variable key. In case the variable does not exist, it will increment to 1. The updated value will be returned.
is: Returns false if environment variable value if falsy. The value is falsy if it is one of the following:
is_all_exists: Returns true if all of environment variables are defined.
is_any_exists: Returns true if any of environment variables is defined.
is_equal: Returns true if the provided environment variable is defined and equals the provided value.
is_or: Returns false if environment variable value if falsy.
Any other value is returned as true.
The value is falsy if it is one of the following:
load_file: Parses the provided env file and loads all environment variables.
parse_env_file_content: Parses the provided content as a map of key/value. The content should be in the form of an env file format.
parse_file: Parses the provided env file and returns its content as a map of key/value.
remove: Removes the provided environment variable.
remove_all: Removes all provided environment variables.
set: Sets the environment variable value.
set_all: Sets all the provided env key/value pairs.
set_bool: Sets the environment variable with a true/false value as string.
set_f32: Sets the environment variable value.
set_f64: Sets the environment variable value.
set_i8: Sets the environment variable value.
set_i16: Sets the environment variable value.
set_i32: Sets the environment variable value.
set_i64: Sets the environment variable value.
set_i128: Sets the environment variable value.
set_isize: Sets the environment variable value.
set_list: Sets the provided string vector as an environment variable.
set_list_with_options: Sets the provided string vector as an environment variable.
set_optional: Sets the environment variable if the provided option contains a value.
set_or_remove: Sets the environment variable if the provided option contains a value. If no value was provided, the environment variable will be removed.
set_u8: Sets the environment variable value.
set_u16: Sets the environment variable value.
set_u32: Sets the environment variable value.
set_u64: Sets the environment variable value.
set_u128: Sets the environment variable value.
set_usize: Sets the environment variable value.
vars: Returns all environment variables as a vector.

Type Aliases§

ExpandOptions: Expand options
ExpansionType: Expansion Type - unix/windows style
ListOptions: Get/Set list options

Crate envmntCopy item path