color: refactor docs, add a couple more methods

Moved the gradient function into the color module, but kept an alias
under the old name.

Gradients now return color objects.

Converting colors to string now uses rgba format when alpha is not 100%.

.gitignore

@@ -14,6 +14,7 @@
 /docs/install/*.md
 /docs/cli/cli/index.md
 /docs/colorschemes/**/index.md
+/docs/config/lua/color/index.md
 /docs/config/lua/config/index.md
 /docs/config/lua/gui-events/index.md
 /docs/config/lua/keyassignment/index.md

ci/generate-docs.py

@@ -336,6 +336,7 @@ def render(self, output, depth=0):
                         "enum: KeyAssignment",
                         "config/lua/keyassignment",
                     ),
+                    Gen("object: Color", "config/lua/color"),
                     Page("object: ExecDomain", "config/lua/ExecDomain.md"),
                     Page("object: LocalProcessInfo", "config/lua/LocalProcessInfo.md"),
                     Gen("object: MuxWindow", "config/lua/mux-window"),

color-types/src/lib.rs

@@ -238,6 +238,13 @@ impl From<SrgbaTuple> for (f32, f32, f32, f32) {
     }
 }
 
+impl From<csscolorparser::Color> for SrgbaTuple {
+    fn from(color: csscolorparser::Color) -> Self {
+        let (r, g, b, a) = color.rgba();
+        Self(r as f32, g as f32, b as f32, a as f32)
+    }
+}
+
 lazy_static::lazy_static! {
     static ref NAMED_COLORS: HashMap<String, SrgbaTuple> = build_colors();
 }
@@ -315,6 +322,14 @@ impl SrgbaTuple {
         )
     }
 
