Crate envmnt

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/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 = |value: String| {
        let mut buffer = String::from("VALUE-");
        buffer.push_str(&value);
        buffer
    };

    envmnt::evaluate_and_set_all(&env, eval_env);

    let value = envmnt::get_or_panic("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 = |value: String| {
        let mut buffer = String::from("PREFIX-");
        buffer.push_str(&value);
        buffer
    };

    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

types

types

Functions

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_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_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 Definitions

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