✨ Added styled module && Improved docs

Author: nwrenger

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "console-utils"
-version = "1.6.1"
+version = "1.7.0"
 edition = "2021"
 authors = ["Nils Wrenger <[email protected]>"]
 description = "Simple CLI Input and Control Utilities"
@@ -14,7 +14,7 @@ license = "MIT"
 [lib]
 
 [target.'cfg(unix)'.dependencies.libc]
-version = "0.2.169"
+version = "0.2.171"
 
 [target.'cfg(windows)'.dependencies.windows-sys]
 version = "0.59.0"

README.md

@@ -16,7 +16,7 @@ To use Console Utils in your Rust project, you can add the following dependency
 
 ```toml
 [dependencies]
-console-utils = "1.6.1"
+console-utils = "1.7.0"
 ```
 
 After adding the dependency, you can import the modules you need in your Rust code. For example:
@@ -68,6 +68,21 @@ let selected_indices = multiselect("Select options:", &options);
 println!("Selected indices: {:?}", selected_indices);
 ```
 
+### Text styling
+
+```rust
+use console_utils::styled::{StyledText, Color};
+
+let text = StyledText::new("Hello, world!")
+    .fg(Color::Red)
+    .bg(Color::Black)
+    .bold()
+    .underline();
+
+// Prints now a `Hello, world!` with red, bold and underlined text on a black background
+println!("{}", text);
+```
+
 ### Console Control
 
 ```rust
@@ -96,7 +111,7 @@ use console_utils::input::{spinner, SpinnerType};
 // Display a standard spinner for 3 seconds
 spinner(3.0, SpinnerType::Standard);
 // Display a custom spinner for 2 seconds
-spinner(2.0, SpinnerType::Custom(vec!["1", "2", "3", "4", "3", "2"]));
+spinner(2.0, SpinnerType::Custom(&["1", "2", "3", "4", "3", "2"]));
 ```
 
 ### Gradual String Reveal

src/input.rs

@@ -5,8 +5,9 @@
 use std::{io, str::FromStr, thread, time::Duration};
 
 use crate::{
-    control::*,
+    control::{clear_line, flush, move_cursor_down, move_cursor_up, Visibility},
     read::{read_key, Key},
+    styled::{Color, StyledText},
 };
 
 /// A Wrapper for empty inputs returning a None
@@ -51,15 +52,20 @@ where
     T::Err: std::fmt::Debug,
 {
     loop {
-        print!("\x1b[31m?\x1b[0m {before} \x1b[90m›\x1b[0m ");
+        let quest = StyledText::new("?").fg(Color::Red);
+        let caret = StyledText::new("›").fg(Color::BrightBlack);
+        print!("{quest} {before} {caret} ");
         flush();
 
         let mut cli = String::new();
         io::stdin().read_line(&mut cli).unwrap();
 
         match cli.parse() {
             Ok(value) => return value,
-            Err(_) => println!("\n\x1b[31mX\x1b[0m Invalid Input Type\n"),
+            Err(_) => {
+                let x = StyledText::new("X").fg(Color::Red);
+                println!("\n{x} Invalid Input Type\n")
+            }
         }
     }
 }
@@ -82,7 +88,9 @@ pub fn select<'a>(before: &'a str, options: &'a [&'a str]) -> usize {
     let mut i = 0;
 
     // print everything
-    println!("\x1b[31m?\x1b[0m {before} \x1b[90m›\x1b[0m ");
+    let quest = StyledText::new("?").fg(Color::Red);
+    let caret = StyledText::new("›").fg(Color::BrightBlack);
+    println!("{quest} {before} {caret} ");
 
     populate(options, None, 0);
 
@@ -140,7 +148,9 @@ pub fn multiselect(before: &str, options: &[&str]) -> Vec<bool> {
     let mut i = 0;
 
     // print everything
-    println!("\x1b[31m?\x1b[0m {before} \x1b[90m›\x1b[0m ");
+    let quest = StyledText::new("?").fg(Color::Red);
+    let caret = StyledText::new("›").fg(Color::BrightBlack);
+    println!("{quest} {before} {caret} ");
 
     populate(options, Some(&matrix), 0);
 
@@ -185,22 +195,21 @@ pub fn multiselect(before: &str, options: &[&str]) -> Vec<bool> {
     matrix
 }
 
-/// Populate function for multiselect
+/// Populate function for select/multiselect
 fn populate(options: &[&str], matrix: Option<&[bool]>, cursor: usize) {
     for (i, option) in options.iter().enumerate() {
         clear_line();
         if i == cursor {
-            println!(
-                "\x1b[36m ›\x1b[0m\x1b[3{}m {}\x1b[0m",
-                if matrix.is_some() && matrix.unwrap()[i] {
-                    "2"
-                } else {
-                    "6"
-                },
-                option
-            );
+            let caret = StyledText::new("›").fg(Color::Green);
+            let option = if matrix.is_some() && matrix.unwrap()[i] {
+                StyledText::new(option).fg(Color::Green)
+            } else {
+                StyledText::new(option).fg(Color::Cyan)
+            };
+            println!(" {caret} {option}");
         } else if matrix.is_some() && matrix.unwrap()[i] {
-            println!("\x1b[32m   {}\x1b[0m", option);
+            let option = StyledText::new(option).fg(Color::Green);
+            println!("   {}", option);
         } else {
             println!("   {}", option);
         }
@@ -211,27 +220,27 @@ fn populate(options: &[&str], matrix: Option<&[bool]>, cursor: usize) {
 /// Enumeration representing different types of spinners.
 #[derive(Debug, Clone)]
 pub enum SpinnerType {
+    /// Spinner with characters `/` `-` `\` `|`.
     Standard,
+    /// Spinner with dots `.` `..` `...` `.....`.
     Dots,
+    /// Spinner with box characters `▌` `▀` `▐` `▄`.
     Box,
+    /// Spinner with flip characters `_` `_` `_` `-` `\` `'` `´` `-` `_` `_` `_`.
     Flip,