+    pub fn to_string(self) -> String {
+        if self.3 == 1.0 {
+            self.to_rgb_string()
+        } else {
+            self.to_rgba_string()
+        }
+    }
+
     /// Returns a string of the form `#RRGGBB`
     pub fn to_rgb_string(self) -> String {
         format!(
@@ -327,11 +342,11 @@ impl SrgbaTuple {
 
     pub fn to_rgba_string(self) -> String {
         format!(
-            "rgba:{} {} {} {}%",
-            (self.0 * 255.) as u8,
-            (self.1 * 255.) as u8,
-            (self.2 * 255.) as u8,
-            (self.3 * 100.) as u8
+            "rgba({}% {}% {}% {}%)",
+            (self.0 * 100.),
+            (self.1 * 100.),
+            (self.2 * 100.),
+            (self.3 * 100.)
         )
     }
 
@@ -782,13 +797,13 @@ mod tests {
     fn from_rgba() {
         assert_eq!(
             SrgbaTuple::from_str("clear").unwrap().to_rgba_string(),
-            "rgba:0 0 0 0%"
+            "rgba(0% 0% 0% 0%)"
         );
         assert_eq!(
             SrgbaTuple::from_str("rgba:100% 0 0 50%")
                 .unwrap()
                 .to_rgba_string(),
-            "rgba:255 0 0 50%"
+            "rgba(100% 0% 0% 50%)"
         );
     }
 
@@ -800,12 +815,11 @@ mod tests {
                 .to_rgb_string(),
             "#ff0000"
         );
-        assert_eq!(
-            SrgbaTuple::from_str("rgba(255,0,0,1)")
-                .unwrap()
-                .to_rgba_string(),
-            "rgba:255 0 0 100%"
-        );
+
+        let rgba = SrgbaTuple::from_str("rgba(255,0,0,1)").unwrap();
+        let round_trip = SrgbaTuple::from_str(&rgba.to_rgba_string()).unwrap();
+        assert_eq!(rgba, round_trip);
+        assert_eq!(rgba.to_rgba_string(), "rgba(100% 0% 0% 100%)");
     }
 
     #[test]

config/src/color.rs

@@ -56,13 +56,13 @@ impl std::ops::Deref for RgbaColor {
 
 impl Into<String> for &RgbaColor {
     fn into(self) -> String {
-        self.color.to_rgb_string()
+        self.color.to_string()
     }
 }
 
 impl Into<String> for RgbaColor {
     fn into(self) -> String {
-        self.color.to_rgb_string()
+        self.color.to_string()
     }
 }
 

config/src/lua.rs

@@ -1,8 +1,7 @@
 use crate::exec_domain::{ExecDomain, ValueOrFunc};
 use crate::keyassignment::KeyAssignment;
 use crate::{
-    FontAttributes, FontStretch, FontStyle, FontWeight, FreeTypeLoadTarget, Gradient, RgbaColor,
-    TextStyle,
+    FontAttributes, FontStretch, FontStyle, FontWeight, FreeTypeLoadTarget, RgbaColor, TextStyle,
 };
 use anyhow::anyhow;
 use luahelper::{from_lua_value_dynamic, lua_value_to_dynamic};
@@ -205,7 +204,6 @@ end
         wezterm_mod.set("sleep_ms", lua.create_async_function(sleep_ms)?)?;
         wezterm_mod.set("strftime", lua.create_function(strftime)?)?;
         wezterm_mod.set("strftime_utc", lua.create_function(strftime_utc)?)?;
-        wezterm_mod.set("gradient_colors", lua.create_function(gradient_colors)?)?;
         wezterm_mod.set("shell_join_args", lua.create_function(shell_join_args)?)?;
         wezterm_mod.set("shell_quote_arg", lua.create_function(shell_quote_arg)?)?;
         wezterm_mod.set("shell_split", lua.create_function(shell_split)?)?;
@@ -672,17 +670,6 @@ fn utf16_to_utf8<'lua>(_: &'lua Lua, text: mlua::String) -> mlua::Result<String>
     String::from_utf16(wide).map_err(|e| mlua::Error::external(e))
 }
 
-fn gradient_colors<'lua>(
-    _lua: &'lua Lua,
-    (gradient, num_colors): (Gradient, usize),
-) -> mlua::Result<Vec<String>> {
-    let g = gradient.build().map_err(|e| mlua::Error::external(e))?;
-    Ok(g.colors(num_colors)
-        .into_iter()
-        .map(|c| c.to_hex_string())
-        .collect())
-}
-
 pub fn add_to_config_reload_watch_list<'lua>(
     lua: &'lua Lua,
     args: Variadic<String>,

docs/config/lua/color/adjust_hue_fixed.md

@@ -0,0 +1,11 @@
+## `color:adjust_hue_fixed(degrees)`
+
+*Since: nightly builds only*
+
+Adjust the hue angle by the specified number of degrees.
+
+180 degrees gives the complementary color.
+Three colors separated by 120 degrees form the triad.
+Four colors separated by 90 degrees form the square.
+
+See also [color:adjust_hue_fixed_ryb()](adjust_hue_fixed_ryb.md).

docs/config/lua/color/adjust_hue_fixed_ryb.md

@@ -0,0 +1,16 @@
+## `color:adjust_hue_fixed_ryb(degrees)`
+
+*Since: nightly builds only*
+
+Adjust the hue angle by the specified number of degrees.
+
+This method uses the [RYB color
+model](https://en.wikipedia.org/wiki/RYB_color_model), which more
+closely matches how artists think of mixing colors and which is
+sometimes referred to as the "artist's color wheel".
+
+180 degrees gives the complementary color.
+Three colors separated by 120 degrees form the triad.
+Four colors separated by 90 degrees form the square.
+
+See also [color:adjust_hue_fixed()](adjust_hue_fixed.md).

docs/config/lua/color/complement.md

@@ -0,0 +1,9 @@
+## `color:complement()`
+
+*Since: nightly builds only*
+
+Returns the complement of the color. The complement is computed
+by converting to HSL, rotating by 180 degrees and converting back
+to RGBA.
+
+See also: [color:complement_ryb()](complement_ryb.md).

docs/config/lua/color/complement_ryb.md

@@ -0,0 +1,13 @@
+## `color:complement_ryb()`
+
+*Since: nightly builds only*
+
+Returns the complement of the color using the [RYB color
+model](https://en.wikipedia.org/wiki/RYB_color_model), which more closely
+matches how artists think of mixing colors.
+
+The complement is computed by converting to HSL, converting the
+hue angle to the equivalent RYB angle, rotating by 180 degrees and
+and then converting back to RGBA.
+
+See also: [color:complement()](complement.md).

docs/config/lua/color/contrast_ratio.md

@@ -0,0 +1,25 @@
+### `color:contrast_ratio(color)`
+
+*Since: nightly builds only*
+
+Computes the contrast ratio between the two colors.
+
+```lua
+> wezterm.color.parse("red"):contrast_ratio(wezterm.color.parse("yellow"))
+1
+> wezterm.color.parse("red"):contrast_ratio(wezterm.color.parse("navy"))
+1.8273614734023298
+```
+
+The contrast ratio is computed by first converting to HSL, taking the
+L components, and diving the lighter one by the darker one.
+
+A contrast ratio of 1 means no contrast.
+
+The maximum possible contrast ratio is 21:
+
+```lua
+> wezterm.color.parse("black"):contrast_ratio(wezterm.color.parse("white"))
+21
+```
+

docs/config/lua/color/darken.md

@@ -0,0 +1,8 @@
+## `color:darken(factor)`
+
+*Since: nightly builds only*
+
+Scales the color towards the minimum lightness by the provided
+factor, which should be in the range `0.0` through `1.0`.
+
+

docs/config/lua/color/darken_fixed.md

@@ -0,0 +1,7 @@
+## `color:darken_fixed(amount)`
+
+*Since: nightly builds only*
+
+Decrease the lightness by amount, a value ranging from `0.0` to `1.0`.
+
+

docs/config/lua/color/delta_e.md

@@ -0,0 +1,16 @@
+### `color:delta_e(color)`
+
+*Since: nightly builds only*
+
+Computes the CIEDE2000 DeltaE value representing the difference
+between the two colors.
+
+A value:
+
+* <= 1.0: difference is not perceptible by the human eye
+* 1-2: difference is perceptible through close observation
+* 2-10: difference is perceptible at a glance
+* 11-49: Colors are more similar than the opposite
+* 50-99: Colors are more opposite than similar
+* 100: Colors are exactly the opposite
+

docs/config/lua/color/desaturate.md

@@ -0,0 +1,8 @@
+## `color:desaturate(factor)`
+
+*Since: nightly builds only*
+
+Scales the color towards the minimum saturation by the provided factor, which
+should be in the range `0.0` through `1.0`.
+
+

docs/config/lua/color/desaturate_fixed.md

@@ -0,0 +1,7 @@
+## `color:desaturate_fixed(amount)`
+
+*Since: nightly builds only*
+
+Decrease the saturation by amount, a value ranging from `0.0` to `1.0`.
+
+

docs/config/lua/color/hsla.md

@@ -0,0 +1,12 @@
+## `color:hsla()`
+
+*Since: nightly builds only*
+
+Converts the color to the HSL colorspace and returns those values +
+alpha:
+
+```lua
+local h, s, l, a = color:hsla()
+```
+
+

docs/config/lua/color/index.markdown

@@ -0,0 +1,16 @@
+# `Color` object
+
+Color objects can be created by calling
+[wezterm.color.parse()](../wezterm.color/parse.md) and may also be
+returned by various wezterm functions and methods.
+
+They represent a color that is internally stored in SRGBA.
+
+Color objects have a number of methods that are helpful to
+compare and compute other color values, which is helpful
+when programmatically generating color schemes.
+
+## Available methods
+
+
+

docs/config/lua/color/laba.md

@@ -0,0 +1,12 @@
+### `color:laba()`
+
+*Since: nightly builds only*
+
+Converts the color to the LAB colorspace and returns those values +
+alpha:
+
+```lua
+local l, a, b, alpha = color:laba()
+```
+
+

docs/config/lua/color/lighten.md

@@ -0,0 +1,8 @@
+## `color:lighten(factor)`
+
+*Since: nightly builds only*
+
+Scales the color towards the maximum lightness by the provided
+factor, which should be in the range `0.0` through `1.0`.
+
+

docs/config/lua/color/lighten_fixed.md

@@ -0,0 +1,7 @@
+## `color:lighten_fixed(amount)`
+
+*Since: nightly builds only*
+
+Increase the lightness by amount, a value ranging from `0.0` to `1.0`.
+
+

docs/config/lua/color/linear_rgba.md

@@ -0,0 +1,13 @@
+## `color:linear_rgba()`
+
+*Since: nightly builds only*
+
+Returns a tuple of the colors converted to linear RGBA and
+expressed as floating point numbers in the range `0.0-1.0`:
+
+```lua
+> r, g, b, a = wezterm.color.parse("purple"):linear_rgba()
+> print(r, g, b, a)
+07:32:17.734 INFO logging > lua: 0.2158605307340622 0 0.2158605307340622 1
+```
+

docs/config/lua/color/saturate.md

@@ -0,0 +1,8 @@
+## `color:saturate(factor)`
+
+*Since: nightly builds only*
+
+Scales the color towards the maximum saturation by the provided factor, which
+should be in the range `0.0` through `1.0`.
+
+

docs/config/lua/color/saturate_fixed.md

@@ -0,0 +1,7 @@
+## `color:saturate_fixed(amount)`
+
+*Since: nightly builds only*
+
+Increase the saturation by amount, a value ranging from `0.0` to `1.0`.
+
+

docs/config/lua/color/square.md

@@ -0,0 +1,12 @@
+## `color:square()`
+
+*Since: nightly builds only*
+
+Returns the other three colors that form a square. The other colors
+are 90 degrees apart on the HSL color wheel.
+
+```lua
+local a, b, c = wezterm:color.parse("yellow"):square()
+```
+
+

docs/config/lua/color/srgb_u8.md

@@ -0,0 +1,12 @@
+## `color:srgba_u8()`
+
+*Since: nightly builds only*
+
+Returns a tuple of the internal SRGBA colors expressed
+as unsigned 8-bit integers in the range 0-255:
+
+```lua
+> r, g, b, a = wezterm.color.parse("purple"):srgba_u8()
+> print(r, g, b, a)
+07:30:20.045 INFO logging > lua: 128 0 128 255
+```