Merge pull request #168 from KodrAus/chore/build-fn-cleanup

Deprecate env_logger::from_env and clean up examples

examples/custom_default_format.rs

@@ -27,11 +27,10 @@ fn init_logger() {
         .filter("MY_LOG_LEVEL")
         .write_style("MY_LOG_STYLE");
 
-    let mut builder = Builder::from_env(env);
-
-    builder.format_level(false).format_timestamp_nanos();
-
-    builder.init();
+    Builder::from_env(env)
+        .format_level(false)
+        .format_timestamp_nanos()
+        .init();
 }
 
 fn main() {

examples/custom_format.rs

@@ -19,7 +19,8 @@ If you want to control the logging output completely, see the `custom_logger` ex
 
 #[cfg(all(feature = "termcolor", feature = "humantime"))]
 fn main() {
-    use env_logger::{fmt, Builder, Env};
+    use env_logger::{fmt::Color, Builder, Env};
+
     use std::io::Write;
 
     fn init_logger() {
@@ -30,7 +31,7 @@ fn main() {
         Builder::from_env(env)
             .format(|buf, record| {
                 let mut style = buf.style();
-                style.set_bg(fmt::Color::Yellow).set_bold(true);
+                style.set_bg(Color::Yellow).set_bold(true);
 
                 let timestamp = buf.timestamp();
 

examples/custom_logger.rs

@@ -13,17 +13,19 @@ If you only want to change the way logs are formatted, look at the `custom_forma
 #[macro_use]
 extern crate log;
 
-use env_logger::filter::Filter;
+use env_logger::filter::{Builder, Filter};
+
 use log::{Log, Metadata, Record, SetLoggerError};
 
+const FILTER_ENV: &'static str = "MY_LOG_LEVEL";
+
 struct MyLogger {
     inner: Filter,
 }
 
 impl MyLogger {
     fn new() -> MyLogger {
-        use env_logger::filter::Builder;
-        let mut builder = Builder::from_env("MY_LOG_LEVEL");
+        let mut builder = Builder::from_env(FILTER_ENV);
 
         MyLogger {
             inner: builder.build(),

examples/direct_logger.rs

@@ -4,13 +4,17 @@ Using `env_logger::Logger` and the `log::Log` trait directly.
 This example doesn't rely on environment variables, or having a static logger installed.
 */
 
-fn record() -> log::Record<'static> {
-    let error_metadata = log::MetadataBuilder::new()
+use env_logger::{Builder, WriteStyle};
+
+use log::{Level, LevelFilter, Log, MetadataBuilder, Record};
+
+fn record() -> Record<'static> {
+    let error_metadata = MetadataBuilder::new()
         .target("myApp")
-        .level(log::Level::Error)
+        .level(Level::Error)
         .build();
 
-    log::Record::builder()
+    Record::builder()
         .metadata(error_metadata)
         .args(format_args!("Error!"))
         .line(Some(433))
@@ -20,16 +24,14 @@ fn record() -> log::Record<'static> {
 }
 
 fn main() {
-    use log::Log;
-
-    let stylish_logger = env_logger::Builder::new()
-        .filter(None, log::LevelFilter::Error)
-        .write_style(env_logger::WriteStyle::Always)
+    let stylish_logger = Builder::new()
+        .filter(None, LevelFilter::Error)
+        .write_style(WriteStyle::Always)
         .build();
 
-    let unstylish_logger = env_logger::Builder::new()
-        .filter(None, log::LevelFilter::Error)
-        .write_style(env_logger::WriteStyle::Never)
+    let unstylish_logger = Builder::new()
+        .filter(None, LevelFilter::Error)
+        .write_style(WriteStyle::Never)
         .build();
 
     stylish_logger.log(&record());

examples/filters_from_code.rs

@@ -5,10 +5,12 @@ Specify logging filters in code instead of using an environment variable.
 #[macro_use]
 extern crate log;
 
+use env_logger::Builder;
+
+use log::LevelFilter;
+
 fn main() {
-    env_logger::builder()
-        .filter_level(log::LevelFilter::Trace)
-        .init();
+    Builder::new().filter_level(LevelFilter::max()).init();
 
     trace!("some trace log");
     debug!("some debug log");

examples/in_tests.rs

@@ -0,0 +1,54 @@
+/*!
+Using `env_logger` in tests.
+
+Log events will be captured by `cargo` and only printed if the test fails.
+You can run this example by calling:
+
+```text
+cargo test --example in_tests
+```
+
+You should see the `it_does_not_work` test fail and include its log output.
+*/
+
+#[cfg_attr(test, macro_use)]
+extern crate log;
+
+fn main() {}
+
+#[cfg(test)]
+mod tests {
+    fn init_logger() {
+        let _ = env_logger::builder()
+            // Include all events in tests
+            .filter_level(log::LevelFilter::max())
+            // Ensure events are captured by `cargo test`
+            .is_test(true)
+            // Ignore errors initializing the logger if tests race to configure it
+            .try_init();
+    }
+
+    #[test]
+    fn it_works() {
+        init_logger();
+
+        let a = 1;
+        let b = 2;
+
+        debug!("checking whether {} + {} = 3", a, b);
+
+        assert_eq!(3, a + b);
+    }
+
+    #[test]
+    fn it_does_not_work() {
+        init_logger();
+
+        let a = 1;
+        let b = 2;
+
+        debug!("checking whether {} + {} = 6", a, b);
+
+        assert_eq!(6, a + b);
+    }
+}

src/lib.rs

@@ -225,7 +225,7 @@
 //! ```
 //! use env_logger::Env;
 //!
-//! env_logger::from_env(Env::default().default_filter_or("warn")).init();
+//! env_logger::Builder::from_env(Env::default().default_filter_or("warn")).init();
 //! ```
 //!
 //! [log-crate-url]: https://docs.rs/log/
@@ -1185,13 +1185,20 @@ where
 /// Create a new builder with the default environment variables.
 ///
 /// The builder can be configured before being initialized.
+/// This is a convenient way of calling [`Builder::from_default_env`].
+///
+/// [`Builder::from_default_env`]: struct.Builder.html#method.from_default_env
 pub fn builder() -> Builder {
     Builder::from_default_env()
 }
 
 /// Create a builder from the given environment variables.
 ///
 /// The builder can be configured before being initialized.
+#[deprecated(
+    since = "0.7.2",
+    note = "Prefer `env_logger::Builder::from_env()` instead."
+)]
 pub fn from_env<'a, E>(env: E) -> Builder
 where
     E: Into<Env<'a>>,