-    Custom(Vec<&'static str>),
+    /// Custom spinner with user-defined frames.
+    Custom(&'static [&'static str]),
 }
 
 impl SpinnerType {
-    /// Converts the spinner type to a vector of frames, gives back the following variants:
-    ///  - `SpinnerType::Standard`: Standard spinner with characters / - \ |.
-    ///  - `SpinnerType::Dots`: Spinner with dots . .. ... .....
-    ///  - `SpinnerType::Box`: Spinner with box characters ▌ ▀ ▐ ▄.
-    ///  - `SpinnerType::Flip`: Spinner with flip characters _ _ _ - \ ' ´ - _ _ _.
-    ///  - `SpinnerType::Custom(frames)`: Custom spinner with user-defined frames.
-    pub fn to_frames(&self) -> Vec<&'static str> {
+    /// Returns the frames of the spinner type.
+    pub fn frames(&self) -> &'static [&'static str] {
         match self {
-            SpinnerType::Standard => vec!["/", "-", "\\", "|"],
-            SpinnerType::Dots => vec![".", "..", "...", "....", "...", ".."],
-            SpinnerType::Box => vec!["▌", "▀", "▐", "▄"],
-            SpinnerType::Flip => vec!["_", "_", "_", "-", "`", "`", "'", "´", "-", "_", "_", "_"],
-            SpinnerType::Custom(frames) => frames.to_owned(),
+            SpinnerType::Standard => &["/", "-", "\\", "|"],
+            SpinnerType::Dots => &[".", "..", "...", "....", "...", ".."],
+            SpinnerType::Box => &["▌", "▀", "▐", "▄"],
+            SpinnerType::Flip => &["_", "_", "_", "-", "`", "`", "'", "´", "-", "_", "_", "_"],
+            SpinnerType::Custom(frames) => frames,
         }
     }
 }
