change: Don't re-export crossterm's types by default

.github/workflows/test.yml

@@ -61,11 +61,15 @@ jobs:
         if: ${{ !matrix.minimal_setup }}
 
       - name: cargo test
+        run: cargo test --target=${{ matrix.target }} --features=integration_test
+        if: ${{ !matrix.minimal_setup }}
+
+      - name: cargo test without default features
         run: cargo test --target=${{ matrix.target }} --tests --no-default-features
         if: ${{ !matrix.minimal_setup }}
 
-      - name: cargo test
-        run: cargo test --target=${{ matrix.target }} --features=integration_test
+      - name: cargo test with crossterm re-export
+        run: cargo test --target=${{ matrix.target }} --features=integration_test,reexport_crossterm
         if: ${{ !matrix.minimal_setup }}
 
       - name: cargo test with custom_styling

CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [7.0.0] - unreleased
+
+### Breaking
+
+- The `Color` and `Attribute` enum are no longer re-exported from crossterm by default.
+  Instead, they're now mirrored and internally mapped.
+  This is needed to prevent breaking changes when updating crossterm in comfy-table.
+  These breaking changes happened in projects that explicitly used crossterm and comfy-table at the same time and fed crossterm's enums into comfy-table.
+  When updating comfy-table, crossterm needed to be upgraded as well, as the compile would otherwise fail due to ABI imcompatibilies.
+
+  If one wants the old behavior for convenience reasons, this can be enabled via a feature flag.
+  However, **this is also a opt-in to potential breaking ABI changes on minor/patch versions**.
+
+  This change allows us to bump the crossterm dependency in the future, without having to release a major version.
+
+### Added
+
+- `reexport_crossterm` feature flag to enable old crossterm re-export.
+
 ## [6.2.0] - 2023-05-26
 
 ### Added

Cargo.toml

@@ -38,11 +38,31 @@ required-features = ["custom_styling"]
 
 [features]
 default = ["tty"]
+# This flag enables support for terminals:
+# - Automatic detection whether we're in a terminal environment
+#   Only used when no explicit `Table::set_width` is provided.
+# - Support for ANSI Escape Code styling for terminals.
 tty = ["crossterm"]
+# This flag enables support for custom styling of text inside of cells:
+# - Text formatting still works, even if you roll your own ANSI escape sequences.
+# - Rainbow text
+# - Makes comfy-table 30-50% slower
 custom_styling = ["console"]
-# This flag is for library debugging only!
+# With this flag, comfy_table re-exposes crossterm's "Attribute" and "Color" enum.
+# By default, a mirrored type is exposed, which internally maps to the crossterm type.
+#
+# This feature is very convenient if you use both comfy_table and crossterm in your code
+# and want to use crossterm's types for everything interchangeably.
+#
+# **BUT** if you enable this feature, you opt-in for breaking ABI changes on minor/patch versions.
+# Meaning, you have to update crossterm whenever you update comfy_table, since they
+# now depend on the same types.
+reexport_crossterm = ["console"]
+# This flag is for comfy-table development debugging!
+# You usually don't need this as a user of the library.
 debug = []
-# This feature is used to expose internal functionality for integration testing.
+# This feature is used to for integration testing of comfy_table.
+# It exposes normally unexposed internal functionality for easier testing.
 integration_test = []
 
 [dependencies]

src/cell.rs

@@ -1,5 +1,5 @@
 #[cfg(feature = "tty")]
-use crossterm::style::{Attribute, Color};
+use crate::{Attribute, Color};
 
 use crate::style::CellAlignment;
 
