feat: support gradients

Author: Mathias-Boulay

src/utils.rs

@@ -114,6 +114,45 @@ impl Color {
     }
 }
 
+/// A Color used in a gradient
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+pub struct ColorGradient {
+    red: u8,
+    green: u8,
+    blue: u8,
+}
+
+impl ColorGradient {
+    fn new(red: u8, green: u8, blue: u8) -> Self {
+        ColorGradient {
+            red: red.min(255),
+            green: green.min(255),
+            blue: blue.min(255),
+        }
+    }
+
+    fn from_hex(hex: &str) -> Self {
+        // Remove '#' if present
+        let s = hex.trim_start_matches('#');
+
+        // 6 char hex
+        let channels: Vec<u8> = (0..5)
+            .step_by(2)
+            .map(|i| u8::from_str_radix(&s[i..i + 2], 16).unwrap_or_default())
+            .collect();
+
+        ColorGradient::new(channels[0], channels[1], channels[2])
+    }
+
+    pub(crate) fn interpolate(&self, other: &ColorGradient, t: f32) -> ColorGradient {
+        ColorGradient {
+            red: (self.red as f32 + (other.red as f32 - self.red as f32) * t) as u8,
+            green: (self.green as f32 + (other.green as f32 - self.green as f32) * t) as u8,
+            blue: (self.blue as f32 + (other.blue as f32 - self.blue as f32) * t) as u8,
+        }
+    }
+}
+
 /// A terminal style attribute.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Ord, PartialOrd)]
 pub enum Attribute {
@@ -160,6 +199,8 @@ pub struct Style {
     bg: Option<Color>,
     fg_bright: bool,
     bg_bright: bool,
+    fg_gradient: Vec<ColorGradient>,
+    bg_gradient: Vec<ColorGradient>,
     attrs: BTreeSet<Attribute>,
     force: Option<bool>,
     for_stderr: bool,
@@ -179,6 +220,8 @@ impl Style {
             bg: None,
             fg_bright: false,
             bg_bright: false,
+            fg_gradient: vec![],
+            bg_gradient: vec![],
             attrs: BTreeSet::new(),
             force: None,
             for_stderr: false,
@@ -222,6 +265,19 @@ impl Style {
                 "reverse" => rv.reverse(),
                 "hidden" => rv.hidden(),
                 "strikethrough" => rv.strikethrough(),
+                gradient if gradient.starts_with("gradient_") => {
+                    for hex_color in gradient[9..].split('_') {
+                        rv = rv.gradient(ColorGradient::from_hex(hex_color));
+                    }
+                    rv
+                }
+                on_gradient if on_gradient.starts_with("on_gradient_") => {
+                    for hex_color in on_gradient[12..].split('_') {
+                        rv = rv.on_gradient(ColorGradient::from_hex(hex_color));
+                    }
+                    rv
+                }
+
                 on_c if on_c.starts_with("on_") => {
                     if let Ok(n) = on_c[3..].parse::<u8>() {
                         rv.on_color256(n)
@@ -295,6 +351,22 @@ impl Style {
         self
     }
 
+    /// Add a gradient color to the text gradient
+    /// Overrides basic foreground colors
+    #[inline]
+    pub fn gradient(mut self, color: ColorGradient) -> Self {
+        self.fg_gradient.push(color);
+        self
+    }
+
+    /// Add a gradient color to the text on_gradient
+    /// Overrides basic background colors
+    #[inline]
+    pub fn on_gradient(mut self, color: ColorGradient) -> Self {
+        self.bg_gradient.push(color);
+        self
+    }
+
     #[inline]
     pub const fn black(self) -> Self {
         self.fg(Color::Black)
@@ -486,6 +558,18 @@ impl<D> StyledObject<D> {
         self
     }
 
+    #[inline]
+    pub fn gradient(mut self, color: ColorGradient) -> StyledObject<D> {
+        self.style = self.style.gradient(color);
+        self
+    }
+
+    #[inline]
+    pub fn on_gradient(mut self, color: ColorGradient) -> StyledObject<D> {
+        self.style = self.style.on_gradient(color);
+        self
+    }
+
     /// Adds a attr.
     #[inline]
     pub fn attr(mut self, attr: Attribute) -> StyledObject<D> {
@@ -618,7 +702,7 @@ impl<D> StyledObject<D> {
 }
 
 macro_rules! impl_fmt {
-    ($name:ident) => {
+    ($name:ident,$format_char:expr) => {
         impl<D: fmt::$name> fmt::$name for StyledObject<D> {
             fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
                 let mut reset = false;
@@ -630,32 +714,49 @@ macro_rules! impl_fmt {
                         false => colors_enabled(),
                     })
                 {
-                    if let Some(fg) = self.style.fg {
-                        if fg.is_color256() {
-                            write!(f, "\x1b[38;5;{}m", fg.ansi_num())?;
-                        } else if self.style.fg_bright {
-                            write!(f, "\x1b[38;5;{}m", fg.ansi_num() + 8)?;
-                        } else {
-                            write!(f, "\x1b[{}m", fg.ansi_num() + 30)?;
+                    if self.style.fg_gradient.is_empty() {
+                        if let Some(fg) = self.style.fg {
+                            if fg.is_color256() {
+                                write!(f, "\x1b[38;5;{}m", fg.ansi_num())?;
+                            } else if self.style.fg_bright {
+                                write!(f, "\x1b[38;5;{}m", fg.ansi_num() + 8)?;
+                            } else {
+                                write!(f, "\x1b[{}m", fg.ansi_num() + 30)?;
+                            }
+                            reset = true;
                         }
-                        reset = true;
                     }
-                    if let Some(bg) = self.style.bg {
-                        if bg.is_color256() {
-                            write!(f, "\x1b[48;5;{}m", bg.ansi_num())?;
-                        } else if self.style.bg_bright {
-                            write!(f, "\x1b[48;5;{}m", bg.ansi_num() + 8)?;
-                        } else {
-                            write!(f, "\x1b[{}m", bg.ansi_num() + 40)?;
+                    if self.style.bg_gradient.is_empty() {
+                        if let Some(bg) = self.style.bg {
+                            if bg.is_color256() {
+                                write!(f, "\x1b[48;5;{}m", bg.ansi_num())?;
+                            } else if self.style.bg_bright {
+                                write!(f, "\x1b[48;5;{}m", bg.ansi_num() + 8)?;
+                            } else {
+                                write!(f, "\x1b[{}m", bg.ansi_num() + 40)?;
+                            }
+                            reset = true;
                         }
-                        reset = true;
                     }
                     for attr in &self.style.attrs {
                         write!(f, "\x1b[{}m", attr.ansi_num())?;
                         reset = true;
                     }
                 }
-                fmt::$name::fmt(&self.val, f)?;
+                // Get the underlying value
+                let mut buf: String = format!($format_char, &self.val);
+
+                if (!self.style.fg_gradient.is_empty()) {
+                    buf = apply_gradient_impl(&buf, &self.style.fg_gradient, false, true);
+                    reset = true;
+                }
+
+                if (!self.style.bg_gradient.is_empty()) {
+                    buf = apply_gradient_impl(&buf, &self.style.bg_gradient, false, false);
+                    reset = true;
+                }
+
+                write!(f, "{}", buf)?;
                 if reset {
                     write!(f, "\x1b[0m")?;
                 }
@@ -665,15 +766,15 @@ macro_rules! impl_fmt {
     };
 }
 
-impl_fmt!(Binary);
-impl_fmt!(Debug);
-impl_fmt!(Display);
-impl_fmt!(LowerExp);
-impl_fmt!(LowerHex);
-impl_fmt!(Octal);
-impl_fmt!(Pointer);
-impl_fmt!(UpperExp);
-impl_fmt!(UpperHex);
+impl_fmt!(Binary, "{:b}");
+impl_fmt!(Debug, "{:?}");
+impl_fmt!(Display, "{}");
+impl_fmt!(LowerExp, "{:e}");
+impl_fmt!(LowerHex, "{:x}");
+impl_fmt!(Octal, "{:o}");
+impl_fmt!(Pointer, "{:p}");
+impl_fmt!(UpperExp, "{:E}");
+impl_fmt!(UpperHex, "{:X}");
 
 /// "Intelligent" emoji formatter.
 ///
@@ -732,6 +833,112 @@ fn char_width(c: char) -> usize {
     }
 }
 
+/// Returns the number of visible characters, ignoring style related chars
+fn count_visible_chars(text: &str) -> usize {
+    let mut total_visible = 0;
+
+    let mut chars = text.chars();
+    while let Some(c) = chars.next() {
+        if c == '\x1b' {
+            while let Some(next) = chars.next() {
+                if next == 'm' {
+                    break;
+                }
+            }
+            continue;
+        }
+        if c != '\n' {
+            total_visible += 1;
+        }
+    }
+
+    total_visible
+}
+
+/// Applies the gradient over a string
+fn apply_gradient_impl(
+    text: &str,
+    gradients: &Vec<ColorGradient>,
+    block: bool,
+    foreground: bool,
+) -> String {
+    let ascii_number = if foreground { 3 } else { 4 };
+    let skip_sequence = format!("[{}8;2;", ascii_number);
+
+    let mut visible_chars = 0;
+    let total_visible = count_visible_chars(text);
+    // The pre-allocation is an estimate, chances are high a re-allocation will occur
+    // But it still less than without the estimate
+    // Since gradients are on the form `\x1b[{}8;2;{};{};{}m` for a single color, the estimation is 16 chars per visible char
+    let mut result = String::with_capacity(16 * total_visible);
+
+    // Second pass: apply gradient
+    let mut chars = text.chars().peekable();
+    while let Some(c) = chars.next() {
+        if c == '\x1b' {
+            let mut seq = String::from(c);
+            while let Some(&next) = chars.peek() {
+                seq.push(next);
+                chars.next();
+                if next == 'm' {
+                    break;
+                }
+            }
+
+            // Only skip foreground/background color sequences
+            if !seq.contains(&skip_sequence) {
+                result.push_str(&seq);
+            }
+            continue;
+        }
+
+        if c == '\n' {
+            result.push(c);
+            if block {
+                visible_chars = 0;
+            }
+            continue;
+        }
+
+        let progress = if total_visible > 1 {
+            visible_chars as f32 / (total_visible - 1) as f32
+        } else {
+            0.0
+        };
+
+        // Find which gradient to use, along the progress for an individual gradient interpolation
+        let gradient_range =
+            map_range((0f32, 1f32), (0f32, (gradients.len() - 1) as f32), progress);
+        let mut current_gradient_index: usize = gradient_range as usize;
+        let mut gradient_progress = gradient_range - current_gradient_index as f32;
+
+        if current_gradient_index == gradients.len() - 1 && current_gradient_index > 0 {
+            // Edge case at the end of the gradient, don't continue looping
+            current_gradient_index -= 1;
+            gradient_progress = 1.0f32
+        }
+
+        let color = gradients[current_gradient_index].interpolate(
+            &gradients[(current_gradient_index + 1).min(gradients.len() - 1)],
+            gradient_progress,
+        );
+
+        result.push_str(&format!(
+            "\x1b[{}8;2;{};{};{}m",
+            ascii_number, color.red, color.green, color.blue
+        ));
+        result.push(c);
+
+        visible_chars += 1;
+    }
+    result
+}
+
+/// Map one range to another
+fn map_range(from_range: (f32, f32), to_range: (f32, f32), s: f32) -> f32 {
+    to_range.0 + (s - from_range.0) * (to_range.1 - to_range.0) / (from_range.1 - from_range.0)
+}
+
 /// Truncates a string to a certain number of characters.
 ///
 /// This ensures that escape codes are not screwed up in the process.