Rust DotEnv - A Lightweight Rust Library for Loading Environment Variables

rust_dotenv is a Rust library designed to load environment variables from .env files, supporting multiple environments and local overrides. This library is perfect for managing configurations dynamically across different environments like development, testing, and production.

Note: I'm French dev begginer in Rust, and this is my first Rust project! Feel free to open issues or submit pull requests to suggest improvements and new features. Contributions are more than welcome!

Features

• Environment-Specific Files: Loads variables from the default .env file or an environment-specific file like .env.development.
• Automatic Local Overrides: By default, rust_dotenv checks for a .local file, such as .env.development.local or .env.local. If this file exists, it will be prioritized over the main .env file, allowing for easy local configuration without modifying environment files directly.
• Convenient API: Provides methods to retrieve (get_var), check existence (has_var), and set new environment variables (set_var) without overwriting existing ones.

Installation

Add rust_dotenv to your Cargo.toml dependencies:

[dependencies]
rust_dotenv = "0.1.0"

Usage Example

1. Initializing rust_dotenv with an Environment

Use DotEnv::new() to load variables from a specified environment. Pass the environment name as a string (like "development"), or an empty string "" to load the default .env file.

use rust_dotenv::dotenv::DotEnv;

fn main() {
    // Load the default `.env` file
    let dotenv = DotEnv::new("");
    println!("Loaded variables (default): {:?}", dotenv.all_vars());

    // Load environment-specific file, e.g., `.env.development`
    let dotenv_dev = DotEnv::new("development");
    println!("Loaded variables (development): {:?}", dotenv_dev.all_vars());
}

2. Retrieving an Environment Variable with get_var

Retrieve a specific environment variable using get_var.

fn main() {
    let dotenv = DotEnv::new("development");

    if let Some(value) = dotenv.get_var("DATABASE_URL".to_string()) {
        println!("DATABASE_URL = {}", value);
    } else {
        println!("DATABASE_URL is not set.");
    }
}

3. Checking for a Variable with has_var

Check if a variable exists with has_var.

fn main() {
    let dotenv = DotEnv::new("development");

    if dotenv.has_var("SECRET_KEY".to_string()) {
        println!("SECRET_KEY is set.");
    } else {
        println!("SECRET_KEY is not set.");
    }
}

4. Setting a New Variable with set_var

Add a new variable dynamically without overwriting existing ones. set_var returns false if the variable already exists.

fn main() {
    let mut dotenv = DotEnv::new("development");

    let added = dotenv.set_var("NEW_VARIABLE".to_string(), "value".to_string());
    if added {
        println!("NEW_VARIABLE added successfully.");
    } else {
        println!("NEW_VARIABLE already exists.");
    }
}

Core API Overview

• DotEnv::new(env: &str) -> DotEnv: Loads variables from .env, .env.{env}, or .env.{env}.local, depending on the environment. If a .local file exists, it will take priority.
• get_var(&self, key: String) -> Option<String>: Retrieves the value of a variable.
• has_var(&self, key: String) -> bool: Checks if a variable is defined in the loaded configuration.
• all_vars(&self) -> HashMap<String, String>: Returns all environment variables as a HashMap.
• set_var(&mut self, key: String, value: String) -> bool: Adds a new variable only if it doesn’t already exist.

Contributing

This project is open to contributions and suggestions! Since it’s my first Rust project, any feedback or feature requests are appreciated. Don’t hesitate to open an issue or pull request to help improve rust_dotenv.

1. Fork the repo
2. Create a new branch (git checkout -b feature-branch)
3. Commit your changes (git commit -am 'Add new feature')
4. Push to the branch (git push origin feature-branch)
5. Create a pull request

This README introduces rust_dotenv's capabilities, clarifies its default behavior with .local files, and invites the community to contribute. Let me know if any further adjustments are needed!