//! [![ci-badge][]][ci] [![license-badge][]][license] [![docs-badge][]][docs] [![rust badge]][rust link]
//!
//! # kankyo
//!
//! `kankyo` is a crate for the loading and unloading of `.env` files or other
//! readers into and from the environment.
//!
//! This crate is meant to be a more modular and efficient, yet concise
//! collection of functions exposed for any custom requirement. Due to its
//! design, it is applicable in both synchronous and asynchronous applications.
//!
//! ### Installation
//!
//! This library requires at least Rust 1.0.0.
//!
//! Add the following dependency to your project's `Cargo.toml`:
//!
//! ```toml
//! kankyo = "0.3"
//! ```
//!
//! ### What are `.env` files?
//!
//! Environment variable files, often named `.env`, are files usually located at
//! the project root. The contents of the file are `=` (equals sign)-delimited
//! lines of key-value pairs. A sample file might look like:
//!
//! ```ini
//! DEBUG=info
//! DB_HOST=127.0.0.1 # This is a comment, not parsed as part of the value.
//!
//! # Empty lines are ignored, as are lines solely consisting of a comment.
//! ```
//!
//! The library works with interfacing over readers (types implementing the
//! `std::io::Read` trait), meaning that you can pass slices of bytes, strings,
//! files, etc. to it.
//!
//! For example, opening a file and parsing its contents into the environment,
//! overwriting existing variables:
//!
//! ```rust,no_run
//! extern crate kankyo;
//!
//! use std::fs::File;
//!
//! # use std::error::Error;
//! #
//! # fn try_main() -> Result<(), Box<Error>> {
//! let mut file = try!(File::open("./.env"));
//!
//! try!(kankyo::load_from_reader(&mut file, true));
//!
//! println!("Loaded!");
//! #     Ok(())
//! # }
//! #
//! # fn main() {
//! #     try_main().unwrap();
//! # }
//! ```
//!
//! Due to the common nature of this operation, a function that does precisely
//! this is offered:
//!
//! ```rust,no_run
//! extern crate kankyo;
//!
//! # use std::error::Error;
//! #
//! # fn try_main() -> Result<(), Box<Error>> {
//! try!(kankyo::init());
//!
//! println!("Loaded!");
//! #     Ok(())
//! # }
//! #
//! # fn main() {
//! #     try_main().unwrap();
//! # }
//! ```
//!
//! [ci]: https://travis-ci.org/rusty-crates/kankyo
//! [ci-badge]: https://img.shields.io/travis/rusty-crates/kankyo.svg?style=flat-square
//! [docs]: https://docs.rs/kankyo
//! [docs-badge]: https://img.shields.io/badge/docs-online-5023dd.svg?style=flat-square
//! [license]: https://opensource.org/licenses/ISC
//! [license-badge]: https://img.shields.io/badge/license-ISC-blue.svg?style=flat-square
//! [rust badge]: https://img.shields.io/badge/rust-1.0+-93450a.svg?style=flat-square
//! [rust link]: https://blog.rust-lang.org/2015/05/15/Rust-1.0.html
#![deny(missing_docs)]

pub mod utils;

use std::env;
use std::collections::HashMap;
use std::ffi::OsStr;
use std::fs::File;
use std::io::Result as IoResult;
use std::io::Read;
use std::path::Path;

/// Loads a key from the current environment. This is more or less an alias of
/// `std::env::var`, but the benefit - slightly - is one less possible use
/// statement.
///
/// # Examples
///
/// Retrieve a key from the environment:
///
/// ```rust,no_run
/// # use std::error::Error;
/// #
/// # fn try_main() -> Result<(), Box<Error>> {
/// try!(kankyo::load(false));
///
/// if let Some(value) = kankyo::key("MY_KEY") {
///     println!("The value of MY_KEY is: {}", value);
/// }
/// #     Ok(())
/// # }
/// #
/// # fn main() {
/// #     try_main().unwrap();
/// # }
/// ```
#[inline]
pub fn key<T: AsRef<OsStr>>(name: T) -> Option<String> {
    _key(name.as_ref())
}

fn _key(name: &OsStr) -> Option<String> {
    env::var(name).ok()
}

/// Loads a `.env` file at the current working directory (`./.env`), overwriting
/// existing variables.
///
/// This is like [`load`], but always overwrites existing variables.
///
/// # Examples
///
/// ```rust,no_run
/// # use std::error::Error;
/// #
/// # fn try_main() -> Result<(), Box<Error>> {
/// #
/// try!(kankyo::init());
///
/// println!("Loaded!");
/// #     Ok(())
/// # }
/// #
/// # fn main() {
/// #     try_main().unwrap();
/// # }
/// ```
///
/// [`load`]: fn.load.html
#[inline]
pub fn init() -> IoResult<()> {
    load(true)
}

/// Loads a `.env` file at the current working directory (`./.env`).
///
/// # Examples
///
/// ```rust,no_run
/// # use std::error::Error;
/// #
/// # fn try_main() -> Result<(), Box<Error>> {
/// try!(kankyo::load(false));
///
/// println!("Loaded!");
/// #     Ok(())
/// # }
/// #
/// # fn main() {
/// #     try_main().unwrap();
/// # }
/// ```
///
/// # Errors
///
/// Returns an `std::io::Error` if there was an error reading the file.
#[inline]
pub fn load(overwrite: bool) -> IoResult<()> {
    load_from_path("./.env", overwrite)
}

/// Reads the content of a file at a given path to find `.env` lines.
pub fn load_from_path<P: AsRef<Path>>(
    path: P,
    overwrite: bool,
) -> IoResult<()> {
    _load_from_path(path.as_ref(), overwrite)
}

