rust-env 0.2.0

//! # rust-env
//!
//! `rust-env` is a lightweight environment configuration library for Rust.
//!
//! It helps you manage `.env`-style configuration files with support for:
//! - Key-value pairs
//! - Vector (list) values using `;` separators
//! - Runtime OS environment variables
//! - Reading and writing environment files
//!
//! ---
//!
//! # Features
//!
//! - Parse `.env` files into structured data
//! - Support for string and vector values
//! - Access local and global environment variables
//! - Modify and persist environment files
//! - Simple helper API for extracting values
//!
//! ---
//!
//! # Value Model
//!
//! Internally, `rust-env` represents data using:
//!
//! - `Str(key, value)`
//! - `Vec(key, Vec<String>)`
//! - `Comment(String)`
//!
//! ---
//!
//! # Example
//!
//! ```rust
//! use rust_env::Env;
//!
//! let mut env = Env::new("./.env");
//!
//! let port = env.get_pair("PORT");
//! env.set(Str("PORT", "8080"));
//! ```
//!
//! ---
//!
//! # Local vs Global
//!
//! - **Local**: values loaded from `.env` file
//! - **Global**: OS environment variables
//!
//! When using merged lookup:
//! ```text
//! global > local
//! ```
//!
//! ---
//!
//! # Notes
//!
//! - All values are stored as strings internally
//! - Vector values are separated using `;`
//! - File writes occur immediately when using `set`
//!
//! ---
//!
//! # Version History
//!
//! ## v0.2.0
//! - Added `match_str` and `match_vec` helpers
//! - Refactored codebase into multiple files
//! - Fixed 3 known bugs
//!
//! ---
//!
//! # Experimental
//!
//! Experimental features such as a future markup language (RML) are **not part of this crate**.
//!
//! They may be developed separately in the future.

use std::env::vars;
use std::fs::{read_to_string, write};

use crate::Pair::Comment;

#[derive(Debug, Clone)]
/// This enum mainly rap two type of data
/// String and `Vec<String>`
/// See docs of `struct Env` of this package for learn more
pub enum Wrapper {
    Str(String),
    Vec(Vec<String>),
    Empty
}


#[derive(Clone, Debug, PartialEq)]
pub enum Pair {
    Str(String, String),
    Vec(String, Vec<String>),
    Comment(String)
}

#[allow(dead_code)]
struct SPair(String, String);

/// The main environment container used by `rust-env`.
///
/// `Env` manages both:
/// - Local environment variables loaded from a `.env` file
/// - Global environment variables from the operating system
///
/// It provides functionality to:
/// - Parse environment files into structured data
/// - Retrieve values (local, global, or merged)
/// - Modify environment entries
/// - Persist changes back to a file
///
/// # Internal Representation
///
/// Environment data is stored as a vector of `Pair`:
///
/// - `Pair::Str(key, value)` → single value
/// - `Pair::Vec(key, values)` → list of values (semicolon-separated in file)
/// - `Pair::Comment(text)` → comments in the file
///
/// # Fields
///
/// - `data`: Local environment variables loaded from file
/// - `global`: OS environment variables captured at runtime
/// - `path`: Path to the associated `.env` file
///
/// # Behavior Notes
///
/// - Local data comes from the file at `path`
/// - Global data is loaded via `std::env::vars()`
/// - `set()` writes changes immediately to disk
/// - Lookup functions may fall back between global/local depending on method
///
/// # Example
///
/// ```rust
/// use rust_env::{Env, Str};
///
/// let mut env = Env::new("./.env");
///
/// // Get a value
/// let port = env.get_pair("PORT");
///
/// // Set a value
/// env.set(Str("PORT", "8080"));
///
/// // Load OS environment variables
/// env.global_env();
///
/// // Debug print local env
/// env.debug_local();
/// ```
///
/// # Notes
///
/// - This struct is not thread-safe by default
/// - All values are stored internally as strings
/// - Vector values use `;` as delimiter in files
pub struct Env {
    pub data: Vec<Pair>,
    pub global: Vec<Pair>,
    pub path: String
}

