Public color API

[KodrAus]

Closes #45 and #42

Some thoughts

• Do we want to treat new environment variables as breaking changes? Users overriding environment variables would probably want to know when new ones are added so they can be overridden too
• Should Env be an &mut self builder like the others?
• Should Style implement Write so you can call writeln!(read_style, "{}", record.args()) to write an entire line using styles?

Refactorings

I've moved all the terminal writing related code, like Target and the new WriteStyle into the fmt module to try and encapsulate it a bit better. Now we don't depend on termcolor directly in the Logger or Builder.

Disabling colors

Adds a new builder property for whether or not to include colors. By default this is RUST_LOG_STYLE, but it can be overridden.

Setting this environment variable to never will disable colors and other styles:

$ export RUST_LOG_STYLE=never
$ ./my-app

Valid values are:

• auto (or missing/invalid) will decide whether or not the terminal supports colors
• always will always use colors
• never will never use colors

In order to support multiple environment variables, I've refactored our from_env functions to accept a generic T: Into<Env>, where Env is a container for the environment variables we care about. These methods can now be called in a few ways:

// reads filters from `MY_LOG` and styles from `RUST_LOG_STYLE`
env_logger::init_from_env("MY_LOG");

// reads filters from `MY_LOG` and styles from `MY_LOG_STYLE`
env_logger::init_from_env(Env::default().filter("MY_LOG").write_style("MY_LOG_STYLE"));

This lets us add new environment variables in the future without potentially breaking people. But it does mean if you're overriding all environment variables that new ones could slip in without you noticing.

Using alternative environment variables

Since we use two environment variables to configure the logger we need an ergonomic way to pass different combinations of those variables to from_env methods. This PR adds an Env type with builder methods for naming environment variables:

env_logger::init_from_env(Env::new().filter("MY_LOG"));

With a few From conversions, the above is also equivalent to:

env_logger::init_from_env("MY_LOG");

Whether or not we want to keep these conversions is up for discussion.

Writing colors

The color API has been refactored so it's a bit nicer to use in your own formats:

let mut style = buf.style();

style.set_color(Color::Red).set_bold(true).set_bg(Color::White);

writeln!(buf, "{}", style.value(42))

This saves you from having to split the writes into multiple calls and juggle Result types.

Writing timestamps

Oh the Formatter.timestamp method is now also public so you can grab timestamps.

[KodrAus]

Needs some more work to smooth out the rough edges.

[KodrAus]

Repeating this check is a bit nasty. I think we should add methods to Env to get an Option for each variable

[KodrAus]

This is problematic because multiple loggers working on the same thread with different configurations will get unexpected results. The problem is the same with the Buffer, since it's tied to the Logger.

I'm thinking we just prevent you building a Logger directly and require it's configured globally, but am open to other suggestions.

[KodrAus]

Looks like we could handle the colors better by using termcolor's ColorChoice enum better. That way we won't need to thread the extra state around.

[KodrAus]

We should align the values of RUST_LOG_STYLE with Cargo's --color inputs.

[KodrAus]

I've done some refactoring so all the code around writing to the terminal is contained in the fmt module. This means the root Logger and Builder are mostly delegating to the filter and fmt modules to work.

I think this will make the library easier to navigate and use in the future since things are getting more complex in env_logger.

[KodrAus]

This value is wrong. It should be auto, always or never.

[KodrAus]

Same as other style examples.

[KodrAus]

Same as other style examples.

[KodrAus]

Even though these are private right now we should add some docs to them.