Expose colored string (#73)

* increased documentation

* format using rustfmt

examples/control.rs

@@ -14,17 +14,29 @@ fn main() {
     colored::control::set_virtual_terminal(true);
     println!("{}", "stdout: Virtual Terminal is in use".bright_green());
     colored::control::set_virtual_terminal(false);
-    println!("{}", "stderr: Virtual Terminal is NOT in use, escape chars should be visible".bright_red());
+    println!(
+        "{}",
+        "stderr: Virtual Terminal is NOT in use, escape chars should be visible".bright_red()
+    );
     colored::control::set_virtual_terminal(true);
-    println!("{}", "stdout: Virtual Terminal is in use AGAIN and should be green!".bright_green());
+    println!(
+        "{}",
+        "stdout: Virtual Terminal is in use AGAIN and should be green!".bright_green()
+    );
     colored::control::set_virtual_terminal(true);
 
     // again with stderr
     eprintln!("{}", "stderr: Virtual Terminal is in use".bright_green());
     colored::control::set_virtual_terminal(false);
-    eprintln!("{}", "stderr: Virtual Terminal is NOT in use, escape chars should be visible".bright_red());
+    eprintln!(
+        "{}",
+        "stderr: Virtual Terminal is NOT in use, escape chars should be visible".bright_red()
+    );
     colored::control::set_virtual_terminal(true);
-    eprintln!("{}", "stderr: Virtual Terminal is in use AGAIN and should be green!".bright_green());
+    eprintln!(
+        "{}",
+        "stderr: Virtual Terminal is in use AGAIN and should be green!".bright_green()
+    );
 }
 
 fn both() {

src/color.rs

@@ -3,6 +3,7 @@ use std::str::FromStr;
 
 /// The 8 standard colors.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
+#[allow(missing_docs)]
 pub enum Color {
     Black,
     Red,
@@ -21,6 +22,8 @@ pub enum Color {
     BrightCyan,
     BrightWhite,
 }
+
+#[allow(missing_docs)]
 impl Color {
     pub fn to_fg_str(&self) -> &str {
         match *self {
@@ -206,6 +209,5 @@ mod tests {
             let color: Result<Color, ()> = "bloublou".parse();
             assert_eq!(Err(()), color)
         }
-
     }
 }

src/control.rs

@@ -33,28 +33,34 @@ pub fn set_virtual_terminal(use_virtual: bool) -> Result<(), ()> {
             processenv::GetStdHandle,
             winbase::STD_OUTPUT_HANDLE,
             wincon::ENABLE_VIRTUAL_TERMINAL_PROCESSING,
-        }
+        },
     };
 
     unsafe {
         let handle = GetStdHandle(STD_OUTPUT_HANDLE);
         let mut original_mode: DWORD = 0;
         GetConsoleMode(handle, &mut original_mode);
 
-        let enabled = original_mode & ENABLE_VIRTUAL_TERMINAL_PROCESSING == ENABLE_VIRTUAL_TERMINAL_PROCESSING;
+        let enabled = original_mode & ENABLE_VIRTUAL_TERMINAL_PROCESSING
+            == ENABLE_VIRTUAL_TERMINAL_PROCESSING;
 
         match (use_virtual, enabled) {
             // not enabled, should be enabled
-            (true, false) => SetConsoleMode(handle, ENABLE_VIRTUAL_TERMINAL_PROCESSING | original_mode),
+            (true, false) => {
+                SetConsoleMode(handle, ENABLE_VIRTUAL_TERMINAL_PROCESSING | original_mode)
+            }
             // already enabled, should be disabled
-            (false, true) => SetConsoleMode(handle, ENABLE_VIRTUAL_TERMINAL_PROCESSING ^ original_mode),
+            (false, true) => {
+                SetConsoleMode(handle, ENABLE_VIRTUAL_TERMINAL_PROCESSING ^ original_mode)
+            }
             _ => 0,
         };
     }
 
     Ok(())
 }
 
+/// A flag to to if coloring should occur.
 pub struct ShouldColorize {
     clicolor: bool,
     clicolor_force: Option<bool>,
@@ -76,6 +82,7 @@ pub fn unset_override() {
 }
 
 lazy_static! {
+/// The persistent [`ShouldColorize`].
     pub static ref SHOULD_COLORIZE: ShouldColorize = ShouldColorize::from_env();
 }
 
@@ -96,8 +103,6 @@ impl ShouldColorize {
     /// `CLICOLOR_FORCE` takes highest priority, followed by `NO_COLOR`,
     /// followed by `CLICOLOR` combined with tty check.
     pub fn from_env() -> Self {
-        use std::io;
-
         ShouldColorize {
             clicolor: ShouldColorize::normalize_env(env::var("CLICOLOR")).unwrap_or_else(|| true)
                 && atty::is(atty::Stream::Stdout),
@@ -109,6 +114,7 @@ impl ShouldColorize {
         }
     }
 
+    /// Returns if the current coloring is expected.
     pub fn should_colorize(&self) -> bool {
         if self.has_manual_override.load(Ordering::Relaxed) {
             return self.manual_override.load(Ordering::Relaxed);
@@ -121,12 +127,14 @@ impl ShouldColorize {
         self.clicolor
     }
 
+    /// Use this to force colored to ignore the environment and always/never colorize
     pub fn set_override(&self, override_colorize: bool) {
         self.has_manual_override.store(true, Ordering::Relaxed);
         self.manual_override
             .store(override_colorize, Ordering::Relaxed);
     }
 
+    /// Remove the manual override and let the environment decide if it's ok to colorize
     pub fn unset_override(&self) {
         self.has_manual_override.store(false, Ordering::Relaxed);
     }