fn _load_from_path(path: &Path, overwrite: bool) -> IoResult<()> {
    let content = try!(read_from_path(path));
    utils::set_variables(&utils::parse_lines(&content), overwrite);

    Ok(())
}

/// Reads the content of a reader and parses it to find `.env` lines.
///
/// # Errors
///
/// Returns an `std::io::Error` if there was an error reading from the reader.
pub fn load_from_reader<R: Read>(
    reader: &mut R,
    overwrite: bool,
) -> IoResult<()> {
    let content = try!(read_to_string(reader));
    utils::set_variables(&utils::parse_lines(&content), overwrite);

    Ok(())
}

/// Creates a snapshot of the present environment variables.
///
/// This is similar to `std::env::vars`, but will instead return a HashMap over
/// only the environment variables that are valid UTF-8.
///
/// # Examples
///
/// ```rust,no_run
/// # use std::error::Error;
/// #
/// # fn try_main() -> Result<(), Box<Error>> {
/// let snapshot = kankyo::snapshot();
///
/// try!(kankyo::load(false));
/// #     Ok(())
/// # }
/// #
/// # fn main() {
/// #     try_main().unwrap();
/// # }
/// ```
pub fn snapshot() -> HashMap<String, String> {
    env::vars_os().into_iter().filter_map(utils::parse_kv).collect()
}

/// Unloads all environment variables in the default `./.env` file from the
/// current environment.
///
/// # Examples
///
/// ```rust,no_run
/// # use std::error::Error;
/// #
/// # fn try_main() -> Result<(), Box<Error>> {
/// try!(kankyo::load(false));
/// println!("Loaded!");
///
/// try!(kankyo::unload());
/// println!("Unloaded!");
/// #     Ok(())
/// # }
/// #
/// # fn main() {
/// #     try_main().unwrap();
/// # }
/// ```
///
/// # Errors
///
/// Returns an `std::io::Error` if there was an error reading from the reader.
#[inline]
pub fn unload() -> IoResult<()> {
    unload_from_path("./.env")
}

/// Unloads from the read content of the given path.
///
/// The path should contain content that of a `.env` file.
///
/// If you need to unload a given slice of keys, prefer [`utils::unload`]. If
/// you need to unload from a reader (e.g. an in-memory buffer), prefer
/// [`unload_from_reader`]. If you need to just unload from a `.env` file,
/// prefer [`unload`].
///
/// # Examples
///
/// Unload from a file at the path `./.prod.env`:
///
/// ```rust,no_run
/// # use std::error::Error;
/// #
/// # fn try_main() -> Result<(), Box<Error>> {
/// #
/// try!(kankyo::unload_from_path("./.prod.env"));
///
/// println!("Successfully unloaded from `./.prod.env`");
/// #     Ok(())
/// # }
/// #
/// # fn main() {
/// #     try_main().unwrap();
/// # }
/// ```
///
/// [`unload`]: fn.unload.html
/// [`unload_from_reader`]: fn.unload_from_reader.html
/// [`utils::unload`]: utils/fn.unload.html
pub fn unload_from_path<P: AsRef<Path>>(path: P) -> IoResult<()> {
    _unload_from_path(path.as_ref())
}

fn _unload_from_path(path: &Path) -> IoResult<()> {
    let content = try!(read_from_path(path));
    utils::unload_from_parsed_lines(&utils::parse_lines(&content));

    Ok(())
}

/// Unloads from the read content of the given reader.
///
/// The reader should contain content that of a `.env` file.
///
/// If you need to unload a given slice of keys, prefer [`utils::unload`]. If
/// you need to just unload from a `.env` file, prefer [`unload`].
///
/// # Examples
///
/// Unload from a file at the path `./.env`:
///
/// ```rust,no_run
/// # use std::error::Error;
/// #
/// # fn try_main() -> Result<(), Box<Error>> {
/// #
/// use std::fs::File;
///
/// let mut file = try!(File::open("./.env"));
///
/// try!(kankyo::unload_from_reader(&mut file));
///
/// println!("Successfully unloaded from `./.env`");
/// #     Ok(())
/// # }
/// #
/// # fn main() {
/// #     try_main().unwrap();
/// # }
/// ```
///
/// # Errors
///
/// Returns an `std::io::Error` if there is an error reading from the reader.
///
/// [`unload`]: fn.unload.html
/// [`utils::unload`]: utils/fn.unload.html
pub fn unload_from_reader<R: Read>(reader: &mut R) -> IoResult<()> {
    let buf = try!(read_to_string(reader));
    let lines = utils::parse_lines(&buf);
    utils::unload_from_parsed_lines(&lines);

    Ok(())
}

fn read_from_path<P: AsRef<Path>>(path: P) -> IoResult<String> {
    read_to_string(&mut try!(File::open(path)))
}

fn read_to_string<R: Read>(reader: &mut R) -> IoResult<String> {
    let mut s = String::new();
    try!(reader.read_to_string(&mut s));

    Ok(s)
}

#[cfg(test)]
mod test {
    use std::io::Cursor;
    use super::*;

    #[test]
    fn test_key() {
        utils::set_variables(&[("foo", "1")], true);
        assert!(key("foo").is_some());
        utils::unload(&["foo"]);
    }

    #[test]
    fn test_reader_loaders() {
        let text = "A=B\nC=D".to_owned().into_bytes();

        let mut cursor = Cursor::new(text);

        load_from_reader(&mut cursor, true).unwrap();

        cursor.set_position(0);
        unload_from_reader(&mut cursor).unwrap();
    }

    #[test]
    fn test_snapshot() {
        utils::set_variables(&[("A", "B")], true);
        let snap = snapshot();
        assert!(snap.contains_key("A"));
    }
}