From a980410a643d4611529cbed89fb307452dcda42e Mon Sep 17 00:00:00 2001 From: LeoniePhiline <22329650+LeoniePhiline@users.noreply.github.com> Date: Wed, 14 Dec 2022 15:10:11 +0100 Subject: [PATCH] fix(docs): Handle errors, rather than using `unwrap`, in examples (#52) - Remove `dirs` dev-dependency - Reword readme to include more updates to this fork from the original `dotenv` - Add better context to rustdoc examples --- CHANGELOG.md | 1 + dotenv/Cargo.toml | 1 - dotenv/README.md | 15 +++++--- dotenv/src/lib.rs | 98 +++++++++++++++++++++++++++++++++-------------- 4 files changed, 79 insertions(+), 36 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d5b2eb1a..2ac07a19 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm - Minimum Supported Rust Version is now 1.56.1 - Removed internal `dotenv_codegen_impl` crate and `proc_macro_hack` dependency +- Improved examples by handling errors, rather than using `unwrap`. ([PR #52](https://github.com/allan2/dotenvy/pull/52) by [LeoniePhiline](https://github.com/LeoniePhiline)) ## [0.15.6] - 2022-10-17 diff --git a/dotenv/Cargo.toml b/dotenv/Cargo.toml index 485faa72..c03e573e 100644 --- a/dotenv/Cargo.toml +++ b/dotenv/Cargo.toml @@ -29,7 +29,6 @@ clap = { version = "3.2", optional = true } [dev-dependencies] tempfile = "3.3.0" -dirs = "4.0" [features] cli = ["clap"] diff --git a/dotenv/README.md b/dotenv/README.md index 5fc70556..27902faf 100644 --- a/dotenv/README.md +++ b/dotenv/README.md @@ -22,17 +22,20 @@ This library loads environment variables from a _.env_ file. This is convenient ### Loading at runtime -```rs -use dotenvy::dotenv; +```rust use std::env; +use std::error::Error; -fn main() { - // load environment variables from .env file - dotenv().expect(".env file not found"); +fn main() -> Result<(), Box> { + // Load environment variables from .env file. + // Fails if .env file not found, not readable or invalid. + dotenvy::dotenv()?; for (key, value) in env::vars() { println!("{key}: {value}"); } + + Ok(()) } ``` @@ -59,13 +62,13 @@ This fork intends to serve as the development home for the dotenv implementation This repo fixes: -- home directory works correctly (no longer using the deprecated `std::env::home_dir`) - more helpful errors for `dotenv!` ([dotenv-rs/dotenv #57](https://github.com/dotenv-rs/dotenv/pull/57)) It also adds: - multiline support for environment variable values - `io::Read` support via [`from_read`](https://docs.rs/dotenvy/latest/dotenvy/fn.from_read.html) and [`from_read_iter`](https://docs.rs/dotenvy/latest/dotenvy/fn.from_read_iter.html) +- override support via [`dotenv_override`], [`from_filename_override`], [`from_path_override`] and [`from_read_override`] - improved docs For a full list of changes, refer to the [changelog](./CHANGELOG.md). diff --git a/dotenv/src/lib.rs b/dotenv/src/lib.rs index 0593950a..006bd772 100644 --- a/dotenv/src/lib.rs +++ b/dotenv/src/lib.rs @@ -31,8 +31,11 @@ static START: Once = Once::new(); /// # Examples: /// /// ```no_run -/// let value = dotenvy::var("HOME").unwrap(); +/// # fn main() -> Result<(), Box> { +/// let value = dotenvy::var("HOME")?; /// println!("{}", value); // prints `/home/foo` +/// # Ok(()) +/// # } /// ``` pub fn var>(key: K) -> Result { START.call_once(|| { @@ -72,10 +75,12 @@ pub fn vars() -> Vars { /// # Examples /// /// ```no_run -/// use dirs::home_dir; +/// use std::path::Path; /// -/// let my_path = home_dir().map(|a| a.join("/absolute/path/.env")).unwrap(); -/// dotenvy::from_path(my_path.as_path()); +/// # fn main() -> Result<(), Box> { +/// dotenvy::from_path(Path::new("path/to/.env"))?; +/// # Ok(()) +/// # } /// ``` pub fn from_path>(path: P) -> Result<()> { let iter = Iter::new(File::open(path).map_err(Error::Io)?); @@ -95,10 +100,12 @@ pub fn from_path>(path: P) -> Result<()> { /// # Examples /// /// ```no_run -/// use dirs::home_dir; +/// use std::path::Path; /// -/// let my_path = home_dir().map(|a| a.join("/absolute/path/.env")).unwrap(); -/// dotenvy::from_path_override(my_path.as_path()); +/// # fn main() -> Result<(), Box> { +/// dotenvy::from_path_override(Path::new("path/to/.env"))?; +/// # Ok(()) +/// # } /// ``` pub fn from_path_override>(path: P) -> Result<()> { let iter = Iter::new(File::open(path).map_err(Error::Io)?); @@ -110,14 +117,15 @@ pub fn from_path_override>(path: P) -> Result<()> { /// # Examples /// /// ```no_run -/// use dirs::home_dir; +/// use std::path::Path; /// -/// let my_path = home_dir().map(|a| a.join("/absolute/path/.env")).unwrap(); -/// -/// for item in dotenvy::from_path_iter(my_path.as_path()).unwrap() { -/// let (key, val) = item.unwrap(); +/// # fn main() -> Result<(), Box> { +/// for item in dotenvy::from_path_iter(Path::new("path/to/.env"))? { +/// let (key, val) = item?; /// println!("{}={}", key, val); /// } +/// # Ok(()) +/// # } /// ``` pub fn from_path_iter>(path: P) -> Result> { Ok(Iter::new(File::open(path).map_err(Error::Io)?)) @@ -136,13 +144,19 @@ pub fn from_path_iter>(path: P) -> Result> { /// /// # Examples /// ```no_run -/// dotenvy::from_filename("custom.env").unwrap(); +/// # fn main() -> Result<(), Box> { +/// dotenvy::from_filename("custom.env")?; +/// # Ok(()) +/// # } /// ``` /// /// It is also possible to load from a typical *.env* file like so. However, using [`dotenv`] is preferred. /// /// ``` -/// dotenvy::from_filename(".env").unwrap(); +/// # fn main() -> Result<(), Box> { +/// dotenvy::from_filename(".env")?; +/// # Ok(()) +/// # } /// ``` pub fn from_filename>(filename: P) -> Result { let (path, iter) = Finder::new().filename(filename.as_ref()).find()?; @@ -162,13 +176,19 @@ pub fn from_filename>(filename: P) -> Result { /// /// # Examples /// ```no_run -/// dotenvy::from_filename_override("custom.env").unwrap(); +/// # fn main() -> Result<(), Box> { +/// dotenvy::from_filename_override("custom.env")?; +/// # Ok(()) +/// # } /// ``` /// /// It is also possible to load from a typical *.env* file like so. However, using [`dotenv_override`] is preferred. /// /// ``` -/// dotenvy::from_filename_override(".env").unwrap(); +/// # fn main() -> Result<(), Box> { +/// dotenvy::from_filename_override(".env")?; +/// # Ok(()) +/// # } /// ``` pub fn from_filename_override>(filename: P) -> Result { let (path, iter) = Finder::new().filename(filename.as_ref()).find()?; @@ -181,10 +201,13 @@ pub fn from_filename_override>(filename: P) -> Result { /// # Examples /// /// ```no_run -/// for item in dotenvy::from_filename_iter("custom.env").unwrap() { -/// let (key, val) = item.unwrap(); +/// # fn main() -> Result<(), Box> { +/// for item in dotenvy::from_filename_iter("custom.env")? { +/// let (key, val) = item?; /// println!("{}={}", key, val); /// } +/// # Ok(()) +/// # } /// ``` pub fn from_filename_iter>(filename: P) -> Result> { @@ -214,8 +237,11 @@ pub fn from_filename_iter>(filename: P) -> Result> { /// use std::io::Read; /// use std::os::unix::net::UnixStream; /// -/// let mut stream = UnixStream::connect("/some/socket").unwrap(); -/// dotenvy::from_read(stream).unwrap(); +/// # fn main() -> Result<(), Box> { +/// let mut stream = UnixStream::connect("/some/socket")?; +/// dotenvy::from_read(stream)?; +/// # Ok(()) +/// # } /// ``` pub fn from_read(reader: R) -> Result<()> { let iter = Iter::new(reader); @@ -243,8 +269,11 @@ pub fn from_read(reader: R) -> Result<()> { /// use std::io::Read; /// use std::os::unix::net::UnixStream; /// -/// let mut stream = UnixStream::connect("/some/socket").unwrap(); -/// dotenvy::from_read_override(stream).unwrap(); +/// # fn main() -> Result<(), Box> { +/// let mut stream = UnixStream::connect("/some/socket")?; +/// dotenvy::from_read_override(stream)?; +/// # Ok(()) +/// # } /// ``` pub fn from_read_override(reader: R) -> Result<()> { let iter = Iter::new(reader); @@ -261,12 +290,15 @@ pub fn from_read_override(reader: R) -> Result<()> { /// use std::io::Read; /// use std::os::unix::net::UnixStream; /// -/// let mut stream = UnixStream::connect("/some/socket").unwrap(); +/// # fn main() -> Result<(), Box> { +/// let mut stream = UnixStream::connect("/some/socket")?; /// /// for item in dotenvy::from_read_iter(stream) { -/// let (key, val) = item.unwrap(); +/// let (key, val) = item?; /// println!("{}={}", key, val); /// } +/// # Ok(()) +/// # } /// ``` pub fn from_read_iter(reader: R) -> Iter { Iter::new(reader) @@ -288,7 +320,10 @@ pub fn from_read_iter(reader: R) -> Iter { /// # Examples /// /// ``` -/// dotenvy::dotenv().unwrap(); +/// # fn main() -> Result<(), Box> { +/// dotenvy::dotenv()?; +/// # Ok(()) +/// # } /// ``` pub fn dotenv() -> Result { let (path, iter) = Finder::new().find()?; @@ -308,8 +343,10 @@ pub fn dotenv() -> Result { /// /// # Examples /// ``` -/// use dotenvy::dotenv_override; -/// dotenv_override().ok(); +/// # fn main() -> Result<(), Box> { +/// dotenvy::dotenv_override()?; +/// # Ok(()) +/// # } /// ``` pub fn dotenv_override() -> Result { let (path, iter) = Finder::new().find()?; @@ -322,10 +359,13 @@ pub fn dotenv_override() -> Result { /// # Examples /// /// ``` -/// for item in dotenvy::dotenv_iter().unwrap() { -/// let (key, val) = item.unwrap(); +/// # fn main() -> Result<(), Box> { +/// for item in dotenvy::dotenv_iter()? { +/// let (key, val) = item?; /// println!("{}={}", key, val); /// } +/// # Ok(()) +/// # } /// ``` pub fn dotenv_iter() -> Result> { let (_, iter) = Finder::new().find()?;