From 1a455554f5e4b4211be5490309d580d18a4cdf56 Mon Sep 17 00:00:00 2001 From: Allan Zhang Date: Mon, 22 Aug 2022 12:26:37 -0400 Subject: [PATCH] Rewrite docs --- dotenv/Cargo.toml | 2 +- dotenv/src/lib.rs | 117 +++++++++++++++++++--------------------------- 2 files changed, 50 insertions(+), 69 deletions(-) diff --git a/dotenv/Cargo.toml b/dotenv/Cargo.toml index 16b0188e..979828f6 100644 --- a/dotenv/Cargo.toml +++ b/dotenv/Cargo.toml @@ -11,7 +11,7 @@ authors = [ "Arpad Borsos ", "Allan Zhang ", ] -description = "A well-maintained fork of the `dotenv` crate" +description = "A well-maintained fork of the dotenv crate" homepage = "https://github.com/allan2/dotenvy" readme = "README.md" keywords = ["dotenv", "env", "environment", "settings", "config"] diff --git a/dotenv/src/lib.rs b/dotenv/src/lib.rs index 9531d683..89334908 100644 --- a/dotenv/src/lib.rs +++ b/dotenv/src/lib.rs @@ -1,10 +1,7 @@ -//! This crate provides a configuration loader in the style of the [ruby dotenv -//! gem](https://github.com/bkeepers/dotenv). This library is meant to be used -//! on development or testing environments in which setting environment -//! variables is not practical. It loads environment variables from a .env -//! file, if available, and mashes those with the actual environment variables -//! provided by the operating system. -#![forbid(unsafe_code)] +//! [`dotenv`]: https://crates.io/crates/dotenv +//! A well-maintained fork of the [`dotenv`] crate +//! +//! This library loads environment variables from a *.env* file. This is convenient for dev environments. mod errors; mod find; @@ -24,16 +21,18 @@ use crate::iter::Iter; static START: Once = Once::new(); -/// After loading the dotenv file, fetches the environment variable key from the current process. +/// Gets the value for an environment variable. /// -/// The returned result is Ok(s) if the environment variable is present and is valid unicode. If the -/// environment variable is not present, or it is not valid unicode, then Err will be returned. +/// The value is `Ok(s)` if the environment variable is present and valid unicode. /// -/// Examples: +/// Note: this function gets values from any visible environment variable key, +/// regardless of whether a *.env* file was loaded. +/// +/// # Examples: /// /// ```no_run -/// let key = "FOO"; -/// let value= dotenvy::var(key).unwrap(); +/// let value = dotenvy::var("HOME").unwrap(); +/// println!("{value}"); // prints `/home/foo` /// ``` pub fn var>(key: K) -> Result { START.call_once(|| { @@ -42,16 +41,12 @@ pub fn var>(key: K) -> Result { env::var(key).map_err(Error::EnvVar) } -/// After loading the dotenv file, returns an iterator of (variable, value) pairs of strings, -/// for all the environment variables of the current process. +/// Returns an iterator of `(key, value)` pairs for all environment variables of the current process. +/// The returned iterator contains a snapshot of the process's environment variables at the time of invocation. Modifications to environment variables afterwards will not be reflected. /// -/// The returned iterator contains a snapshot of the process's environment variables at the -/// time of this invocation, modifications to environment variables afterwards will not be -/// reflected in the returned iterator. /// -/// Examples: +/// # Examples: /// -/// ```no_run /// use std::io; /// /// let result: Vec<(String, String)> = dotenvy::vars().collect(); @@ -63,15 +58,14 @@ pub fn vars() -> Vars { env::vars() } -/// Loads the file at the specified absolute path. +/// Loads environment variables from the specified path. /// -/// Examples +/// # Examples /// -/// ``` -/// use std::env; -/// use std::path::{Path}; +/// ```no_run +/// use dirs::home_dir; /// -/// let my_path = dirs::home_dir().map(|a| a.join("/.env")).unwrap(); +/// let my_path = home_dir().map(|a| a.join("/absolute/path/.env")).unwrap(); /// dotenvy::from_path(my_path.as_path()); /// ``` pub fn from_path>(path: P) -> Result<()> { @@ -79,38 +73,35 @@ pub fn from_path>(path: P) -> Result<()> { iter.load() } -/// Like [from_path], but returns an iterator over variables instead of loading into environment. +/// Returns an iterator over environment variables from the specified path. /// -/// Examples +/// # Examples /// /// ```no_run -/// use std::env; -/// use std::path::{Path}; +/// use dirs::home_dir; /// -/// let my_path = dirs::home_dir().map(|a| a.join("/.env")).unwrap(); -/// let iter = dotenvy::from_path_iter(my_path.as_path()).unwrap(); +/// let my_path = home_dir().map(|a| a.join("/absolute/path/.env")).unwrap(); /// -/// for item in iter { +/// for item in dotenvy::from_path_iter(my_path.as_path()).unwrap() { /// let (key, val) = item.unwrap(); -/// println!("{}={}", key, val); +/// println!("{key}={val}"); /// } /// ``` pub fn from_path_iter>(path: P) -> Result> { Ok(Iter::new(File::open(path).map_err(Error::Io)?)) } -/// Loads the specified file from the environment's current directory or its parents in sequence. +/// Loads environment variables from the specified file. /// /// # Examples -/// ``` -/// dotenvy::from_filename("custom.env").ok(); +/// ```no_run +/// dotenvy::from_filename("custom.env").unwrap(); /// ``` /// -/// It is also possible to do the following, but it is equivalent to using [dotenv], -/// which is preferred. +/// It is also possible to load from a typical *.env* file like so. However, using [dotenv] is preferred. /// /// ``` -/// dotenvy::from_filename(".env").ok(); +/// dotenvy::from_filename(".env").unwrap(); /// ``` pub fn from_filename>(filename: P) -> Result { let (path, iter) = Finder::new().filename(filename.as_ref()).find()?; @@ -118,34 +109,26 @@ pub fn from_filename>(filename: P) -> Result { Ok(path) } -/// Like [from_filename], but returns an iterator over variables instead of loading into environment. +/// Returns an iterator over environment variables from the specified file. /// /// # Examples -/// ``` -/// dotenvy::from_filename("custom.env").ok(); -/// ``` -/// -/// It is also possible to do the following, but it is equivalent to using [dotenv_iter], -/// which is preferred. -/// /// ```no_run -/// let iter = dotenvy::from_filename_iter(".env").unwrap(); -/// -/// for item in iter { -/// let (key, val) = item.unwrap(); -/// println!("{}={}", key, val); -/// } +/// for item in dotenvy::from_filename_iter("custom.env").unwrap() { +/// let (key, val) = item.unwrap(); +/// println!("{key}={val}"); +/// } /// ``` + pub fn from_filename_iter>(filename: P) -> Result> { let (_, iter) = Finder::new().filename(filename.as_ref()).find()?; Ok(iter) } -/// Loads from any arbitrary [io::Read](std::io::Read). +/// Loads environment variables from [io::Read](std::io::Read). /// -/// Useful when you're reading dotenv info from something like IPC or the network. +/// This is useful for loading environment variables from from IPC or the network. /// -/// If you're just opening a regular file, use [from_path] or [from_filename]. +/// For regular files, use [from_path] or [from_filename]. /// /// # Examples /// ```no_run @@ -162,7 +145,7 @@ pub fn from_read(reader: R) -> Result<()> { Ok(()) } -/// Like [from_read], but returns an iterator over variables instead of loading into environment. +/// Returns an iterator over environment variables from [io::Read](std::io::Read). /// /// # Examples /// @@ -172,23 +155,21 @@ pub fn from_read(reader: R) -> Result<()> { /// use std::os::unix::net::UnixStream; /// /// let mut stream = UnixStream::connect("/some/socket").unwrap(); -/// let iter = dotenvy::from_read_iter(stream); /// -/// for item in iter { +/// for item in dotenvy::from_read_iter(stream) { /// let (key, val) = item.unwrap(); -/// println!("{}={}", key, val); +/// println!("{key}={val}"); /// } /// ``` pub fn from_read_iter(reader: R) -> Iter { Iter::new(reader) } - -/// This is usually what you want. -/// It loads the .env file located in the environment's current directory or its parents in sequence. +/// Loads the *.env* file from the current directory or parents. This is typically what you want. /// +/// An error will be returned if the file is not found. /// # Examples /// ``` -/// dotenvy::dotenv().ok(); +/// dotenvy::dotenv().unwrap(); /// ``` pub fn dotenv() -> Result { let (path, iter) = Finder::new().find()?; @@ -196,13 +177,13 @@ pub fn dotenv() -> Result { Ok(path) } -/// Like [dotenv], but returns an iterator over variables instead of loading into environment. +/// Returns an iterator over environment variables. /// /// # Examples -/// ```no_run +/// ``` /// for item in dotenvy::dotenv_iter().unwrap() { /// let (key, val) = item.unwrap(); -/// println!("{}={}", key, val); +/// println!("{key}={val}"); /// } /// ``` pub fn dotenv_iter() -> Result> {