diff --git a/itconfig/src/envstr.rs b/itconfig/src/envstr.rs index 7bed80a..8da5307 100644 --- a/itconfig/src/envstr.rs +++ b/itconfig/src/envstr.rs @@ -1,20 +1,46 @@ use std::ops::Deref; -#[doc(hidden)] +/// A trait for converting value to EnvString. +/// +/// This trait automatically implemented for any type which implements the +/// [`Display`] trait. As such, `ToEnvString` shouldn't be implemented directly: +/// [`Display`] should be implemented instead, and you get the `ToEnvString` +/// implementation for free. +/// +/// [`Display`]: std::fmt::Display pub trait ToEnvString { + /// Converts the giving value to a `EnvString`. + /// + /// # Examples + /// + /// basic usage + /// + /// ```rust + /// # use itconfig::{EnvString, ToEnvString}; + /// let i = 5; + /// let five = EnvString::from("5"); + /// assert_eq!(five, i.to_env_string()); + /// ``` fn to_env_string(&self) -> EnvString; } -#[doc(hidden)] +/// Simple and safe type conversions that may fail in a controlled way under +/// some circumstances. +/// +/// This trait automatically implemented for all standard primitives. If you +/// want to use your custom type in the library you need to implement +/// `ToEnvString` and `FromEnvString` manually. pub trait FromEnvString: Sized { + /// The type returned in the event of a conversion error. type Err; + /// Performs the conversion. fn from_env_string(s: &EnvString) -> Result; } impl ToEnvString for T where - T: ToString, + T: std::fmt::Display, { #[inline] fn to_env_string(&self) -> EnvString { @@ -68,6 +94,7 @@ impl FromEnvString for bool { } } +#[doc(hidden)] #[cfg(feature = "array")] #[derive(Debug)] pub enum ArrayEnvError { @@ -90,8 +117,7 @@ where .and_then(|vec| { vec.iter() .map(|v| { - v.to_env_string() - .parse::() + FromEnvString::from_env_string(&v.to_env_string()) .map_err(|_| ArrayEnvError::FailedToParse) }) .collect::, _>>() @@ -115,13 +141,20 @@ impl FromEnvString for &'static str { } } -#[doc(hidden)] +/// Wrapper under String type. +/// +/// When we read the environment variable, we automatically convert the value +/// to EnvString and then convert it to your expected type. +/// #[derive(Debug, PartialEq, Clone)] pub struct EnvString(String); -impl EnvString { - pub fn parse(&self) -> Result { - FromEnvString::from_env_string(self) +impl From for EnvString +where + T: ToEnvString, +{ + fn from(val: T) -> Self { + val.to_env_string() } } diff --git a/itconfig/src/error.rs b/itconfig/src/error.rs index 2b0c92a..7173c70 100644 --- a/itconfig/src/error.rs +++ b/itconfig/src/error.rs @@ -1,9 +1,13 @@ use std::error; use std::fmt; +/// The error type for operations interacting with environment variables #[derive(Debug, PartialEq)] pub enum EnvError { + /// The specified environment variable was not present in the current process's environment. MissingVariable(String), + + /// Failed to parse the specified environment variable. FailedToParse(String), } diff --git a/itconfig/src/getenv.rs b/itconfig/src/getenv.rs index a3240e5..8f2e911 100644 --- a/itconfig/src/getenv.rs +++ b/itconfig/src/getenv.rs @@ -1,4 +1,5 @@ -use crate::prelude::*; +use crate::envstr::*; +use crate::error::*; use std::env; /// This function is similar as `get_env`, but it unwraps result with panic on error. @@ -123,17 +124,14 @@ where .and_then(|env_str| parse_env_variable(env_name, env_str)) } -#[doc(hidden)] fn parse_env_variable(env_name: &str, env_str: EnvString) -> Result where T: FromEnvString, { - env_str - .parse::() + FromEnvString::from_env_string(&env_str) .map_err(|_| EnvError::FailedToParse(env_name.to_string())) } -#[doc(hidden)] fn make_panic(e: EnvError) -> T { panic!("{}", e) } diff --git a/itconfig/src/lib.rs b/itconfig/src/lib.rs index bee8ba7..32a2bb8 100644 --- a/itconfig/src/lib.rs +++ b/itconfig/src/lib.rs @@ -140,6 +140,7 @@ #![forbid(unsafe_code)] #![deny( missing_debug_implementations, + missing_docs, unstable_features, unused_imports, unused_qualifications @@ -149,18 +150,14 @@ ///////////////////////////////////////////////////////////////////////////// -pub mod envstr; +mod envstr; mod error; mod getenv; +pub use self::envstr::*; pub use self::error::*; pub use self::getenv::*; -pub mod prelude { - pub use crate::envstr::*; - pub use crate::error::*; -} - #[cfg(feature = "macro")] extern crate itconfig_macro; #[cfg(feature = "macro")]