/// A trait that defines the core behavior of an environment system.
///
/// This trait is mainly intended for advanced use cases where users want to
/// implement a custom environment backend while keeping compatibility with
/// the `rust-env` API.
///
/// Most users do NOT need to implement this trait directly.
///
/// # Purpose
///
/// `EnvFrame` allows you to:
/// - Define custom storage for environment data
/// - Customize parsing and serialization logic
/// - Extend or replace default `Env` behavior
///
/// # Example
///
/// ```rust
/// use rust_env::{EnvFrame, Pair};
///
/// struct CustomEnv {
///     data: Vec<Pair>,
///     global: Vec<Pair>,
///     path: String,
/// }
///
/// impl EnvFrame for CustomEnv {
///     // implement custom behavior here
/// }
/// ```
///
/// # Note
///
/// This trait is intended for advanced extensibility only.
/// Standard usage should rely on `Env`.
pub trait EnvFrame {
    fn marshal(val: Vec<Pair>) -> String;
    fn parse(content: String) -> Vec<Pair>;
    fn new(name: String) -> Env;
    fn load(&mut self, e: &str);
    fn get(&self, k: &str) -> Wrapper;
    fn get_debug(self) -> Vec<Pair>;
    fn set(&mut self, k: &str, v: Pair);
    fn debug(self);
    fn upload(path: &str, Pairs: Vec<Pair>) -> Env;
    fn global_env(&mut self);
    fn get_local(&self, k: &str) -> Wrapper;
    fn get_global(&self, k: &str) -> Wrapper;
}

#[allow(non_snake_case)]
#[allow(dead_code)]
pub fn Str(a: &str, b: &str) -> Pair {
    Pair::Str(a.to_string(), b.to_string())
}

pub fn get_d(d: Vec<Pair>, key: String) -> Wrapper {
    for h in d.into_iter() {

        match h {
            Pair ::Str(k, v)
            if k == key => {
                return Wrapper::Str(v)
            },
            Pair ::Vec(k, v)
            if k == key => {
                return Wrapper::Vec(v)
            },
            _ => continue
        }
    }

    return Wrapper::Empty;
}

/// On version 0.2.0 of rust-env DX improved
/// You don't need to match a `Wrapper` variant
/// Instead use `match_str` and `match vec`
/// Here's a example
/// # Example
/// ```
/// use rust_env::{Env, match_str, match_vec, Wrapper};
///
/// let env = Env::new("./config.env");
///
/// //On version 0.1.0
/// let addr = match env.get_local("ADDR") {
///     Wrapper::Str(e) => e,
///     Wrapper::Vec(v) => panic!("Can't use vec instead of string"),
///     _ => String::new()
/// };
/// let ip = match env.get_local("ip") {
///     Wrapper::Vec(e) => e,
///     Wrapper::Str(v) => panic!("Can't use string instead of vec"),
///     _ => String::new()
/// };
///
/// //Now (v0.2.0)
///
/// let addr: String = match_str(env.get_local("ADDR"));
/// let ip: Vec<String> = match_vec(env.get_local("IP"));
/// ```

#[allow(dead_code)]
pub fn match_str(w: Wrapper) -> String {
    return match w {
        Wrapper::Str(s) => s,
        Wrapper::Vec(_) => {
            panic!("Can't extract string from Wrapper::Vec");
        }
        _ => String::new()
    }
}

/// On version 0.2.0 of rust-env DX improved
/// You don't need to match a `Wrapper` variant
/// Instead use `match_str` and `match vec`
/// Here's a example
/// # Example
/// ```
/// use rust_env::{Env, match_str, match_vec, Wrapper};
///
/// let env = Env::new("./config.env");
///
/// //On version 0.1.0
/// let addr = match env.get_local("ADDR") {
///     Wrapper::Str(e) => e,
///     Wrapper::Vec(v) => panic!("Can't use vec instead of string"),
///     _ => String::new()
/// };
/// let ip = match env.get_local("ip") {
///     Wrapper::Vec(e) => e,
///     Wrapper::Str(v) => panic!("Can't use string instead of vec"),
///     _ => String::new()
/// };
///
/// //Now (v0.2.0)
///
/// let addr: String = match_str(env.get_local("ADDR"));
/// let ip: Vec<String> = match_vec(env.get_local("IP"));
/// ```
#[allow(dead_code)]
pub fn match_vec(w: Wrapper) -> Vec<String> {
    return match w {
        Wrapper::Vec(s) => s,
        Wrapper::Str(_) => {
            panic!("Can't extract string from Wrapper::Str")
        }
        _ => Vec::new()
    }
}