@@ -82,8 +82,7 @@ impl Cell {
 
     /// Set the foreground text color for this cell.
     ///
-    /// comfy-table uses [Crossterm Colors](crossterm::style::Color).
-    /// Look at their documentation for all possible Colors.
+    /// Look at [Color](crate::Color) for a list of all possible Colors.
     /// ```
     /// use comfy_table::Color;
     /// use comfy_table::Cell;
@@ -101,8 +100,7 @@ impl Cell {
 
     /// Set the background color for this cell.
     ///
-    /// comfy-table uses [Crossterm Colors](crossterm::style::Color).
-    /// Look at their documentation for all possible Colors.
+    /// Look at [Color](crate::Color) for a list of all possible Colors.
     /// ```
     /// use comfy_table::Color;
     /// use comfy_table::Cell;
@@ -121,8 +119,7 @@ impl Cell {
     /// Add a styling attribute to the content cell.\
     /// Those can be **bold**, _italic_, blinking and many more.
     ///
-    /// comfy-table uses [Crossterm Attributes](crossterm::style::Attribute).
-    /// Look at their documentation for all possible [Attributes](Attribute).
+    /// Look at [Attribute](crate::Attribute) for a list of all possible Colors.
     /// ```
     /// use comfy_table::Attribute;
     /// use comfy_table::Cell;

src/style/attribute.rs

@@ -0,0 +1,129 @@
+/// Represents an attribute.
+///
+/// # Platform-specific Notes
+///
+/// * Only UNIX and Windows 10 terminals do support text attributes.
+/// * Keep in mind that not all terminals support all attributes.
+/// * Crossterm implements almost all attributes listed in the
+///   [SGR parameters](https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_parameters).
+///
+/// | Attribute | Windows | UNIX | Notes |
+/// | :-- | :--: | :--: | :-- |
+/// | `Reset` | ✓ | ✓ | |
+/// | `Bold` | ✓ | ✓ | |
+/// | `Dim` | ✓ | ✓ | |
+/// | `Italic` | ? | ? | Not widely supported, sometimes treated as inverse. |
+/// | `Underlined` | ✓ | ✓ | |
+/// | `SlowBlink` | ? | ? | Not widely supported, sometimes treated as inverse. |
+/// | `RapidBlink` | ? | ? | Not widely supported. MS-DOS ANSI.SYS; 150+ per minute. |
+/// | `Reverse` | ✓ | ✓ | |
+/// | `Hidden` | ✓ | ✓ | Also known as Conceal. |
+/// | `Fraktur` | ✗ | ✓ | Legible characters, but marked for deletion. |
+/// | `DefaultForegroundColor` | ? | ? | Implementation specific (according to standard). |
+/// | `DefaultBackgroundColor` | ? | ? | Implementation specific (according to standard). |
+/// | `Framed` | ? | ? | Not widely supported. |
+/// | `Encircled` | ? | ? | This should turn on the encircled attribute. |
+/// | `OverLined` | ? | ? | This should draw a line at the top of the text. |
+///
+/// Usage:
+///
+/// Check [crate::Cell::add_attribute] on how to use it.
+#[derive(Copy, Clone, Debug, PartialEq, Eq, Ord, PartialOrd, Hash)]
+#[non_exhaustive]
+pub enum Attribute {
+    /// Resets all the attributes.
+    Reset,
+    /// Increases the text intensity.
+    Bold,
+    /// Decreases the text intensity.
+    Dim,
+    /// Emphasises the text.
+    Italic,
+    /// Underlines the text.
+    Underlined,
+
+    // Other types of underlining
+    /// Double underlines the text.
+    DoubleUnderlined,
+    /// Undercurls the text.
+    Undercurled,
+    /// Underdots the text.
+    Underdotted,
+    /// Underdashes the text.
+    Underdashed,
+
+    /// Makes the text blinking (< 150 per minute).
+    SlowBlink,
+    /// Makes the text blinking (>= 150 per minute).
+    RapidBlink,
+    /// Swaps foreground and background colors.
+    Reverse,
+    /// Hides the text (also known as Conceal).
+    Hidden,
+    /// Crosses the text.
+    CrossedOut,
+    /// Sets the [Fraktur](https://en.wikipedia.org/wiki/Fraktur) typeface.
+    ///
+    /// Mostly used for [mathematical alphanumeric symbols](https://en.wikipedia.org/wiki/Mathematical_Alphanumeric_Symbols).
+    Fraktur,
+    /// Turns off the `Bold` attribute. - Inconsistent - Prefer to use NormalIntensity
+    NoBold,
+    /// Switches the text back to normal intensity (no bold, italic).
+    NormalIntensity,
+    /// Turns off the `Italic` attribute.
+    NoItalic,
+    /// Turns off the `Underlined` attribute.
+    NoUnderline,
+    /// Turns off the text blinking (`SlowBlink` or `RapidBlink`).
+    NoBlink,
+    /// Turns off the `Reverse` attribute.
+    NoReverse,
+    /// Turns off the `Hidden` attribute.
+    NoHidden,
+    /// Turns off the `CrossedOut` attribute.
+    NotCrossedOut,
+    /// Makes the text framed.
+    Framed,
+    /// Makes the text encircled.
+    Encircled,
+    /// Draws a line at the top of the text.
+    OverLined,
+    /// Turns off the `Frame` and `Encircled` attributes.
+    NotFramedOrEncircled,
+    /// Turns off the `OverLined` attribute.
+    NotOverLined,
+}
+
+/// Map the internal mirrored [Attribute] to the actually used [crossterm::style::Attribute]
+pub(crate) fn map_attribute(attribute: Attribute) -> crossterm::style::Attribute {
+    match attribute {
+        Attribute::Reset => crossterm::style::Attribute::Reset,
+        Attribute::Bold => crossterm::style::Attribute::Bold,
+        Attribute::Dim => crossterm::style::Attribute::Dim,
+        Attribute::Italic => crossterm::style::Attribute::Italic,
+        Attribute::Underlined => crossterm::style::Attribute::Underlined,
+        Attribute::DoubleUnderlined => crossterm::style::Attribute::DoubleUnderlined,
+        Attribute::Undercurled => crossterm::style::Attribute::Undercurled,
+        Attribute::Underdotted => crossterm::style::Attribute::Underdotted,
+        Attribute::Underdashed => crossterm::style::Attribute::Underdashed,
+        Attribute::SlowBlink => crossterm::style::Attribute::SlowBlink,
+        Attribute::RapidBlink => crossterm::style::Attribute::RapidBlink,
+        Attribute::Reverse => crossterm::style::Attribute::Reverse,
+        Attribute::Hidden => crossterm::style::Attribute::Hidden,
+        Attribute::CrossedOut => crossterm::style::Attribute::CrossedOut,
+        Attribute::Fraktur => crossterm::style::Attribute::Fraktur,
+        Attribute::NoBold => crossterm::style::Attribute::NoBold,
+        Attribute::NormalIntensity => crossterm::style::Attribute::NormalIntensity,
+        Attribute::NoItalic => crossterm::style::Attribute::NoItalic,
+        Attribute::NoUnderline => crossterm::style::Attribute::NoUnderline,
+        Attribute::NoBlink => crossterm::style::Attribute::NoBlink,
+        Attribute::NoReverse => crossterm::style::Attribute::NoReverse,
+        Attribute::NoHidden => crossterm::style::Attribute::NoHidden,
+        Attribute::NotCrossedOut => crossterm::style::Attribute::NotCrossedOut,
+        Attribute::Framed => crossterm::style::Attribute::Framed,
+        Attribute::Encircled => crossterm::style::Attribute::Encircled,
+        Attribute::OverLined => crossterm::style::Attribute::OverLined,
+        Attribute::NotFramedOrEncircled => crossterm::style::Attribute::NotFramedOrEncircled,
+        Attribute::NotOverLined => crossterm::style::Attribute::NotOverLined,
+    }
+}

src/style/color.rs

@@ -0,0 +1,116 @@
+/// Represents a color.
+///
+/// This type is a simplified re-implementation of crossterm's Color enum.
+/// See [crossterm::style::color](https://docs.rs/crossterm/latest/crossterm/style/enum.Color.html)
+///
+/// # Platform-specific Notes
+///
+/// The following list of 16 base colors are available for almost all terminals (Windows 7 and 8 included).
+///
+/// | Light      | Dark          |
+/// | :--------- | :------------ |
+/// | `DarkGrey` | `Black`       |
+/// | `Red`      | `DarkRed`     |
+/// | `Green`    | `DarkGreen`   |
+/// | `Yellow`   | `DarkYellow`  |
+/// | `Blue`     | `DarkBlue`    |
+/// | `Magenta`  | `DarkMagenta` |
+/// | `Cyan`     | `DarkCyan`    |
+/// | `White`    | `Grey`        |
+///
+/// Most UNIX terminals and Windows 10 consoles support additional colors.
+/// See [Color::Rgb] or [Color::AnsiValue] for more info.
+///
+/// Usage:
+///
+/// Check [crate::Cell::bg], [crate::Cell::fg] and  on how to use it.
+#[derive(Copy, Clone, Debug, PartialEq, Eq, Ord, PartialOrd, Hash)]
+pub enum Color {
+    /// Resets the terminal color.
+    Reset,
+
+    /// Black color.
+    Black,
+
+    /// Dark grey color.
+    DarkGrey,
+
+    /// Light red color.
+    Red,
+
+    /// Dark red color.
+    DarkRed,
+
+    /// Light green color.
+    Green,
+
+    /// Dark green color.
+    DarkGreen,
+
+    /// Light yellow color.
+    Yellow,
+
+    /// Dark yellow color.
+    DarkYellow,
+
+    /// Light blue color.
+    Blue,
+
+    /// Dark blue color.
+    DarkBlue,
+
+    /// Light magenta color.
+    Magenta,
+
+    /// Dark magenta color.
+    DarkMagenta,
+
+    /// Light cyan color.
+    Cyan,
+
+    /// Dark cyan color.
+    DarkCyan,
+
+    /// White color.
+    White,
+
+    /// Grey color.
+    Grey,
+
+    /// An RGB color. See [RGB color model](https://en.wikipedia.org/wiki/RGB_color_model) for more info.
+    ///
+    /// Most UNIX terminals and Windows 10 supported only.
+    /// See [Platform-specific notes](enum.Color.html#platform-specific-notes) for more info.
+    Rgb { r: u8, g: u8, b: u8 },
+
+    /// An ANSI color. See [256 colors - cheat sheet](https://jonasjacek.github.io/colors/) for more info.
+    ///
+    /// Most UNIX terminals and Windows 10 supported only.
+    /// See [Platform-specific notes](enum.Color.html#platform-specific-notes) for more info.
+    AnsiValue(u8),
+}
+
+/// Map the internal mirrored [Color] enum to the actually used [crossterm::style::Color].
+pub(crate) fn map_color(color: Color) -> crossterm::style::Color {
+    match color {
+        Color::Reset => crossterm::style::Color::Reset,
+        Color::Black => crossterm::style::Color::Black,
+        Color::DarkGrey => crossterm::style::Color::DarkGrey,
+        Color::Red => crossterm::style::Color::Red,
+        Color::DarkRed => crossterm::style::Color::DarkRed,
+        Color::Green => crossterm::style::Color::Green,
+        Color::DarkGreen => crossterm::style::Color::DarkGreen,
+        Color::Yellow => crossterm::style::Color::Yellow,
+        Color::DarkYellow => crossterm::style::Color::DarkYellow,
+        Color::Blue => crossterm::style::Color::Blue,
+        Color::DarkBlue => crossterm::style::Color::DarkBlue,
+        Color::Magenta => crossterm::style::Color::Magenta,
+        Color::DarkMagenta => crossterm::style::Color::DarkMagenta,
+        Color::Cyan => crossterm::style::Color::Cyan,
+        Color::DarkCyan => crossterm::style::Color::DarkCyan,
+        Color::White => crossterm::style::Color::White,
+        Color::Grey => crossterm::style::Color::Grey,
+        Color::Rgb { r, g, b } => crossterm::style::Color::Rgb { r, g, b },
+        Color::AnsiValue(value) => crossterm::style::Color::AnsiValue(value),
+    }
+}