@@ -246,7 +255,7 @@ impl SpinnerType {
 /// - `time`: A floating-point number representing the duration of the spinner animation in seconds.
 /// - `spinner_type`: The type of spinner to display.
 pub fn spinner(mut time: f64, spinner_type: SpinnerType) {
-    let frames = spinner_type.to_frames();
+    let frames = spinner_type.frames();
     let mut i = 0;
 
     while time > 0.0 {

src/lib.rs

@@ -4,3 +4,4 @@
 pub mod control;
 pub mod input;
 pub mod read;
+pub mod styled;

src/read.rs

@@ -5,38 +5,32 @@
 
 use std::io;
 
-/// # Key Enum
-///
-/// The `Key` enum represents different keyboard keys that can be captured by the
-/// `read_key` function.
-///
-/// - `ArrowUp`: Represents the arrow up key.
-/// - `ArrowDown`: Represents the arrow down key.
-/// - `ArrowRight`: Represents the arrow right key.
-/// - `ArrowLeft`: Represents the arrow left key.
-/// - `Enter`: Represents the Enter/Return key.
-/// - `Tab`: Represents the Tab key.
-/// - `Backspace`: Represents the Backspace key.
-/// - `Escape`: Represents the Escape key.
-/// - `Char(char)`: Represents any printable character on the keyboard.
+/// Represents different keyboard keys that can be captured by the `read_key` function.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum Key {
+    /// Arrow up key.
     ArrowUp,
+    /// Arrow down key.
     ArrowDown,
+    /// Arrow right key.
     ArrowRight,
+    /// Arrow left key.
     ArrowLeft,
+    /// Enter/Return key.
     Enter,
+    /// Tab key.
     Tab,
+    /// Backspace key.
     Backspace,
+    /// Escape key.
     Escape,
+    /// Any printable character on the keyboard.
     Char(char),
+    /// Any unrecognized key.
     Unknown,
 }
 
-/// # Read Key Function
-///
-/// The `read_key` function reads a single key event from the console input
-/// and returns a `Key` enum.
+/// Reads a single key event from the console input and returns a `Key` enum.
 pub fn read_key() -> io::Result<Key> {
     #[cfg(windows)]
     {
@@ -49,10 +43,8 @@ pub fn read_key() -> io::Result<Key> {
     }
 }
 
-/// # Windows Module
-///
-/// The `windows` module contains Windows-specific implementation details for reading
-/// keyboard input. It utilizes the `windows-sys` crate to interact with Windows Console API.
+/// Contains Windows-specific implementation details for reading keyboard
+/// input. It utilizes the `windows-sys` crate to interact with Windows Console API.
 #[cfg(windows)]
 pub mod windows {
     use super::Key;
@@ -103,10 +95,8 @@ pub mod windows {
     }
 }
 
-/// # Unix Module
-///
-/// The `unix` module contains Unix-specific implementation details for reading
-/// keyboard input. It uses the `libc` crate to manipulate terminal attributes.
+/// Contains Unix-specific implementation details for reading keyboard
+/// input. It uses the `libc` crate to manipulate terminal attributes.
 #[cfg(unix)]
 pub mod unix {
     use libc::{tcgetattr, tcsetattr, ECHO, ICANON, STDIN_FILENO, TCSANOW};
@@ -115,7 +105,7 @@ pub mod unix {
 
     use super::Key;
 
-    // Internal function for disabling line buffering.
+    // Disables line buffering.
     fn disable_line_buffering() -> io::Result<()> {
         let mut termios = unsafe { mem::zeroed() };
         if unsafe { tcgetattr(STDIN_FILENO, &mut termios) } != 0 {
@@ -131,7 +121,7 @@ pub mod unix {
         Ok(())
     }
 
-    // Internal function for enabling line buffering.
+    // Enables line buffering.
     fn enable_line_buffering() -> io::Result<()> {
         let mut termios = unsafe { mem::zeroed() };
         if unsafe { tcgetattr(STDIN_FILENO, &mut termios) } != 0 {
@@ -147,7 +137,7 @@ pub mod unix {
         Ok(())
     }
 
-    // Internal function for reading a key from the console.
+    // Reads a key from the console.
     pub(crate) fn read_key() -> io::Result<Key> {
         let mut buffer = [0; 3];
         disable_line_buffering()?;