fn has(b: Vec<Pair>, h: Pair) -> bool {
    let mut res = false;

    for vals in b.into_iter() {
        if vals == h {
            res = true;
            break;
        }
    }

    res
}

impl Env {
    #[allow(dead_code)]
    /// Parses a raw environment string into a list of `Pair` values.
    ///
    /// This function converts `.env`-style text into structured data.
    ///
    /// # Format Rules
    ///
    /// Each line is expected to follow:
    ///
    /// ```text
    /// KEY=VALUE
    /// ```
    ///
    /// Supported formats:
    ///
    /// - Single value:
    ///   ```text
    ///   PORT=8080
    ///   ```
    ///
    /// - Vector value (semicolon-separated):
    ///   ```text
    ///   IP=127;0;0;1
    ///   ```
    ///
    /// # Behavior
    ///
    /// - Lines without `=` are ignored
    /// - Empty keys are ignored
    /// - Values containing `;` are treated as vectors
    /// - Whitespace around values is trimmed
    ///
    /// # Returns
    ///
    /// A `Vec<Pair>` representing parsed environment entries.
    ///
    /// # Example
    ///
    /// ```rust
    /// use rust_env::Env;
    ///
    /// let data = Env::parse("PORT=8080\nIP=127;0;0;1");
    /// ```
    ///
    /// # Notes
    ///
    /// - This function does not read from files directly
    /// - It only parses in-memory strings
    /// - Comments are not fully supported unless explicitly handled
    pub fn parse(content: &str) -> Vec<Pair> {
        let s = content.to_string();
        let lines = s.split("\n").collect::<Vec<&str>>();
        let mut res: Vec<Pair> = Vec::new();

        for _lines in lines.iter() {
            let Pair_ = _lines.split_once("=").unwrap_or_default();

            if Pair_.0 == "" {
                if _lines.starts_with("#") {
                    res.push(Comment(String::from(&_lines[1..])));
                    continue; 
                }
                continue;
            }

            let raw_value = Pair_.1;
            let mut value: Pair = Pair::Comment(String::new());

            match raw_value.find(";") {
                Some(_) => {
                    let raw = raw_value.split(";").collect::<Vec<&str>>();
                    let mut str_vec: Vec<String> = Vec::new();

                    for r in raw.into_iter() {
                        str_vec.push(r.to_string());
                    }
                    value = Pair::Vec(
                        Pair_.0.to_string(),
                        str_vec)
                }
                None => {
                    value = Pair::Str(Pair_.0.to_string(),
                                      Pair_.1.trim().to_string())
                }
            }

            res.push(value);
        }

        return res;
    }

    /// Converts a vector of `Pair` values into a valid `.env` formatted string.
    ///
    /// This is the inverse of `parse()`.
    ///
    /// It serializes structured environment data back into text form.
    ///
    /// # Output Format
    ///
    /// - `Pair::Str(key, value)` →
    ///   ```text
    ///   KEY=VALUE
    ///   ```
    ///
    /// - `Pair::Vec(key, values)` →
    ///   ```text
    ///   KEY=a;b;c
    ///   ```
    ///
    /// - `Pair::Comment(text)` →
    ///   ```text
    ///   #text
    ///   ```
    ///
    /// # Behavior
    ///
    /// - Values in vectors are joined using `;`
    /// - Keys and values are written exactly as stored
    /// - No escaping is applied for special characters
    ///
    /// # Returns
    ///
    /// A formatted `.env` string.
    ///
    /// # Example
    ///
    /// ```rust
    /// use rust_env::{Env, Str};
    ///
    /// let data = vec![
    ///     Str("PORT", "8080"),
    /// ];
    ///
    /// let out = Env::marshal(data);
    /// ```
    ///
    /// # Notes
    ///
    /// - This function does not write to files
    /// - Formatting is minimal and not lossless (comments/order may be simplified)

