Add and Expose Methods of easily Creating and Mutating ColoredString's and Style's for Users

CHANGELOG.md

@@ -1,5 +1,26 @@
 # Unreleased
 
+- Updated top-level docs to include a note about `ColoredString`\'s role in the `Colorize` pipeline as well as link to it to suggest learning more about how to manipulate existing `ColoredString`\'s.
+- Changes to `ColoredString`:
+  - Expose fields.
+  - **[DEPRECATION]:** Deprecated methods `fgcolor`, `bgcolor`, and `style` due to their obsolescence in the face of the exposing of their represented fields.
+  - Add methods for clearing specific elements of `fgcolor`, `bgcolor`, and `style`.
+  - Change Default implementation to be via derive as Style now implements Default (see changes to Style below).
+  - Add implementation of `DerefMut`.
+  - Updated docs to reflect the above changes as well as generally greatly expand them.
+- Changes to `Style`:
+  - Implemented `Default` for `Style` (returns `CLEAR`). This exposes a method by which users can create plain `Style`\'s from scratch.
+  - Implemented `From<Styles>` for `Style`. This lets users easily create `Style`\'s from specific styles.
+  - Exposed previously private method `add`.
+  - Created method `remove` which essentially does the opposite.
+  - Added builder-style methods in the vein of `Colorize` to add stylings (e.g. `bold`, `underline`, `italic`, `strikethrough`).
+  - Implemented bitwise operators `BitAnd`, `BitOr`, `BitXor`, and `Not` as well as their representative assignment operators. You can also use a `Styles` as an operand for these.
+  - Implemented `FromIterator<Styles>` for Style.
+- Changes to `Styles`:
+  - Implemented bitwise operators `BitAnd`, `BitOr`, `BitXor`, and `Not` which all combine `Styles`\'s and output `Style`\'s. These can also take a `Style` as an operand.
+- Added additional testing for all of the above changes.
+- Added methods `with_style` and `with_color_and_style` to `Colorize`.
+
 # 2.0.4
 - Switch from `winapi` to `windows-sys`.
 

src/lib.rs

@@ -23,6 +23,10 @@
 //!
 //! See [the `Colorize` trait](./trait.Colorize.html) for all the methods.
 //!
+//! Note: The methods of [`Colorize`], when used on [`str`]'s, return
+//! [`ColoredString`]'s. See [`ColoredString`] to learn more about them and
+//! what you can do with them beyond continue to use [`Colorize`] to further
+//! modify them.
 #![warn(missing_docs)]
 
 extern crate is_terminal;
@@ -43,17 +47,93 @@ pub mod customcolors;
 
 pub use color::*;
 
-use std::{borrow::Cow, fmt, ops::Deref};
+use std::{
+    borrow::Cow,
+    fmt,
+    ops::{Deref, DerefMut},
+};
 
 pub use style::{Style, Styles};
 
 /// A string that may have color and/or style applied to it.
-#[derive(Clone, Debug, PartialEq, Eq)]
+///
+/// Commonly created via calling the methods of [`Colorize`] on a &str.
+/// All methods of [`Colorize`] either create a new `ColoredString` from
+/// the type called on or modify a callee `ColoredString`. See
+/// [`Colorize`] for more.
+///
+/// The primary usage of `ColoredString`'s is as a way to take text,
+/// apply colors and miscillaneous styling to it (such as bold or
+/// underline), and then use it to create formatted strings that print
+/// to the console with the special styling applied.
+///
+/// ## Usage
+///
+/// As stated, `ColoredString`'s, once created, can be printed to the
+/// console with their colors and style or turned into a string
+/// containing special console codes that has the same effect.
+/// This is made easy via `ColoredString`'s implementations of
+/// [`Display`](std::fmt::Display) and [`ToString`] for those purposes
+/// respectively.
+///
+/// Printing a `ColoredString` with its style is as easy as:
+///
+/// ```
+/// # use colored::*;
+/// let cstring: ColoredString = "Bold and Red!".bold().red();
+/// println!("{}", cstring);
+/// ```
+///
+/// ## Manipulating the coloring/style of a `ColoredString`
+///
+/// Getting or changing the foreground color, background color, and or
+/// style of a `ColoredString` is as easy as manually reading / modifying
+/// the fields of `ColoredString`.
+///
+/// ```
+/// # use colored::*;
+/// let mut red_text = "Red".red();
+/// // Changing color using re-assignment and [`Colorize`]:
+/// red_text = red_text.blue();
+/// // Manipulating fields of `ColoredString` in-place:
+/// red_text.fgcolor = Some(Color::Blue);
+///
+/// let styled_text1 = "Bold".bold();
+/// let styled_text2 = "Italic".italic();
+/// let mut styled_text3 = ColoredString::from("Bold and Italic");
+/// styled_text3.style = styled_text1.style | styled_text2.style;
+/// ```
+///
+/// ## Modifying the text of a `ColoredString`
+///
+/// Modifying the text is as easy as modifying the `input` field of
+/// `ColoredString`...
+///
+/// ```
+/// # use colored::*;
+/// let mut colored_text = "Magenta".magenta();
+/// colored_text = colored_text.blue();
+/// colored_text.input = "Blue".to_string();
+/// // Note: The above is inefficient and `colored_text.input.replace_range(.., "Blue")` would
+/// // be more proper. This is just for example.
+///
+/// assert_eq!(&*colored_text, "Blue");
+/// ```
+///
+/// Notice how this process preserves the coloring and style.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+#[non_exhaustive]
 pub struct ColoredString {
-    input: String,
-    fgcolor: Option<Color>,
-    bgcolor: Option<Color>,
-    style: style::Style,
+    /// The plain text that will have color and style applied to it.
+    pub input: String,
+    /// The color of the text as it will be printed.
+    pub fgcolor: Option<Color>,
+    /// The background color (if any). None means that the text will be printed
+    /// without a special background.
+    pub bgcolor: Option<Color>,
+    /// Any special styling to be applied to the text (see Styles for a list of
+    /// available options).
+    pub style: style::Style,
 }
 
 /// The trait that enables something to be given color.
