From c3caa22b942ee6ff7f69b73c461cc443dac9b19a Mon Sep 17 00:00:00 2001 From: Dmitriy Pleshevskiy Date: Fri, 16 Apr 2021 01:04:35 +0300 Subject: [PATCH 1/2] chore: add documentation for env string --- itconfig/src/envstr.rs | 51 ++++++++++++++++++++++++++++++++++-------- itconfig/src/error.rs | 4 ++++ itconfig/src/getenv.rs | 8 +++---- itconfig/src/lib.rs | 9 +++----- 4 files changed, 52 insertions(+), 20 deletions(-) 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")] From c4573bfc487b129ca7c81148524c810440ff4da4 Mon Sep 17 00:00:00 2001 From: Dmitriy Pleshevskiy Date: Fri, 16 Apr 2021 01:12:35 +0300 Subject: [PATCH 2/2] chore: mark json array as deprecated --- README.md | 2 +- itconfig/Cargo.toml | 5 ++- itconfig/src/envstr.rs | 97 +++++++++++++++++++++++------------------- itconfig/src/lib.rs | 2 +- 4 files changed, 58 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 4a2ee26..a3ef219 100644 --- a/README.md +++ b/README.md @@ -128,7 +128,6 @@ cargo test --all-features * **default** - ["primitives"] * **macro** - Activates `config!` macros for easy configure web application. -* **array** - Add EnvString impl for vector type (uses optional `serde_json` package). * **primitives** - Group for features: `numbers` and `bool`. * **numbers** - Group for features: `int`, `uint` and `float`. * **int** - Group for features: `i8`, `i16`, `i32`, `i64`, `i128` and `isize`. @@ -149,6 +148,7 @@ cargo test --all-features * **f32** - impl EnvString for `f32` type * **f64** - impl EnvString for `f64` type * **bool** - impl EnvString for `bool` type +* **json_array** - Add EnvString impl for vector type (uses optional `serde_json` package). ⚠ **_DEPRECATED_** ## License diff --git a/itconfig/Cargo.toml b/itconfig/Cargo.toml index c327ec2..15d80d3 100644 --- a/itconfig/Cargo.toml +++ b/itconfig/Cargo.toml @@ -26,8 +26,6 @@ default = ["primitives"] macro = ["itconfig-macro"] -array = ["serde_json"] - primitives = ["numbers", "bool"] numbers = ["int", "uint", "float"] int = ["i8", "i16", "i32", "i64", "i128", "isize"] @@ -53,6 +51,9 @@ f64 = [] bool = [] +# deprecated since 1.1 +json_array = ["serde_json"] + [badges] travis-ci = { repository = "icetemple/itconfig-rs" } diff --git a/itconfig/src/envstr.rs b/itconfig/src/envstr.rs index 8da5307..efc7838 100644 --- a/itconfig/src/envstr.rs +++ b/itconfig/src/envstr.rs @@ -1,5 +1,30 @@ use std::ops::Deref; +/// 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 From for EnvString +where + T: ToEnvString, +{ + fn from(val: T) -> Self { + val.to_env_string() + } +} + +impl Deref for EnvString { + type Target = String; + + fn deref(&self) -> &Self::Target { + &self.0 + } +} + /// A trait for converting value to EnvString. /// /// This trait automatically implemented for any type which implements the @@ -94,15 +119,40 @@ impl FromEnvString for bool { } } -#[doc(hidden)] -#[cfg(feature = "array")] +impl FromEnvString for String { + type Err = (); + + fn from_env_string(s: &EnvString) -> Result { + Ok(s.0.clone()) + } +} + +impl FromEnvString for &'static str { + type Err = (); + + fn from_env_string(s: &EnvString) -> Result { + Ok(Box::leak(s.0.clone().into_boxed_str())) + } +} + +//===========================================================================// +// DEPRECATED // +//===========================================================================// + +/// Error type for json array implementation +#[cfg(feature = "json_array")] #[derive(Debug)] +#[deprecated(since = "1.1.0")] pub enum ArrayEnvError { + /// Invalid type. InvalidType, + + /// Failed to parse environment variable FailedToParse, } -#[cfg(feature = "array")] +#[cfg(feature = "json_array")] +#[allow(deprecated)] impl FromEnvString for Vec where T: FromEnvString, @@ -124,44 +174,3 @@ where }) } } - -impl FromEnvString for String { - type Err = (); - - fn from_env_string(s: &EnvString) -> Result { - Ok(s.0.clone()) - } -} - -impl FromEnvString for &'static str { - type Err = (); - - fn from_env_string(s: &EnvString) -> Result { - Ok(Box::leak(s.0.clone().into_boxed_str())) - } -} - -/// 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 From for EnvString -where - T: ToEnvString, -{ - fn from(val: T) -> Self { - val.to_env_string() - } -} - -impl Deref for EnvString { - type Target = String; - - fn deref(&self) -> &Self::Target { - &self.0 - } -} diff --git a/itconfig/src/lib.rs b/itconfig/src/lib.rs index 32a2bb8..2ca2655 100644 --- a/itconfig/src/lib.rs +++ b/itconfig/src/lib.rs @@ -113,7 +113,6 @@ //! //! * **default** - ["primitives"] //! * **macro** - Activates `config!` macros for easy configure web application. -//! * **array** - Add EnvString impl for vector type (uses optional `serde_json` package). //! * **primitives** - Group for features: `numbers` and `bool`. //! * **numbers** - Group for features: `int`, `uint` and `float`. //! * **int** - Group for features: `i8`, `i16`, `i32`, `i64`, `i128` and `isize`. @@ -134,6 +133,7 @@ //! * **f32** - impl EnvString for `f32` type //! * **f64** - impl EnvString for `f64` type //! * **bool** - impl EnvString for `bool` type +//! * **json_array** - Add EnvString impl for vector type (uses optional `serde_json` package). ⚠ **_DEPRECATED_** //! // Rustc lints.