    pub fn marshal(val: Vec<Pair>) -> String {
        let mut Pair = String::new();

        for v in val.into_iter() {
            Pair.push_str(match v.clone() {
                Pair::Str(a, _) => a,
                Pair::Vec(a, _) => a,
                _ => String::new()
            }.as_str());
            Pair.push('=');
            Pair.push_str(match v.clone() {
                Pair::Str(_, b) => b,
                Pair::Vec(_, v) => {
                    let mut s = String::new();

                    for v in v.clone() {
                        s.push_str(v.as_str());
                        s.push(';')
                    }

                    s
                },
                Pair::Comment(s) => format!("#{s}")
            }.as_str());
        }

        return Pair;
    }

    /// Creates a new `Env` instance from a `.env` file.
    ///
    /// This function reads the file at the given path and parses its contents
    /// into structured environment data.
    ///
    /// # Behavior
    ///
    /// - Loads local environment variables from the file
    /// - Parses content using `.env` rules (`KEY=VALUE`)
    /// - Stores results in `self.data`
    /// - Initializes an empty global environment store
    ///
    /// # Arguments
    ///
    /// - `name`: Path to the `.env` file
    ///
    /// # Returns
    ///
    /// A fully initialized `Env` instance containing:
    /// - `data`: parsed local environment variables
    /// - `global`: empty until `global_env()` is called
    /// - `path`: stored file path
    ///
    /// # Example
    ///
    /// ```rust
    /// use rust_env::Env;
    ///
    /// let env = Env::new("./.env");
    /// ```
    ///
    /// # Notes
    ///
    /// - Panics if the file path is invalid or unreadable
    /// - This does NOT load OS environment variables automatically
    /// - Use `global_env()` to populate global environment data
    pub fn new(name: &str) -> Env {
        let content = read_to_string(name.clone()).expect("Invalid path");
        let local = Env::parse(content.as_str());

        Self {
            data: local,
            path: name.to_string().clone(),
            global: Vec::new()
        }
    }

    #[allow(dead_code)]
    /// It will return the entire env
    /// local and global
    /// # Example
    /// ```
    /// use rust_env::{Env, Pair};
    ///
    /// let env = Env::new("./.env");
    /// let e: Vec<Pair> = env.get_debug();
    /// ```

    pub fn get_debug(self) -> Vec<Pair> { return self.data.clone() }
    #[allow(dead_code)]

    /// Creates a new `Env` instance from a `.env` file.
    ///
    /// This function reads the file at the given path and parses its contents
    /// into structured environment data.
    ///
    /// # Behavior
    ///
    /// - Loads local environment variables from the file
    /// - Parses content using `.env` rules (`KEY=VALUE`)
    /// - Stores results in `self.data`
    /// - Initializes an empty global environment store
    ///
    /// # Arguments
    ///
    /// - `name`: Path to the `.env` file
    ///
    /// # Returns
    ///
    /// A fully initialized `Env` instance containing:
    /// - `data`: parsed local environment variables
    /// - `global`: empty until `global_env()` is called
    /// - `path`: stored file path
    ///
    /// # Example
    ///
    /// ```rust
    /// use rust_env::Env;
    ///
    /// let env = Env::new("./.env");
    /// ```
    ///
    /// # Notes
    ///
    /// - Panics if the file path is invalid or unreadable
    /// - This does NOT load OS environment variables automatically
    /// - Use `global_env()` to populate global environment data
    pub fn set(&mut self, h: Pair) {

        if !has(self.data.clone(), h.clone()) {
            self.data.push(h.clone());
        }
        let Pair = Env::marshal(vec![h]);

        write(&self.path, Pair).expect(
            "Invalid path to write")
    }

