aboutsummaryrefslogtreecommitdiff
path: root/src/lib.rs
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib.rs')
-rw-r--r--src/lib.rs168
1 files changed, 114 insertions, 54 deletions
diff --git a/src/lib.rs b/src/lib.rs
index 4151836..4fa4055 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -15,20 +15,16 @@
//! ## Example
//!
//! ```
-//! #[macro_use] extern crate log;
+//! use log::{debug, error, log_enabled, info, Level};
//!
-//! use log::Level;
+//! env_logger::init();
//!
-//! fn main() {
-//! env_logger::init();
+//! debug!("this is a debug {}", "message");
+//! error!("this is printed by default");
//!
-//! debug!("this is a debug {}", "message");
-//! error!("this is printed by default");
-//!
-//! if log_enabled!(Level::Info) {
-//! let x = 3 * 4; // expensive computation
-//! info!("the answer was: {}", x);
-//! }
+//! if log_enabled!(Level::Info) {
+//! let x = 3 * 4; // expensive computation
+//! info!("the answer was: {}", x);
//! }
//! ```
//!
@@ -146,7 +142,6 @@
//!
//! ```
//! # #[macro_use] extern crate log;
-//! # fn main() {}
//! #[cfg(test)]
//! mod tests {
//! fn init() {
@@ -225,7 +220,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/
@@ -237,7 +232,7 @@
#![doc(
html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
html_favicon_url = "https://www.rust-lang.org/static/images/favicon.ico",
- html_root_url = "https://docs.rs/env_logger/0.7.1"
+ html_root_url = "https://docs.rs/env_logger/0.8.1"
)]
#![cfg_attr(test, deny(warnings))]
// When compiled for the rustc compiler itself we want to make sure that this is
@@ -257,13 +252,13 @@ pub use self::fmt::glob::*;
use self::filter::Filter;
use self::fmt::writer::{self, Writer};
-use self::fmt::Formatter;
+use self::fmt::{FormatFn, Formatter};
/// The default name for the environment variable to read filters from.
-pub const DEFAULT_FILTER_ENV: &'static str = "RUST_LOG";
+pub const DEFAULT_FILTER_ENV: &str = "RUST_LOG";
/// The default name for the environment variable to read style preferences from.
-pub const DEFAULT_WRITE_STYLE_ENV: &'static str = "RUST_LOG_STYLE";
+pub const DEFAULT_WRITE_STYLE_ENV: &str = "RUST_LOG_STYLE";
/// Set of environment variables to configure from.
///
@@ -309,8 +304,7 @@ struct Var<'a> {
pub struct Logger {
writer: Writer,
filter: Filter,
- #[allow(unknown_lints, bare_trait_objects)]
- format: Box<Fn(&mut Formatter, &Record) -> io::Result<()> + Sync + Send>,
+ format: FormatFn,
}
/// `Builder` acts as builder for initializing a `Logger`.
@@ -321,23 +315,20 @@ pub struct Logger {
/// # Examples
///
/// ```
-/// #[macro_use] extern crate log;
-///
-/// use std::env;
-/// use std::io::Write;
-/// use log::LevelFilter;
+/// # #[macro_use] extern crate log;
+/// # use std::io::Write;
/// use env_logger::Builder;
+/// use log::LevelFilter;
///
-/// fn main() {
-/// let mut builder = Builder::from_default_env();
+/// let mut builder = Builder::from_default_env();
///
-/// builder.format(|buf, record| writeln!(buf, "{} - {}", record.level(), record.args()))
-/// .filter(None, LevelFilter::Info)
-/// .init();
+/// builder
+/// .format(|buf, record| writeln!(buf, "{} - {}", record.level(), record.args()))
+/// .filter(None, LevelFilter::Info)
+/// .init();
///
-/// error!("error message");
-/// info!("info message");
-/// }
+/// error!("error message");
+/// info!("info message");
/// ```
#[derive(Default)]
pub struct Builder {
@@ -359,16 +350,15 @@ impl Builder {
/// Create a new builder and configure filters and style:
///
/// ```
- /// # fn main() {
/// use log::LevelFilter;
/// use env_logger::{Builder, WriteStyle};
///
/// let mut builder = Builder::new();
///
- /// builder.filter(None, LevelFilter::Info)
- /// .write_style(WriteStyle::Always)
- /// .init();
- /// # }
+ /// builder
+ /// .filter(None, LevelFilter::Info)
+ /// .write_style(WriteStyle::Always)
+ /// .init();
/// ```
///
/// [`filter`]: #method.filter
@@ -412,17 +402,61 @@ impl Builder {
E: Into<Env<'a>>,
{
let mut builder = Builder::new();
+ builder.parse_env(env);
+ builder
+ }
+
+ /// Applies the configuration from the environment.
+ ///
+ /// This function allows a builder to be configured with default parameters,
+ /// to be then overridden by the environment.
+ ///
+ /// # Examples
+ ///
+ /// Initialise a logger with filter level `Off`, then override the log
+ /// filter from an environment variable called `MY_LOG`:
+ ///
+ /// ```
+ /// use log::LevelFilter;
+ /// use env_logger::Builder;
+ ///
+ /// let mut builder = Builder::new();
+ ///
+ /// builder.filter_level(LevelFilter::Off);
+ /// builder.parse_env("MY_LOG");
+ /// builder.init();
+ /// ```
+ ///
+ /// Initialise a logger with filter level `Off`, then use the `MY_LOG`
+ /// variable to override filtering and `MY_LOG_STYLE` to override whether
+ /// or not to write styles:
+ ///
+ /// ```
+ /// use log::LevelFilter;
+ /// use env_logger::{Builder, Env};
+ ///
+ /// let env = Env::new().filter("MY_LOG").write_style("MY_LOG_STYLE");
+ ///
+ /// let mut builder = Builder::new();
+ /// builder.filter_level(LevelFilter::Off);
+ /// builder.parse_env(env);
+ /// builder.init();
+ /// ```
+ pub fn parse_env<'a, E>(&mut self, env: E) -> &mut Self
+ where
+ E: Into<Env<'a>>,
+ {
let env = env.into();
if let Some(s) = env.get_filter() {
- builder.parse_filters(&s);
+ self.parse_filters(&s);
}
if let Some(s) = env.get_write_style() {
- builder.parse_write_style(&s);
+ self.parse_write_style(&s);
}
- builder
+ self
}
/// Initializes the log builder from the environment using default variable names.
@@ -447,6 +481,32 @@ impl Builder {
Self::from_env(Env::default())
}
+ /// Applies the configuration from the environment using default variable names.
+ ///
+ /// This method is a convenient way to call `parse_env(Env::default())` without
+ /// having to use the `Env` type explicitly. The builder will use the
+ /// [default environment variables].
+ ///
+ /// # Examples
+ ///
+ /// Initialise a logger with filter level `Off`, then configure it using the
+ /// default environment variables:
+ ///
+ /// ```
+ /// use log::LevelFilter;
+ /// use env_logger::Builder;
+ ///
+ /// let mut builder = Builder::new();
+ /// builder.filter_level(LevelFilter::Off);
+ /// builder.parse_default_env();
+ /// builder.init();
+ /// ```
+ ///
+ /// [default environment variables]: struct.Env.html#default-environment-variables
+ pub fn parse_default_env(&mut self) -> &mut Self {
+ self.parse_env(Env::default())
+ }
+
/// Sets the format function for formatting the log output.
///
/// This function is called on each record logged and should format the
@@ -538,17 +598,15 @@ impl Builder {
///
/// # Examples
///
- /// Only include messages for warning and above for logs in `path::to::module`:
+ /// Only include messages for info and above for logs in `path::to::module`:
///
/// ```
- /// # fn main() {
- /// use log::LevelFilter;
/// use env_logger::Builder;
+ /// use log::LevelFilter;
///
/// let mut builder = Builder::new();
///
/// builder.filter_module("path::to::module", LevelFilter::Info);
- /// # }
/// ```
pub fn filter_module(&mut self, module: &str, level: LevelFilter) -> &mut Self {
self.filter.filter_module(module, level);
@@ -559,17 +617,15 @@ impl Builder {
///
/// # Examples
///
- /// Only include messages for warning and above for logs in `path::to::module`:
+ /// Only include messages for info and above for logs in `path::to::module`:
///
/// ```
- /// # fn main() {
- /// use log::LevelFilter;
/// use env_logger::Builder;
+ /// use log::LevelFilter;
///
/// let mut builder = Builder::new();
///
/// builder.filter_level(LevelFilter::Info);
- /// # }
/// ```
pub fn filter_level(&mut self, level: LevelFilter) -> &mut Self {
self.filter.filter_level(level);
@@ -583,17 +639,15 @@ impl Builder {
///
/// # Examples
///
- /// Only include messages for warning and above for logs in `path::to::module`:
+ /// Only include messages for info and above for logs in `path::to::module`:
///
/// ```
- /// # fn main() {
- /// use log::LevelFilter;
/// use env_logger::Builder;
+ /// use log::LevelFilter;
///
/// let mut builder = Builder::new();
///
/// builder.filter(Some("path::to::module"), LevelFilter::Info);
- /// # }
/// ```
pub fn filter(&mut self, module: Option<&str>, level: LevelFilter) -> &mut Self {
self.filter.filter(module, level);
@@ -1054,7 +1108,6 @@ pub fn init() {
/// and `MY_LOG_STYLE` for writing colors:
///
/// ```
-/// # extern crate env_logger;
/// use env_logger::{Builder, Env};
///
/// # fn run() -> Result<(), Box<::std::error::Error>> {
@@ -1064,7 +1117,7 @@ pub fn init() {
///
/// Ok(())
/// # }
-/// # fn main() { run().unwrap(); }
+/// # run().unwrap();
/// ```
///
/// # Errors
@@ -1114,6 +1167,9 @@ 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()
}
@@ -1121,6 +1177,10 @@ pub fn builder() -> Builder {
/// Create a builder from the given environment variables.
///
/// The builder can be configured before being initialized.
+#[deprecated(
+ since = "0.8.0",
+ note = "Prefer `env_logger::Builder::from_env()` instead."
+)]
pub fn from_env<'a, E>(env: E) -> Builder
where
E: Into<Env<'a>>,
generated by cgit v1.2.3 (git 2.25.1) at 2024-07-02 23:33:24 +0000