0.6.7 Minor improvements

- improve docu for usage of reconfigure capability
- remove own macro print_err! in favor of new standard macro eprintln!

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "flexi_logger"
-version = "0.6.6"
+version = "0.6.7"
 authors = ["emabee <meinolf.block@sap.com>"]
 description = "A flexible and reconfigurable logger that can write to stderr or to log files"
 keywords = ["file", "logger"]

src/flexi_logger.rs

@@ -217,7 +217,7 @@ impl log::Log for FlexiLogger {
 
             flexi_writer.write(msgb, &self.config);
         } else {
-            let _ = writeln!(&mut io::stderr(), "{}", msg);
+            eprintln!("{}", msg);
         }
     }
 }

src/flexi_writer.rs

@@ -89,7 +89,7 @@ impl FlexiWriter {
         if let Some(ref mut lw) = self.o_flw {
             lw.write(msgb)
               .unwrap_or_else(|e| {
-                  print_err!("Flexi logger: write access to file failed with {}", e);
+                  eprintln!("Flexi logger: write access to file failed with {}", e);
                   0
               });
             if self.use_rotating {
@@ -161,13 +161,13 @@ fn get_next_rotate_idx(s_filename_base: &String, o_suffix: &Option<String>) -> u
     let fn_pattern = get_filename_pattern(s_filename_base, o_suffix);
     match glob(&fn_pattern) {
         Err(e) => {
-            print_err!("Is this ({}) really a directory? Listing failed with {}", fn_pattern, e);
+            eprintln!("Is this ({}) really a directory? Listing failed with {}", fn_pattern, e);
         }
         Ok(globresults) => {
             for globresult in globresults {
                 match globresult {
                     Err(e) => {
-                        print_err!("Error occured when reading directory for log files: {:?}", e)
+                        eprintln!("Error occured when reading directory for log files: {:?}", e)
                     }
                     Ok(pathbuf) => {
                         let filename = pathbuf.file_stem().unwrap().to_string_lossy();

src/lib.rs

@@ -1,7 +1,7 @@
 #![warn(missing_docs)]
 
-//! A logger that can write the log to standard error or to a fresh file in a configurable folder
-//! and allows custom logline formats.
+//! A logger that can write the log to standard error or to a fresh file in a configurable folder,
+//! and allows custom logline formats, and whose log specification can be changed at runtime.
 //!
 //! It had started as an extended copy of [env_logger](http://crates.io/crates/env_logger/).
 //!
@@ -52,19 +52,6 @@ extern crate glob;
 extern crate log;
 extern crate regex;
 
-macro_rules! print_err {
-    ($($arg:tt)*) => (
-        {
-            use std::io::prelude::*;
-            if let Err(e) = write!(&mut ::std::io::stderr(), "{}\n", format_args!($($arg)*)) {
-                panic!("Failed to write to stderr.\
-                    \nOriginal error output: {}\
-                    \nSecondary error writing to stderr: {}", format!($($arg)*), e);
-            }
-        }
-    )
-}
-
 mod deprecated;
 mod flexi_error;
 mod flexi_logger;

src/log_specification.rs

@@ -7,7 +7,9 @@ use std::collections::HashMap;
 /// Immutable struct that defines which loglines are to be written,
 /// based on the module, the log level, and the text.
 ///
-/// The loglevel specification via string (relevant for methods parse() and env())
+/// The loglevel specification via string (relevant for methods
+/// [parse()](struct.LogSpecification.html#method.parse) and
+/// [env()](struct.LogSpecification.html#method.env))
 /// works essentially like with env_logger,
 /// but we are a bit more tolerant with spaces. Its functionality can be
 /// described with some Backus-Naur-form:
@@ -18,14 +20,21 @@ use std::collections::HashMap;
 /// <text_filter> ::= <regex>
 /// ```
 ///
+/// * Examples:
+///
+///  * ```"info"```: all logs with info, warn, or error level are written
+///  * ```"crate1"```: all logs of this crate are written, but nothing else
+///  * ```"warn, crate2::mod_a=debug, mod_x::mod_y=trace"```: all crates log warnings and erors, mod_a additional debug messages, and
+///    mod_x::mod_y is fully traced
+///
 /// * If you just specify the module, without log_level, all levels will be traced for this module.
 /// * If you just specify a log level, this will be applied as default to all modules without
 ///   explicit log level assigment.
 ///   (You see that for modules named error, warn, info, debug or trace,
 ///   it is necessary to specify their loglevel explicit).
 /// * The module names are compared as Strings, with the side effect that a specified module filter
 ///   affects all modules whose name starts with this String.<br>
-///   Example: "foo" affects e.g.
+///   Example: ```"foo"``` affects e.g.
 ///
 ///   * foo
 ///   * foo::bar
@@ -34,16 +43,16 @@ use std::collections::HashMap;
 ///
 /// The optional text filter is applied for all modules.
 ///
-/// Note that external module names are to be specified like in "extern crate ...".
-/// For crates with a dash in their name this means: the dash is to be replaced with
-/// the underscore (e.g. karl_heinz, not karl-heinz).
+/// Note that external module names are to be specified like in ```"extern crate ..."```, i.e.,
+/// for crates with a dash in their name this means: the dash is to be replaced with
+/// the underscore (e.g. ```karl_heinz```, not ```karl-heinz```).
 #[derive(Clone,Debug)]
 pub struct LogSpecification {
     module_filters: Vec<ModuleFilter>,
     textfilter: Option<Regex>,
 }
 
-/// Defines which loglevel filter to use for a given module (or as default, if no module is given)
+/// Defines which loglevel filter to use for a given module (or as default, if no module is given).
 #[derive(Clone,Debug)]
 pub struct ModuleFilter {
     pub module_name: Option<String>,
@@ -57,8 +66,7 @@ impl LogSpecification {
         self.textfilter = other_spec.textfilter;
     }
 
-    /// Returns a log specification from a String
-    /// (e.g: "crate1, crate2::mod_a, crate3::mod_x = error /foo").
+    /// Returns a log specification from a String.
     pub fn parse(spec: &str) -> LogSpecification {
         let mut dirs = Vec::<ModuleFilter>::new();
 

src/logger.rs

@@ -11,7 +11,7 @@ pub type FormatFunction = fn(&LogRecord) -> String;
 
 /// The standard entry-point for using flexi_logger.
 ///
-/// Create a Logger with your desired loglevel-specification
+/// Create a Logger with your desired (initial) loglevel-specification
 ///
 /// * by specifying a String programmatically,
 ///   using [Logger::with_str()](struct.Logger.html#method.with_str),
@@ -20,7 +20,8 @@ pub type FormatFunction = fn(&LogRecord) -> String;
 /// * or by providing an explicitly built LogSpecification,
 ///   using [Logger::with()](struct.Logger.html#method.with),
 ///
-/// use its configuration methods, and finally call start().
+/// use its configuration methods, and finally call [start()](struct.Logger.html#method.start)
+/// (or [start_reconfigurable()](struct.Logger.html#method.start_reconfigurable)).
 ///
 /// ## Examples
 ///
@@ -67,6 +68,7 @@ impl Logger {
     }
 
     /// Create a Logger that reads the LogSpecification from a String or &str.
+    /// [See LogSpecification](struct.LogSpecification.html) for the syntax.
     pub fn with_str<S: AsRef<str>>(s: S) -> Logger {
         let logspec = LogSpecification::parse(s.as_ref());
         Logger {