    /// Loads environment data into the current `Env` instance.
    ///
    /// This function parses a raw `.env`-style string and merges it into
    /// the existing local environment data.
    ///
    /// It is similar to `set`, but operates on multiple entries at once
    /// and does not directly write to disk.
    ///
    /// # Behavior
    ///
    /// - Parses the input string using `.env` rules (`KEY=VALUE`)
    /// - Supports vector values using `;` separators
    /// - Ignores duplicate keys already present in `self.data`
    /// - Only updates in-memory state (does NOT persist to file)
    ///
    /// # Arguments
    ///
    /// - `e`: A raw environment string (e.g. `"PORT=8080\nIP=127;0;0;1"`)
    ///
    /// # Example
    ///
    /// ```rust
    /// use rust_env::Env;
    ///
    /// let mut env = Env::new("./.env");
    ///
    /// env.load("PORT=8080\nHOST=127.0.0.1");
    /// env.debug();
    /// ```
    ///
    /// # Notes
    ///
    /// - This does NOT modify the file on disk
    /// - Use `set` or `upload` for persistent changes
    /// - Duplicate keys are ignored based on existing local data
    #[allow(dead_code)]
    pub fn load(&mut self, e: &str) {
        let h = Env::parse(e);

        for Pair in h.into_iter() {
            if !has(self.data.clone(), Pair.clone()) {
                self.data.push(Pair.clone())
            }
        }
    }


    #[allow(dead_code)]
    /// It's a function to debug the entire env
    /// # Example
    /// ```
    /// use rust_env::Env;
    /// let env: Env = Env::new("./.env");
    ///
    /// env.debug();
    /// ```

    pub fn debug(&self) { println!("{:?}", self.data) }
    #[allow(dead_code)]
    /// This function allows one to marshal env pairs and write them to a certain file
    /// It's similar to the `new` function
    /// But you can write external data to the
    /// env file
    /// # Example
    /// ```
    /// use rust_env::{Env, Str, Vct};
    ///
    /// let env = Env::upload("./env", vec![
    ///       Str("PORT", "6778"),
    ///       Vct("IP", vec![
    ///          "127",
    ///           "0",
    ///           "0"
    ///       ])
    /// ]);
    /// ```
    pub fn upload(path: &str, Pairs: Vec<Pair>) -> Env {
        let mut data: Vec<Pair> = Vec::new();
        let mut out = String::new();

        for Pair in Pairs.into_iter() {
            match Pair.clone() {
                Pair::Str(a, b) => {
                    data.push(Pair.clone());

                    out.push_str(&*a);
                    out.push('=');
                    out.push_str(&*b);
                    out.push_str("\n");
                },
                Pair::Vec(a, vector) => {
                    data.push(Pair::Vec(a.clone(), vector.clone()));

                    let mut raw_literal = a;
                    raw_literal.push('=');

                    for ve in vector.clone().into_iter() {
                        raw_literal.push_str(&*ve);
                        raw_literal.push_str(";")
                    }

                    out.push_str(&*raw_literal);
                }
                _ => {}
            }
        }
        write(path, out).expect(
            "Invalid path to write");

        Self {
            data,
            global: Vec::new(),
            path: path.to_string()
        }
    }

    ///You can upload the global env data on the environment
    ///# Example
    ///```
    /// use rust_env::Env;
    ///
    /// let mut env: Env = Env::upload("./.env", vec![
    ///     //put your local config
    /// ]);
    ///
    /// env.debug();
    /// env.global_env();
    /// env.debug();
    #[allow(dead_code)]
    pub fn global_env(&mut self) {
        for (k, v) in vars() {
            self.global.push(Pair::Str(k, v));
        }
    }

    #[allow(dead_code)]
    /// get_local is similar to `get_Pair`
    /// But, You can just gt the local config
    /// Not the global
    /// # Example
    /// ```
    /// use rust_env::Wrapper;
    ///
    /// let port = match get_local("PORT") {
    ///     Wrapper::Str(v) => v,
    ///     e => e
    /// };
    pub fn get_local(&self, k: &str) -> Wrapper {
        get_d(self.data[..].to_vec(), k.to_string())
    }

