From 217c57cd60628abde1ca2f0c39b014e22c9edc4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Orhun=20Parmaks=C4=B1z?= Date: Sun, 24 Nov 2024 02:23:40 +0300 Subject: [PATCH] refactor: modularize backends (#1508) Backend code is now moved to `ratatui-crossterm`, `ratatui-termion` and `ratatui-termwiz`. This should be backwards compatible with existing code. Co-authored-by: Josh McKinney --- Cargo.lock | 44 ++++- Cargo.toml | 28 +-- clippy.toml | 6 + ratatui-core/Cargo.toml | 22 ++- {ratatui => ratatui-core}/src/backend.rs | 29 +-- {ratatui => ratatui-core}/src/backend/test.rs | 2 +- ratatui-core/src/lib.rs | 1 + ratatui-crossterm/Cargo.toml | 45 +++++ ratatui-crossterm/README.md | 10 ++ .../src/lib.rs | 19 +- ratatui-termion/Cargo.toml | 35 ++++ ratatui-termion/README.md | 11 ++ .../termion.rs => ratatui-termion/src/lib.rs | 24 ++- ratatui-termwiz/Cargo.toml | 39 ++++ ratatui-termwiz/README.md | 11 ++ .../termwiz.rs => ratatui-termwiz/src/lib.rs | 38 ++-- ratatui-widgets/Cargo.toml | 12 +- ratatui/Cargo.toml | 167 +++++++++--------- ratatui/src/lib.rs | 30 ++-- ratatui/src/prelude.rs | 5 +- ratatui/src/terminal/init.rs | 11 +- ratatui/src/terminal/terminal.rs | 3 +- xtask/README.md | 10 +- xtask/src/main.rs | 18 ++ 24 files changed, 445 insertions(+), 175 deletions(-) rename {ratatui => ratatui-core}/src/backend.rs (95%) rename {ratatui => ratatui-core}/src/backend/test.rs (99%) create mode 100644 ratatui-crossterm/Cargo.toml create mode 100644 ratatui-crossterm/README.md rename ratatui/src/backend/crossterm.rs => ratatui-crossterm/src/lib.rs (97%) create mode 100644 ratatui-termion/Cargo.toml create mode 100644 ratatui-termion/README.md rename ratatui/src/backend/termion.rs => ratatui-termion/src/lib.rs (97%) create mode 100644 ratatui-termwiz/Cargo.toml create mode 100644 ratatui-termwiz/README.md rename ratatui/src/backend/termwiz.rs => ratatui-termwiz/src/lib.rs (95%) diff --git a/Cargo.lock b/Cargo.lock index a8ff2130..3f0c4c69 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2162,13 +2162,14 @@ dependencies = [ "rand 0.8.5", "rand_chacha 0.3.1", "ratatui-core", + "ratatui-crossterm", + "ratatui-termion", + "ratatui-termwiz", "ratatui-widgets", "rstest", "serde", "serde_json", "strum", - "termion", - "termwiz", "time", "tokio", "tracing", @@ -2191,6 +2192,7 @@ dependencies = [ "palette", "paste", "pretty_assertions", + "ratatui", "rstest", "serde", "serde_json", @@ -2200,6 +2202,40 @@ dependencies = [ "unicode-width", ] +[[package]] +name = "ratatui-crossterm" +version = "0.1.0" +dependencies = [ + "crossterm", + "document-features", + "instability", + "ratatui", + "ratatui-core", + "rstest", +] + +[[package]] +name = "ratatui-termion" +version = "0.1.0" +dependencies = [ + "document-features", + "instability", + "ratatui-core", + "rstest", + "termion", +] + +[[package]] +name = "ratatui-termwiz" +version = "0.1.0" +dependencies = [ + "document-features", + "ratatui", + "ratatui-core", + "rstest", + "termwiz", +] + [[package]] name = "ratatui-widgets" version = "0.3.0" @@ -2570,9 +2606,9 @@ dependencies = [ [[package]] name = "serde_json" -version = "1.0.132" +version = "1.0.133" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d726bfaff4b320266d395898905d0eba0345aae23b54aee3a737e260fd46db03" +checksum = "c7fceb2473b9166b2294ef05efcb65a3db80803f0b03ef86a5fc88a2b85ee377" dependencies = [ "itoa", "memchr", diff --git a/Cargo.toml b/Cargo.toml index e846b7ba..aae366ef 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,7 +1,15 @@ [workspace] resolver = "2" -members = ["ratatui", "ratatui-core", "ratatui-widgets", "xtask"] -default-members = ["ratatui", "ratatui-core", "ratatui-widgets"] +members = ["ratatui", "ratatui-*", "xtask"] +default-members = [ + "ratatui", + "ratatui-core", + "ratatui-crossterm", + # this is not included as it doesn't compile on windows + # "ratatui-termion", + "ratatui-termwiz", + "ratatui-widgets", +] [workspace.package] authors = ["Florian Dehau ", "The Ratatui Developers"] @@ -12,19 +20,13 @@ keywords = ["tui", "terminal", "dashboard"] categories = ["command-line-interface"] readme = "README.md" license = "MIT" -exclude = [ - "assets/*", - ".github", - "Makefile.toml", - "CONTRIBUTING.md", - "*.log", - "tags", -] +exclude = ["assets/*", ".github", "Makefile.toml", "CONTRIBUTING.md", "*.log", "tags"] edition = "2021" rust-version = "1.74.0" [workspace.dependencies] bitflags = "2.6.0" +crossterm = "0.28.1" document-features = "0.2.7" indoc = "2.0.5" instability = "0.3.3" @@ -32,13 +34,19 @@ itertools = "0.13.0" pretty_assertions = "1.4.1" ratatui = { path = "ratatui" } ratatui-core = { path = "ratatui-core" } +ratatui-crossterm = { path = "ratatui-crossterm" } +ratatui-termion = { path = "ratatui-termion" } +ratatui-termwiz = { path = "ratatui-termwiz" } ratatui-widgets = { path = "ratatui-widgets" } rstest = "0.23.0" serde = { version = "1.0.215", features = ["derive"] } +serde_json = "1.0.133" strum = { version = "0.26.3", features = ["derive"] } +termwiz = { version = "0.22.0" } unicode-segmentation = "1.12.0" # See for information about why we pin unicode-width unicode-width = "=0.2.0" +termion = "4.0.0" # Improve benchmark consistency [profile.bench] diff --git a/clippy.toml b/clippy.toml index 915286cd..6e841010 100644 --- a/clippy.toml +++ b/clippy.toml @@ -3,9 +3,15 @@ avoid-breaking-exported-api = false # https://rust-lang.github.io/rust-clippy/master/index.html#/multiple_crate_versions # ratatui -> bitflags v2.3 # termwiz -> wezterm-blob-leases -> mac_address -> nix -> bitflags v1.3.2 +# (also, memoffset, syn, nix, strsim, windows-sys # crossterm -> all the windows- deps https://github.com/ratatui/ratatui/pull/1064#issuecomment-2078848980 allowed-duplicate-crates = [ "bitflags", + "memoffset", + "nix", + "strsim", + "syn", + "windows-sys", "windows-targets", "windows_aarch64_gnullvm", "windows_aarch64_msvc", diff --git a/ratatui-core/Cargo.toml b/ratatui-core/Cargo.toml index f86a2396..c9a589e4 100644 --- a/ratatui-core/Cargo.toml +++ b/ratatui-core/Cargo.toml @@ -17,7 +17,13 @@ exclude.workspace = true edition.workspace = true rust-version.workspace = true +[package.metadata.docs.rs] +all-features = true +rustdoc-args = ["--cfg", "docsrs"] + [features] +default = [] + ## enables conversions from colors in the [`palette`] crate to [`Color`](crate::style::Color). palette = ["dep:palette"] @@ -25,14 +31,14 @@ palette = ["dep:palette"] ## the Crossterm backend, and is not supported on Windows 7. underline-color = [] +## Use terminal scrolling regions to make some operations less prone to +## flickering. (i.e. Terminal::insert_before). +scrolling-regions = [] + ## enables serialization and deserialization of style and color types using the [`serde`] crate. ## This is useful if you want to save themes to a file. serde = ["dep:serde", "bitflags/serde", "compact_str/serde"] -[package.metadata.docs.rs] -all-features = true -rustdoc-args = ["--cfg", "docsrs"] - [dependencies] bitflags = "2.3" cassowary = "0.3" @@ -50,9 +56,13 @@ unicode-truncate = "2" unicode-width.workspace = true [dev-dependencies] -rstest.workspace = true pretty_assertions.workspace = true -serde_json = "1.0.132" +ratatui = { workspace = true, features = ["crossterm", "termwiz"] } +rstest.workspace = true +serde_json.workspace = true + +[target.'cfg(not(windows))'.dev-dependencies] +ratatui = { workspace = true, features = ["termion"] } [lints.clippy] # we often split up a module into multiple files with the main type in a file named after the diff --git a/ratatui/src/backend.rs b/ratatui-core/src/backend.rs similarity index 95% rename from ratatui/src/backend.rs rename to ratatui-core/src/backend.rs index c001b7a0..824b59e1 100644 --- a/ratatui/src/backend.rs +++ b/ratatui-core/src/backend.rs @@ -56,7 +56,7 @@ //! Each backend handles raw mode differently, so the behavior may vary depending on the backend //! being used. Be sure to consult the backend's specific documentation for exact details on how it //! implements raw mode. - +//! //! # Alternate Screen //! //! The alternate screen is a separate buffer that some terminals provide, distinct from the main @@ -90,15 +90,15 @@ //! backend being used, and developers should consult the specific backend's documentation to //! understand how it implements mouse capture. //! -//! [`TermionBackend`]: termion/struct.TermionBackend.html -//! [`Terminal`]: crate::terminal::Terminal -//! [`TermionBackend`]: termion/struct.TermionBackend.html +//! [`CrosstermBackend`]: https://docs.rs/ratatui/latest/ratatui/backend/struct.CrosstermBackend.html +//! [`TermionBackend`]: https://docs.rs/ratatui/latest/ratatui/backend/struct.TermionBackend.html +//! [`TermwizBackend`]: https://docs.rs/ratatui/latest/ratatui/backend/struct.TermwizBackend.html +//! [`Terminal`]: https://docs.rs/ratatui/latest/ratatui/struct.Terminal.html //! [Crossterm]: https://crates.io/crates/crossterm //! [Termion]: https://crates.io/crates/termion //! [Termwiz]: https://crates.io/crates/termwiz //! [Examples]: https://github.com/ratatui/ratatui/tree/main/ratatui/examples/README.md -//! [Backend Comparison]: -//! https://ratatui.rs/concepts/backends/comparison/ +//! [Backend Comparison]: https://ratatui.rs/concepts/backends/comparison/ //! [Ratatui Website]: https://ratatui.rs use std::io; @@ -109,21 +109,6 @@ use crate::{ layout::{Position, Size}, }; -#[cfg(feature = "crossterm")] -mod crossterm; -#[cfg(feature = "crossterm")] -pub use self::crossterm::{CrosstermBackend, FromCrossterm, IntoCrossterm}; - -#[cfg(all(not(windows), feature = "termion"))] -mod termion; -#[cfg(all(not(windows), feature = "termion"))] -pub use self::termion::{FromTermion, IntoTermion, TermionBackend}; - -#[cfg(feature = "termwiz")] -mod termwiz; -#[cfg(feature = "termwiz")] -pub use self::termwiz::{FromTermwiz, IntoTermwiz, TermwizBackend}; - mod test; pub use self::test::TestBackend; @@ -162,7 +147,7 @@ pub struct WindowSize { /// Most applications should not need to interact with the `Backend` trait directly as the /// [`Terminal`] struct provides a higher level interface for interacting with the terminal. /// -/// [`Terminal`]: crate::terminal::Terminal +/// [`Terminal`]: https://docs.rs/ratatui/latest/ratatui/struct.Terminal.html pub trait Backend { /// Draw the given content to the terminal screen. /// diff --git a/ratatui/src/backend/test.rs b/ratatui-core/src/backend/test.rs similarity index 99% rename from ratatui/src/backend/test.rs rename to ratatui-core/src/backend/test.rs index 7761fd9e..8186f8bf 100644 --- a/ratatui/src/backend/test.rs +++ b/ratatui-core/src/backend/test.rs @@ -144,7 +144,7 @@ impl TestBackend { #[track_caller] pub fn assert_buffer(&self, expected: &Buffer) { // TODO: use assert_eq!() - ratatui_core::assert_buffer_eq!(&self.buffer, expected); + crate::assert_buffer_eq!(&self.buffer, expected); } /// Asserts that the `TestBackend`'s scrollback buffer is equal to the expected buffer. diff --git a/ratatui-core/src/lib.rs b/ratatui-core/src/lib.rs index 56c60d52..e900e11e 100644 --- a/ratatui-core/src/lib.rs +++ b/ratatui-core/src/lib.rs @@ -38,6 +38,7 @@ //! //! This project is licensed under the MIT License. See the [LICENSE](../LICENSE) file for details. +pub mod backend; pub mod buffer; pub mod layout; pub mod style; diff --git a/ratatui-crossterm/Cargo.toml b/ratatui-crossterm/Cargo.toml new file mode 100644 index 00000000..10b47cbd --- /dev/null +++ b/ratatui-crossterm/Cargo.toml @@ -0,0 +1,45 @@ +[package] +name = "ratatui-crossterm" +version = "0.1.0" +description = "Crossterm backend for the Ratatui Terminal UI library." +documentation = "https://docs.rs/ratatui-crossterm/" +readme = "README.md" +authors.workspace = true +repository.workspace = true +homepage.workspace = true +keywords.workspace = true +categories.workspace = true +license.workspace = true +exclude.workspace = true +edition.workspace = true +rust-version.workspace = true + +[features] +default = ["underline-color"] + +## enables the backend code that sets the underline color. +## Underline color is only supported by the [`CrosstermBackend`](backend::CrosstermBackend) backend, +## and is not supported on Windows 7. +underline-color = [] + +## Use terminal scrolling regions to make Terminal::insert_before less prone to flickering. +scrolling-regions = ["ratatui-core/scrolling-regions"] + +#! The following features are unstable and may change in the future: + +## Enable all unstable features. +unstable = ["unstable-backend-writer"] + +## Enables getting access to backends' writers. +unstable-backend-writer = [] + + +[dependencies] +crossterm.workspace = true +document-features = { workspace = true, optional = true } +instability.workspace = true +ratatui-core = { workspace = true } + +[dev-dependencies] +ratatui = { workspace = true, features = ["crossterm"] } +rstest.workspace = true diff --git a/ratatui-crossterm/README.md b/ratatui-crossterm/README.md new file mode 100644 index 00000000..45bb43dc --- /dev/null +++ b/ratatui-crossterm/README.md @@ -0,0 +1,10 @@ +# Ratatui-crossterm + + + +This module provides the [`CrosstermBackend`] implementation for the [`Backend`] trait. It uses +the [Crossterm] crate to interact with the terminal. + +[Crossterm]: https://crates.io/crates/crossterm + + diff --git a/ratatui/src/backend/crossterm.rs b/ratatui-crossterm/src/lib.rs similarity index 97% rename from ratatui/src/backend/crossterm.rs rename to ratatui-crossterm/src/lib.rs index e243012a..9efb44b1 100644 --- a/ratatui/src/backend/crossterm.rs +++ b/ratatui-crossterm/src/lib.rs @@ -1,9 +1,21 @@ +// show the feature flags in the generated documentation +#![cfg_attr(docsrs, feature(doc_cfg))] +#![cfg_attr(docsrs, feature(doc_auto_cfg))] +#![doc( + html_logo_url = "https://raw.githubusercontent.com/ratatui/ratatui/main/assets/logo.png", + html_favicon_url = "https://raw.githubusercontent.com/ratatui/ratatui/main/assets/favicon.ico" +)] +#![warn(missing_docs)] //! This module provides the [`CrosstermBackend`] implementation for the [`Backend`] trait. It uses //! the [Crossterm] crate to interact with the terminal. //! //! [Crossterm]: https://crates.io/crates/crossterm +#![cfg_attr(feature = "document-features", doc = "\n## Features")] +#![cfg_attr(feature = "document-features", doc = document_features::document_features!())] + use std::io::{self, Write}; +pub use crossterm; #[cfg(feature = "underline-color")] use crossterm::style::SetUnderlineColor; use crossterm::{ @@ -16,8 +28,7 @@ use crossterm::{ }, terminal::{self, Clear}, }; - -use crate::{ +use ratatui_core::{ backend::{Backend, ClearType, WindowSize}, buffer::Cell, layout::{Position, Size}, @@ -74,8 +85,8 @@ use crate::{ /// for more details on raw mode and alternate screen. /// /// [`Write`]: std::io::Write -/// [`Terminal`]: crate::terminal::Terminal -/// [`backend`]: crate::backend +/// [`Terminal`]: https://docs.rs/ratatui/latest/ratatui/struct.Terminal.html +/// [`backend`]: ratatui_core::backend /// [Crossterm]: https://crates.io/crates/crossterm /// [Examples]: https://github.com/ratatui/ratatui/tree/main/ratatui/examples/README.md #[derive(Debug, Default, Clone, Eq, PartialEq, Hash)] diff --git a/ratatui-termion/Cargo.toml b/ratatui-termion/Cargo.toml new file mode 100644 index 00000000..42280be2 --- /dev/null +++ b/ratatui-termion/Cargo.toml @@ -0,0 +1,35 @@ +[package] +name = "ratatui-termion" +version = "0.1.0" +description = "Termion backend for the Ratatui Terminal UI library." +documentation = "https://docs.rs/ratatui-termion/" +readme = "README.md" +authors.workspace = true +repository.workspace = true +homepage.workspace = true +keywords.workspace = true +categories.workspace = true +license.workspace = true +exclude.workspace = true +edition.workspace = true +rust-version.workspace = true + +[package.metadata.docs.rs] +all-features = true +cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"] +rustdoc-args = ["--cfg", "docsrs"] + +[features] +default = [] + +## Use terminal scrolling regions to make Terminal::insert_before less prone to flickering. +scrolling-regions = ["ratatui-core/scrolling-regions"] + +[dependencies] +document-features = { workspace = true, optional = true } +ratatui-core = { workspace = true } +termion.workspace = true +instability.workspace = true + +[dev-dependencies] +rstest.workspace = true diff --git a/ratatui-termion/README.md b/ratatui-termion/README.md new file mode 100644 index 00000000..a1667bfb --- /dev/null +++ b/ratatui-termion/README.md @@ -0,0 +1,11 @@ +# Ratatui-termion + + + +This module provides the [`TermionBackend`] implementation for the [`Backend`] trait. It uses +the [Termion] crate to interact with the terminal. + +[`Backend`]: ratatui_core::backend::Backend +[Termion]: https://docs.rs/termion + + diff --git a/ratatui/src/backend/termion.rs b/ratatui-termion/src/lib.rs similarity index 97% rename from ratatui/src/backend/termion.rs rename to ratatui-termion/src/lib.rs index 4c1fc305..68c8e4e1 100644 --- a/ratatui/src/backend/termion.rs +++ b/ratatui-termion/src/lib.rs @@ -1,21 +1,32 @@ +// show the feature flags in the generated documentation +#![cfg_attr(docsrs, feature(doc_cfg))] +#![cfg_attr(docsrs, feature(doc_auto_cfg))] +#![doc( + html_logo_url = "https://raw.githubusercontent.com/ratatui/ratatui/main/assets/logo.png", + html_favicon_url = "https://raw.githubusercontent.com/ratatui/ratatui/main/assets/favicon.ico" +)] +#![warn(missing_docs)] //! This module provides the [`TermionBackend`] implementation for the [`Backend`] trait. It uses //! the [Termion] crate to interact with the terminal. //! -//! [`Backend`]: crate::backend::Backend -//! [`TermionBackend`]: crate::backend::TermionBackend +//! [`Backend`]: ratatui_core::backend::Backend //! [Termion]: https://docs.rs/termion +#![cfg_attr(feature = "document-features", doc = "\n## Features")] +#![cfg_attr(feature = "document-features", doc = document_features::document_features!())] + use std::{ fmt, io::{self, Write}, }; -use crate::{ +use ratatui_core::{ backend::{Backend, ClearType, WindowSize}, buffer::Cell, layout::{Position, Size}, style::{Color, Modifier, Style}, - termion::{self, color as tcolor, color::Color as _, style as tstyle}, }; +pub use termion; +use termion::{color as tcolor, color::Color as _, style as tstyle}; /// A [`Backend`] implementation that uses [Termion] to render to the terminal. /// @@ -61,7 +72,7 @@ use crate::{ /// /// [`IntoRawMode::into_raw_mode()`]: termion::raw::IntoRawMode /// [`IntoAlternateScreen::into_alternate_screen()`]: termion::screen::IntoAlternateScreen -/// [`Terminal`]: crate::terminal::Terminal +/// [`Terminal`]: ratatui::terminal::Terminal /// [Termion]: https://docs.rs/termion #[derive(Debug, Default, Clone, Eq, PartialEq, Hash)] pub struct TermionBackend @@ -532,8 +543,9 @@ impl fmt::Display for ResetRegion { #[cfg(test)] mod tests { + use ratatui_core::style::Stylize; + use super::*; - use crate::style::Stylize; #[test] fn from_termion_color() { diff --git a/ratatui-termwiz/Cargo.toml b/ratatui-termwiz/Cargo.toml new file mode 100644 index 00000000..57e13b36 --- /dev/null +++ b/ratatui-termwiz/Cargo.toml @@ -0,0 +1,39 @@ +[package] +name = "ratatui-termwiz" +version = "0.1.0" +description = "Termwiz backend for the Ratatui Terminal UI library." +documentation = "https://docs.rs/ratatui-termwiz/" +readme = "README.md" +authors.workspace = true +repository.workspace = true +homepage.workspace = true +keywords.workspace = true +categories.workspace = true +license.workspace = true +exclude.workspace = true +edition.workspace = true +rust-version.workspace = true + +[package.metadata.docs.rs] +all-features = true +cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"] +rustdoc-args = ["--cfg", "docsrs"] + +[features] +default = [] + +## Enables the backend code that sets the underline color. +## Underline color is not supported on Windows 7. +underline-color = [] + +## Use terminal scrolling regions to make Terminal::insert_before less prone to flickering. +scrolling-regions = ["ratatui-core/scrolling-regions"] + +[dependencies] +document-features = { workspace = true, optional = true } +ratatui-core = { workspace = true } +termwiz.workspace = true + +[dev-dependencies] +ratatui = { workspace = true, features = ["termwiz"] } +rstest.workspace = true diff --git a/ratatui-termwiz/README.md b/ratatui-termwiz/README.md new file mode 100644 index 00000000..ccd45a79 --- /dev/null +++ b/ratatui-termwiz/README.md @@ -0,0 +1,11 @@ +# Ratatui-termwiz + + + +This module provides the [`TermwizBackend`] implementation for the [`Backend`] trait. It uses +the [Termwiz] crate to interact with the terminal. + +[`Backend`]: trait.Backend.html +[Termwiz]: https://crates.io/crates/termwiz + + diff --git a/ratatui/src/backend/termwiz.rs b/ratatui-termwiz/src/lib.rs similarity index 95% rename from ratatui/src/backend/termwiz.rs rename to ratatui-termwiz/src/lib.rs index eb8384a2..a569b0fa 100644 --- a/ratatui/src/backend/termwiz.rs +++ b/ratatui-termwiz/src/lib.rs @@ -1,24 +1,34 @@ -//! This module provides the `TermwizBackend` implementation for the [`Backend`] trait. It uses the -//! [Termwiz] crate to interact with the terminal. +// show the feature flags in the generated documentation +#![cfg_attr(docsrs, feature(doc_cfg))] +#![cfg_attr(docsrs, feature(doc_auto_cfg))] +#![doc( + html_logo_url = "https://raw.githubusercontent.com/ratatui/ratatui/main/assets/logo.png", + html_favicon_url = "https://raw.githubusercontent.com/ratatui/ratatui/main/assets/favicon.ico" +)] +#![warn(missing_docs)] +//! This module provides the [`TermwizBackend`] implementation for the [`Backend`] trait. It uses +//! the [Termwiz] crate to interact with the terminal. //! //! [`Backend`]: trait.Backend.html -//! [`TermwizBackend`]: crate::backend::TermionBackend //! [Termwiz]: https://crates.io/crates/termwiz +#![cfg_attr(feature = "document-features", doc = "\n## Features")] +#![cfg_attr(feature = "document-features", doc = document_features::document_features!())] use std::{error::Error, io}; -use crate::{ +use ratatui_core::{ backend::{Backend, WindowSize}, buffer::Cell, layout::{Position, Size}, style::{Color, Modifier, Style}, - termwiz::{ - caps::Capabilities, - cell::{AttributeChange, Blink, CellAttributes, Intensity, Underline}, - color::{AnsiColor, ColorAttribute, ColorSpec, LinearRgba, RgbColor, SrgbaTuple}, - surface::{Change, CursorVisibility, Position as TermwizPosition}, - terminal::{buffered::BufferedTerminal, ScreenSize, SystemTerminal, Terminal}, - }, +}; +pub use termwiz; +use termwiz::{ + caps::Capabilities, + cell::{AttributeChange, Blink, CellAttributes, Intensity, Underline}, + color::{AnsiColor, ColorAttribute, ColorSpec, LinearRgba, RgbColor, SrgbaTuple}, + surface::{Change, CursorVisibility, Position as TermwizPosition}, + terminal::{buffered::BufferedTerminal, ScreenSize, SystemTerminal, Terminal}, }; /// A [`Backend`] implementation that uses [Termwiz] to render to the terminal. @@ -53,8 +63,8 @@ use crate::{ /// See the the [Examples] directory for more examples. See the [`backend`] module documentation /// for more details on raw mode and alternate screen. /// -/// [`backend`]: crate::backend -/// [`Terminal`]: crate::terminal::Terminal +/// [`backend`]: ratatui_core::backend +/// [`Terminal`]: https://docs.rs/ratatui/latest/ratatui/struct.Terminal.html /// [`BufferedTerminal`]: termwiz::terminal::buffered::BufferedTerminal /// [Termwiz]: https://crates.io/crates/termwiz /// [Examples]: https://github.com/ratatui/ratatui/tree/main/ratatui/examples/README.md @@ -759,7 +769,7 @@ mod tests { #[test] fn from_cell_attribute_for_style() { - use crate::style::Stylize; + use ratatui_core::style::Stylize; #[cfg(feature = "underline-color")] const STYLE: Style = Style::new() diff --git a/ratatui-widgets/Cargo.toml b/ratatui-widgets/Cargo.toml index 33400708..6ead4080 100644 --- a/ratatui-widgets/Cargo.toml +++ b/ratatui-widgets/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "ratatui-widgets" -description = "A collection of Ratatui widgets for building terminal user interfaces." +description = "A collection of Ratatui widgets for building terminal user interfaces using Ratatui." version = "0.3.0" readme = "README.md" authors.workspace = true @@ -14,7 +14,13 @@ exclude.workspace = true edition.workspace = true rust-version.workspace = true +[package.metadata.docs.rs] +all-features = true +rustdoc-args = ["--cfg", "docsrs"] + [features] +default = [] + ## enables serialization and deserialization of style and color types using the [`serde`] crate. ## This is useful if you want to save themes to a file. serde = ["dep:serde", "ratatui-core/serde"] @@ -37,10 +43,6 @@ unstable = ["unstable-rendered-line-info"] ## See [Issue 293](https://github.com/ratatui/ratatui/issues/293) for more details. unstable-rendered-line-info = [] -[package.metadata.docs.rs] -all-features = true -rustdoc-args = ["--cfg", "docsrs"] - [dependencies] bitflags.workspace = true itertools.workspace = true diff --git a/ratatui/Cargo.toml b/ratatui/Cargo.toml index a31ee49d..d912a583 100644 --- a/ratatui/Cargo.toml +++ b/ratatui/Cargo.toml @@ -14,25 +14,102 @@ exclude.workspace = true edition.workspace = true rust-version.workspace = true +[package.metadata.docs.rs] +all-features = true +# see https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html +cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"] +rustdoc-args = ["--cfg", "docsrs"] + +[features] +#! The crate provides a set of optional features that can be enabled in your `Cargo.toml` file. +#! +## By default, we enable the crossterm backend as this is a reasonable choice for most applications +## as it is supported on Linux/Mac/Windows systems. We also enable the `underline-color` feature +## which allows you to set the underline color of text. +default = ["crossterm", "underline-color"] +#! Generally an application will only use one backend, so you should only enable one of the following features: +## enables the [`CrosstermBackend`](backend::CrosstermBackend) backend and adds a dependency on [`crossterm`]. +crossterm = ["dep:ratatui-crossterm"] +## enables the [`TermionBackend`](backend::TermionBackend) backend and adds a dependency on [`termion`]. +termion = ["dep:ratatui-termion"] +## enables the [`TermwizBackend`](backend::TermwizBackend) backend and adds a dependency on [`termwiz`]. +termwiz = ["dep:ratatui-termwiz"] + +#! The following optional features are available for all backends: +## enables serialization and deserialization of style and color types using the [`serde`] crate. +## This is useful if you want to save themes to a file. +serde = ["dep:serde", "ratatui-core/serde", "ratatui-widgets/serde"] + +## enables conversions from colors in the [`palette`] crate to [`Color`](crate::style::Color). +palette = ["ratatui-core/palette", "dep:palette"] + +## Use terminal scrolling regions to make some operations less prone to +## flickering. (i.e. Terminal::insert_before). +scrolling-regions = [ + "ratatui-core/scrolling-regions", + "ratatui-crossterm?/scrolling-regions", + "ratatui-termion?/scrolling-regions", + "ratatui-termwiz?/scrolling-regions", +] + +## enables all widgets. +all-widgets = ["widget-calendar"] + +#! Widgets that add dependencies are gated behind feature flags to prevent unused transitive +#! dependencies. The available features are: +## enables the [`calendar`](widgets::calendar) widget module and adds a dependency on [`time`]. +widget-calendar = ["ratatui-widgets/calendar"] + +#! The following optional features are only available for some backends: + +## Enables the backend code that sets the underline color. +## Underline color is only supported by the Crossterm and Termwiz backends, and is not supported on +## Windows 7. +underline-color = [ + "ratatui-core/underline-color", + "ratatui-crossterm?/underline-color", + "ratatui-termwiz?/underline-color", +] + +#! The following features are unstable and may change in the future: + +## Enable all unstable features. +unstable = ["unstable-rendered-line-info", "unstable-widget-ref", "unstable-backend-writer"] + +## Enables the [`Paragraph::line_count`](widgets::Paragraph::line_count) +## [`Paragraph::line_width`](widgets::Paragraph::line_width) methods +## which are experimental and may change in the future. +## See [Issue 293](https://github.com/ratatui/ratatui/issues/293) for more details. +unstable-rendered-line-info = ["ratatui-widgets/unstable-rendered-line-info"] + +## enables the [`WidgetRef`] and [`StatefulWidgetRef`] traits which are experimental and may change +## in the future. +## +## [`WidgetRef`]: widgets::WidgetRef +## [`StatefulWidgetRef`]: widgets::StatefulWidgetRef +unstable-widget-ref = [] + +## Enables getting access to backends' writers. Only the Crossterm backend currently supports this. +unstable-backend-writer = ["ratatui-crossterm?/unstable-backend-writer"] + [dependencies] -crossterm = { version = "0.28.1", optional = true } document-features = { workspace = true, optional = true } indoc = "2" instability.workspace = true itertools.workspace = true palette = { version = "0.7.6", optional = true } ratatui-core = { workspace = true } +ratatui-crossterm = { workspace = true, optional = true } +ratatui-termwiz = { workspace = true, optional = true } ratatui-widgets = { workspace = true } serde = { workspace = true, optional = true } strum.workspace = true -termwiz = { version = "0.22.0", optional = true } time = { version = "0.3.11", optional = true, features = ["local-offset"] } # See for information about why we pin unicode-width unicode-width.workspace = true [target.'cfg(not(windows))'.dependencies] -# termion is not supported on Windows -termion = { version = "4.0.0", optional = true } +ratatui-termion = { workspace = true, optional = true } [dev-dependencies] argh = "0.1.12" @@ -48,13 +125,8 @@ pretty_assertions = "1.4.0" rand = "0.8.5" rand_chacha = "0.3.1" rstest = "0.23.0" -serde_json = "1.0.109" -tokio = { version = "1.41.1", features = [ - "rt", - "macros", - "time", - "rt-multi-thread", -] } +serde_json.workspace = true +tokio = { version = "1.41.1", features = ["rt", "macros", "time", "rt-multi-thread"] } tracing = "0.1.40" tracing-appender = "0.2.3" tracing-subscriber = { version = "0.3.18", features = ["env-filter"] } @@ -101,79 +173,6 @@ string_to_string = "warn" unnecessary_self_imports = "warn" use_self = "warn" -[features] -#! The crate provides a set of optional features that can be enabled in your `Cargo.toml` file. -#! -## By default, we enable the crossterm backend as this is a reasonable choice for most applications -## as it is supported on Linux/Mac/Windows systems. We also enable the `underline-color` feature -## which allows you to set the underline color of text. -default = ["crossterm", "underline-color"] -#! Generally an application will only use one backend, so you should only enable one of the following features: -## enables the [`CrosstermBackend`](backend::CrosstermBackend) backend and adds a dependency on [`crossterm`]. -crossterm = ["dep:crossterm"] -## enables the [`TermionBackend`](backend::TermionBackend) backend and adds a dependency on [`termion`]. -termion = ["dep:termion"] -## enables the [`TermwizBackend`](backend::TermwizBackend) backend and adds a dependency on [`termwiz`]. -termwiz = ["dep:termwiz"] - -#! The following optional features are available for all backends: -## enables serialization and deserialization of style and color types using the [`serde`] crate. -## This is useful if you want to save themes to a file. -serde = ["dep:serde", "ratatui-core/serde", "ratatui-widgets/serde"] - -## enables conversions from colors in the [`palette`] crate to [`Color`](crate::style::Color). -palette = ["ratatui-core/palette", "dep:palette"] - -## Use terminal scrolling regions to make some operations less prone to -## flickering. (i.e. Terminal::insert_before). -scrolling-regions = [] - -## enables all widgets. -all-widgets = ["widget-calendar"] - -#! Widgets that add dependencies are gated behind feature flags to prevent unused transitive -#! dependencies. The available features are: -## enables the [`calendar`](widgets::calendar) widget module and adds a dependency on [`time`]. -widget-calendar = ["ratatui-widgets/calendar"] - -#! The following optional features are only available for some backends: - -## enables the backend code that sets the underline color. -## Underline color is only supported by the [`CrosstermBackend`](backend::CrosstermBackend) backend, -## and is not supported on Windows 7. -underline-color = ["dep:crossterm", "ratatui-core/underline-color"] - -#! The following features are unstable and may change in the future: - -## Enable all unstable features. -unstable = [ - "unstable-rendered-line-info", - "unstable-widget-ref", - "unstable-backend-writer", -] - -## Enables the [`Paragraph::line_count`](widgets::Paragraph::line_count) -## [`Paragraph::line_width`](widgets::Paragraph::line_width) methods -## which are experimental and may change in the future. -## See [Issue 293](https://github.com/ratatui/ratatui/issues/293) for more details. -unstable-rendered-line-info = ["ratatui-widgets/unstable-rendered-line-info"] - -## enables the [`WidgetRef`] and [`StatefulWidgetRef`] traits which are experimental and may change -## in the future. -## -## [`WidgetRef`]: widgets::WidgetRef -## [`StatefulWidgetRef`]: widgets::StatefulWidgetRef -unstable-widget-ref = [] - -## Enables getting access to backends' writers. -unstable-backend-writer = [] - -[package.metadata.docs.rs] -all-features = true -# see https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html -cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"] -rustdoc-args = ["--cfg", "docsrs"] - [lib] bench = false diff --git a/ratatui/src/lib.rs b/ratatui/src/lib.rs index d3d4d597..955daf79 100644 --- a/ratatui/src/lib.rs +++ b/ratatui/src/lib.rs @@ -326,25 +326,35 @@ //! [Forum]: https://forum.ratatui.rs //! [Sponsors Badge]: https://img.shields.io/github/sponsors/ratatui?logo=github&style=flat-square&color=1370D3 -/// re-export the `crossterm` crate so that users don't have to add it as a dependency -#[cfg(feature = "crossterm")] -pub use crossterm; /// re-export the `palette` crate so that users don't have to add it as a dependency #[cfg(feature = "palette")] pub use palette; +/// re-export the `crossterm` crate so that users don't have to add it as a dependency +#[cfg(feature = "crossterm")] +pub use ratatui_crossterm::crossterm; +/// re-export the `termion` crate so that users don't have to add it as a dependency +#[cfg(all(not(windows), feature = "termion"))] +pub use ratatui_termion::termion; +/// re-export the `termwiz` crate so that users don't have to add it as a dependency +#[cfg(feature = "termwiz")] +pub use ratatui_termwiz::termwiz; #[cfg(feature = "crossterm")] pub use terminal::{ init, init_with_options, restore, try_init, try_init_with_options, try_restore, DefaultTerminal, }; pub use terminal::{CompletedFrame, Frame, Terminal, TerminalOptions, Viewport}; -/// re-export the `termion` crate so that users don't have to add it as a dependency -#[cfg(all(not(windows), feature = "termion"))] -pub use termion; -/// re-export the `termwiz` crate so that users don't have to add it as a dependency -#[cfg(feature = "termwiz")] -pub use termwiz; -pub mod backend; +/// Re-exports for the backend implementations. +pub mod backend { + pub use ratatui_core::backend::{Backend, ClearType, TestBackend, WindowSize}; + #[cfg(feature = "crossterm")] + pub use ratatui_crossterm::{CrosstermBackend, FromCrossterm, IntoCrossterm}; + #[cfg(all(not(windows), feature = "termion"))] + pub use ratatui_termion::{FromTermion, IntoTermion, TermionBackend}; + #[cfg(feature = "termwiz")] + pub use ratatui_termwiz::{FromTermwiz, IntoTermwiz, TermwizBackend}; +} + pub use ratatui_core::{buffer, layout}; pub mod prelude; pub use ratatui_core::{style, symbols}; diff --git a/ratatui/src/prelude.rs b/ratatui/src/prelude.rs index 060cfea8..a55e2ed8 100644 --- a/ratatui/src/prelude.rs +++ b/ratatui/src/prelude.rs @@ -27,14 +27,15 @@ //! assert_eq!(text::Line::default(), ratatui::text::Line::from(vec![])); //! ``` +pub use ratatui_core::backend::{self, Backend}; #[cfg(feature = "crossterm")] -pub use crate::backend::{CrosstermBackend, FromCrossterm, IntoCrossterm}; +pub use ratatui_crossterm::{CrosstermBackend, FromCrossterm, IntoCrossterm}; + #[cfg(all(not(windows), feature = "termion"))] pub use crate::backend::{FromTermion, IntoTermion, TermionBackend}; #[cfg(feature = "termwiz")] pub use crate::backend::{FromTermwiz, IntoTermwiz, TermwizBackend}; pub use crate::{ - backend::{self, Backend}, buffer::{self, Buffer}, layout::{self, Alignment, Constraint, Direction, Layout, Margin, Position, Rect, Size}, style::{self, Color, Modifier, Style, Stylize}, diff --git a/ratatui/src/terminal/init.rs b/ratatui/src/terminal/init.rs index 993f8c76..cad35b63 100644 --- a/ratatui/src/terminal/init.rs +++ b/ratatui/src/terminal/init.rs @@ -1,11 +1,14 @@ use std::io::{self, stdout, Stdout}; -use crossterm::{ - execute, - terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen}, +use ratatui_crossterm::{ + crossterm::{ + execute, + terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen}, + }, + CrosstermBackend, }; -use crate::{backend::CrosstermBackend, terminal::TerminalOptions, Terminal}; +use crate::{terminal::TerminalOptions, Terminal}; /// A type alias for the default terminal type. /// diff --git a/ratatui/src/terminal/terminal.rs b/ratatui/src/terminal/terminal.rs index 0fa6659b..2174dc6b 100644 --- a/ratatui/src/terminal/terminal.rs +++ b/ratatui/src/terminal/terminal.rs @@ -1,7 +1,8 @@ use std::io; +use ratatui_core::backend::{Backend, ClearType}; + use crate::{ - backend::{Backend, ClearType}, buffer::{Buffer, Cell}, layout::{Position, Rect, Size}, CompletedFrame, Frame, TerminalOptions, Viewport, diff --git a/xtask/README.md b/xtask/README.md index 3890acdb..a1eb27b8 100644 --- a/xtask/README.md +++ b/xtask/README.md @@ -1,5 +1,11 @@ # xtask for ratatui -See for details + -run with `cargo xtask ...` +A simple task runner for the project. + +See for details on the xtask pattern. + +Run `cargo xtask --help` for more information + + diff --git a/xtask/src/main.rs b/xtask/src/main.rs index a5e5f688..e5c00b24 100644 --- a/xtask/src/main.rs +++ b/xtask/src/main.rs @@ -1,3 +1,9 @@ +//! A simple task runner for the project. +//! +//! See for details on the xtask pattern. +//! +//! Run `cargo xtask --help` for more information + use std::{fmt::Debug, io, process::Output, vec}; use cargo_metadata::MetadataCommand; @@ -99,6 +105,10 @@ enum Command { #[command(visible_alias = "fmt")] FixFormatting, + /// Fix README.md (by running cargo-rdme) + #[command(visible_alias = "fr")] + FixReadme, + /// Fix typos in the project #[command(visible_alias = "typos")] FixTypos, @@ -143,6 +153,7 @@ impl Command { Command::LintMarkdown => lint_markdown(), Command::FixClippy => fix_clippy(), Command::FixFormatting => fix_format(), + Command::FixReadme => fix_readme(), Command::FixTypos => fix_typos(), Command::Test => test(), Command::TestBackend { backend } => test_backend(backend), @@ -178,6 +189,13 @@ fn check_readme() -> Result<()> { Ok(()) } +fn fix_readme() -> Result<()> { + for package in get_workspace_packages()? { + run_cargo(vec!["rdme", "--workspace-project", &package])?; + } + Ok(()) +} + /// Generate code coverage report fn coverage() -> Result<()> { run_cargo(vec![