@@ -327,6 +407,8 @@ pub trait Colorize {
     fn reversed(self) -> ColoredString;
     fn hidden(self) -> ColoredString;
     fn strikethrough(self) -> ColoredString;
+    fn with_style<S: Into<Style>>(self, style: S) -> ColoredString;
+    fn with_color_and_style(self, other: &ColoredString) -> ColoredString;
 }
 
 impl ColoredString {
@@ -339,6 +421,7 @@ impl ColoredString {
     /// let cstr = cstr.clear();
     /// assert_eq!(cstr.fgcolor(), None);
     /// ```
+    #[deprecated(note = "Deprecated due to the exposing of the fgcolor struct field.")]
     pub fn fgcolor(&self) -> Option<Color> {
         self.fgcolor.as_ref().copied()
     }
@@ -352,6 +435,7 @@ impl ColoredString {
     /// let cstr = cstr.clear();
     /// assert_eq!(cstr.bgcolor(), None);
     /// ```
+    #[deprecated(note = "Deprecated due to the exposing of the bgcolor struct field.")]
     pub fn bgcolor(&self) -> Option<Color> {
         self.bgcolor.as_ref().copied()
     }
@@ -365,10 +449,28 @@ impl ColoredString {
     /// assert_eq!(colored.style().contains(Styles::Italic), true);
     /// assert_eq!(colored.style().contains(Styles::Dimmed), false);
     /// ```
+    #[deprecated(note = "Deprecated due to the exposing of the style struct field.")]
     pub fn style(&self) -> style::Style {
         self.style
     }
 
+    /// Clears foreground coloring on this `ColoredString`, meaning that it
+    /// will be printed with the default terminal text color.
+    pub fn clear_fgcolor(&mut self) {
+        self.fgcolor = None;
+    }
+
+    /// Gets rid of this `ColoredString`'s background.
+    pub fn clear_bgcolor(&mut self) {
+        self.bgcolor = None;
+    }
+
+    /// Clears any special styling and sets it back to the default (plain,
+    /// maybe colored, text).
+    pub fn clear_style(&mut self) {
+        self.style = Style::default();
+    }
+
     /// Checks if the colored string has no color or styling.
     ///
     /// ```rust
@@ -461,24 +563,19 @@ impl ColoredString {
     }
 }
 
-impl Default for ColoredString {
-    fn default() -> Self {
-        ColoredString {
-            input: String::default(),
-            fgcolor: None,
-            bgcolor: None,
-            style: style::CLEAR,
-        }
-    }
-}
-
 impl Deref for ColoredString {
     type Target = str;
-    fn deref(&self) -> &str {
+    fn deref(&self) -> &Self::Target {
         &self.input
     }
 }
 
+impl DerefMut for ColoredString {
+    fn deref_mut(&mut self) -> &mut <Self as Deref>::Target {
+        &mut self.input
+    }
+}
+
 impl From<String> for ColoredString {
     fn from(s: String) -> Self {
         ColoredString {
@@ -506,6 +603,16 @@ impl Colorize for ColoredString {
         self.bgcolor = Some(color.into());
         self
     }
+    fn with_style<S: Into<Style>>(mut self, style: S) -> ColoredString {
+        self.style = style.into();
+        self
+    }
+    fn with_color_and_style(mut self, other: &ColoredString) -> ColoredString {
+        self.fgcolor = other.fgcolor;
+        self.bgcolor = other.bgcolor;
+        self.style = other.style;
+        self
+    }
 
     fn clear(self) -> ColoredString {
         ColoredString {
@@ -570,6 +677,23 @@ impl<'a> Colorize for &'a str {
         }
     }
 
+    fn with_style<S: Into<Style>>(self, style: S) -> ColoredString {
+        ColoredString {
+            input: self.to_string(),
+            style: style.into(),
+            ..Default::default()
+        }
+    }
+
+    fn with_color_and_style(self, other: &ColoredString) -> ColoredString {
+        ColoredString {
+            input: self.to_string(),
+            fgcolor: other.fgcolor,
+            bgcolor: other.bgcolor,
+            style: other.style,
+        }
+    }
+
     fn clear(self) -> ColoredString {
         ColoredString {
             input: String::from(self),
@@ -849,6 +973,8 @@ mod tests {
 
     #[test]
     fn exposing_tests() {
+        #![allow(deprecated)]
+
         let cstring = "".red();
         assert_eq!(cstring.fgcolor(), Some(Color::Red));
         assert_eq!(cstring.bgcolor(), None);