    #[allow(dead_code)]
    /// Retrieves a value from the global (OS-level) environment variables.
    ///
    /// This function searches only in the runtime environment provided by
    /// `std::env::vars()`, which is captured when `global_env()` is called.
    ///
    /// # Behavior
    ///
    /// - Searches only global environment variables
    /// - Does NOT fall back to local `.env` data
    /// - Returns the first matching key if found
    ///
    /// # Returns
    ///
    /// A `Wrapper` enum:
    /// - `Wrapper::Str(String)` for single values
    /// - `Wrapper::Vec(Vec<String>)` (rare, depending on parsing rules)
    /// - `Wrapper::Empty` if the key does not exist
    ///
    /// # Arguments
    ///
    /// - `k`: The environment variable key to search for
    ///
    /// # Example
    ///
    /// ```rust
    /// use rust_env::{Env, Wrapper};
    ///
    /// let mut env = Env::new("./.env");
    /// env.global_env(); // load OS environment variables
    ///
    /// match env.get_global("PATH") {
    ///     Wrapper::Str(v) => println!("PATH = {}", v),
    ///     Wrapper::Empty => println!("Not found"),
    ///     _ => println!("Unexpected format"),
    /// }
    /// ```
    ///
    /// # Notes
    ///
    /// - This only works after calling `global_env()`
    /// - Values come from the OS environment at runtime
    /// - This does not read from `.env` files
    /// - Lookup is linear (O(n))
    pub fn get_global(&self, k: &str) -> Wrapper { get_d(self.global[..].to_vec(), k.to_string()) }

    /// It will print the global env
    #[allow(dead_code)]
    pub fn debug_global(&self) { println!("{:?}", self.global) }

    /// It will print the local env
    /// # Example
    /// ```
    /// use rust_env::Env;
    ///
    /// let mut env = Env::new("./.env");
    /// env.global_env();
    ///
    /// //printing just global env
    /// env.debug_global();
    ///
    /// //printing just local env
    /// env.debug_local()
    /// ```
    #[allow(dead_code)]
    pub fn debug_local(&self) { println!("{:?}", self.data) }

    #[allow(dead_code)]
    /// Retrieves a value from the environment, checking both global and local scopes.
    ///
    /// This function performs a merged lookup:
    ///
    /// 1. Checks global environment variables (OS-level)
    /// 2. Falls back to local `.env` data if not found
    ///
    /// # Lookup Order
    ///
    /// ```text
    /// global → local
    /// ```
    ///
    /// # Behavior
    ///
    /// - Returns the first matching key found
    /// - If the value is a string, returns `Wrapper::Str`
    /// - If the value is a list, returns `Wrapper::Vec`
    /// - If the key does not exist, returns `Wrapper::Empty`
    ///
    /// # Arguments
    ///
    /// - `k`: The key to search for
    ///
    /// # Returns
    ///
    /// A `Wrapper` enum containing:
    /// - `Wrapper::Str(String)` for single values
    /// - `Wrapper::Vec(Vec<String>)` for list values
    /// - `Wrapper::Empty` if not found
    ///
    /// # Example
    ///
    /// ```rust
    /// use rust_env::{Env, Wrapper};
    ///
    /// let mut env = Env::new("./.env");
    /// env.global_env();
    ///
    /// match env.get_pair("PORT") {
    ///     Wrapper::Str(v) => println!("PORT = {}", v),
    ///     Wrapper::Vec(v) => println!("List = {:?}", v),
    ///     Wrapper::Empty => println!("Not found"),
    /// }
    /// ```
    ///
    /// # Notes
    ///
    /// - Global variables override local ones
    /// - This function does not modify state
    /// - Lookup is linear (O(n)) in both environments
    pub fn get_pair(&mut self, k: &str) -> Wrapper {
        return match get_d(self.global[..].to_vec(), k.to_string()) {
            Wrapper::Empty => get_d(self.data[..].to_vec(), k.to_string()),
            e => e
        };
    }
}