itsscb/ratatui
1
0
Fork 0
mirror of https://github.com/ratatui/ratatui.git synced 2025-09-30 06:21:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: simplify ratatui-macro docs (#1923)

Browse Source
This commit is contained in:
Josh McKinney 2025-06-25 00:47:27 -07:00 committed by GitHub
parent 272f5c05dc
commit ca2ad4a1f9
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 125 additions and 248 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

174
ratatui-macros/README.md
View File

@ -17,15 +17,13 @@ Ratatui proper.
## Features
- Constraint-based Layouts: Easily define layout constraints such as fixed, percentage, minimum,
and maximum sizes, as well as ratios.
- Directional Layouts: Specify layouts as either horizontal or vertical with simple macro
commands.
- Span and Line macros: Make it easier to create spans and lines with styling.
- [Text macros](#text-macros) for easily defining styled [`Text`]s, [`Line`]s, and [`Span`]s.
- [Layout macros](#layout-macros) for defining [`Layout`]s with [`Constraint`]s and directions.
- [Table macros](#table-macros) for creating [`Row`]s and [`Cell`]s.
## Getting Started
To use `ratatui-macros` in your Rust project, add it as a dependency in your `Cargo.toml`:
Add `ratatui-macros` as a dependency in your `Cargo.toml`:
```shell
cargo add ratatui-macros
@ -34,154 +32,82 @@ cargo add ratatui-macros
Then, import the macros in your Rust file:
```rust
use ratatui_macros::{
constraint,
constraints,
horizontal,
vertical,
span,
line,
};
use ratatui_macros::{constraint, constraints, horizontal, line, row, span, text, vertical};
```
## Macros
## Text Macros
### Layout
If you are new to Ratatui, check out the [Layout concepts] article on the Ratatui website before
proceeding.
Use the `constraints!` macro to define layout constraints:
The [`span!`] macro creates raw or styled [`Span`]s.
```rust
use ratatui_macros::constraints;
assert_eq!(
constraints![==50, ==30%, >=3, <=1, ==1/2, *=1],
[
Constraint::Length(50),
Constraint::Percentage(30),
Constraint::Min(3),
Constraint::Max(1),
Constraint::Ratio(1, 2),
Constraint::Fill(1),
]
)
```
```rust
use ratatui_macros::constraints;
assert_eq!(
constraints![==1/4; 4],
[
Constraint::Ratio(1, 4),
Constraint::Ratio(1, 4),
Constraint::Ratio(1, 4),
Constraint::Ratio(1, 4),
]
)
```
Use the `constraint!` macro to define individual constraints:
```rust
use ratatui_macros::constraint;
assert_eq!(
constraint!(==50),
Constraint::Length(50),
)
```
Create vertical and horizontal layouts using the `vertical!` and `horizontal!` macros:
```rust
use ratatui_macros::{vertical, horizontal};
let area = Rect { x: 0, y: 0, width: 10, height: 10 };
let [main, bottom] = vertical![==100%, >=3].areas(area);
assert_eq!(bottom.y, 7);
assert_eq!(bottom.height, 3);
let [left, main, right] = horizontal![>=3, ==100%, >=3].areas(area);
assert_eq!(left.width, 3);
assert_eq!(right.width, 3);
```
### Spans
The `span!` macro create raw and styled `Span`s. They each take a format string and arguments.
`span!` accepts as the first parameter any value that can be converted to a `Style` followed by
a `;` followed by the format string and arguments.
```rust
use ratatui_macros::span;
let name = "world!";
let raw_greeting = span!("hello {name}");
let styled_greeting = span!(Style::new().green(); "hello {name}");
let styled_greeting = span!(Color::Green; "hello {name}");
let styled_greeting = span!(Modifier::BOLD; "hello {name}");
let colored_greeting = span!(Color::Green; "hello {name}");
let modified_greeting = span!(Modifier::BOLD; "hello {name}");
```
### Line
The `line!` macro creates a `Line` that contains a sequence of spans. It is similar to the
`vec!` macro.
The [`line!`] macro creates a [`Line`] that contains a sequence of [`Span`]s. It is similar to
the [`vec!`] macro. Each element is converted into a [`Span`] using [`Into::into`].
```rust
use ratatui_macros::line;
let name = "world!";
let line = line!["hello", format!("{name}")];
let line = line!["hello ", span!(Color::Green; "{name}")];
let line = line!["Name: ".bold(), "Remy".italic()];
let line = line!["bye"; 2];
```
### Text
The `text!` macro creates a `Text` that contains a sequence of lines. It is similar to the
`vec!` macro.
The [`text!`] macro creates a [`Text`] that contains a sequence of [`Line`]. It is similar to
the [`vec!`] macro. Each element is converted to a [`Line`] using [`Into::into`].
```rust
use ratatui_macros::{span, line, text};
let name = "world!";
let text = text!["hello", format!("{name}")];
let text = text!["bye"; 2];
```
It is even possible to use `span!` and `line!` in the `text!` macro:
```rust
use ratatui_macros::{span, line, text};
let name = "Bye!!!";
let text = text![line!["hello", "world".bold()], span!(Modifier::BOLD; "{name}")];
```
### Row
## Layout Macros
The `row!` macro creates a `Row` that contains a sequence of `Cell`. It is similar to the `vec!`
macro. A `Row` represents a sequence of `Cell`s in a single row of a table.
If you are new to Ratatui, check out the [Layout concepts] article on the Ratatui website before
proceeding.
The [`constraints!`] macro defines an array of [`Constraint`]s:
```rust
use ratatui_macros::row;
let layout = Layout::horizontal(constraints![==50, ==30%, >=3, <=1, ==1/2, *=1]);
```
The [`constraint!`] macro defines individual [`Constraint`]s:
```rust
let layout = Layout::horizontal([constraint!(==50)]);
```
The [`vertical!`] and [`horizontal!`] macros are a shortcut to defining a [`Layout`]:
```rust
let [top, main, bottom] = vertical![==1, *=1, >=3].areas(area);
let [left, main, right] = horizontal![>=20, *=1, >=20].areas(main);
```
## Table Macros
The [`row!`] macro creates a [`Row`] for a [`Table`] that contains a sequence of [`Cell`]s. It
is similar to the [`vec!`] macro.
```rust
let rows = [
row!["hello", "world"],
row!["goodbye", "world"],
row![
text!["line 1", line!["Line", "2".bold()]],
span!(Modifier::BOLD; "Cell 2"),
],
];
```
It is even possible to use `span!`, `line!` and `text!` in the `row!` macro:
```rust
use ratatui_macros::{span, line, text, row};
let name = "Bye!!!";
let text = row![text![line!["hello", "world".bold()]], span!(Modifier::BOLD; "{name}")];
let table = Table::new(rows, constraints![==20, *=1]);
```
## Contributing
@ -201,5 +127,13 @@ request, or a pull request, all forms of contributions are valued and appreciate
[CI Status]: https://github.com/ratatui/ratatui/actions
[Ratatui]: https://github.com/ratatui/ratatui
[Layout concepts]: https://ratatui.rs/concepts/layout
[`Constraint`]: ratatui_core::layout::Constraint
[`Layout`]: ratatui_core::layout::Layout
[`Span`]: ratatui_core::text::Span
[`Line`]: ratatui_core::text::Line
[`Text`]: ratatui_core::text::Text
[`Row`]: ratatui_widgets::table::Row
[`Cell`]: ratatui_widgets::table::Cell
[`Table`]: ratatui_widgets::table::Table
<!-- cargo-rdme end -->

199
ratatui-macros/src/lib.rs
View File

@ -7,15 +7,13 @@
//!
//! # Features
//!
//! - Constraint-based Layouts: Easily define layout constraints such as fixed, percentage, minimum,
//! and maximum sizes, as well as ratios.
//! - Directional Layouts: Specify layouts as either horizontal or vertical with simple macro
//! commands.
//! - Span and Line macros: Make it easier to create spans and lines with styling.
//! - [Text macros](#text-macros) for easily defining styled [`Text`]s, [`Line`]s, and [`Span`]s.
//! - [Layout macros](#layout-macros) for defining [`Layout`]s with [`Constraint`]s and directions.
//! - [Table macros](#table-macros) for creating [`Row`]s and [`Cell`]s.
//!
//! # Getting Started
//!
//! To use `ratatui-macros` in your Rust project, add it as a dependency in your `Cargo.toml`:
//! Add `ratatui-macros` as a dependency in your `Cargo.toml`:
//!
//! ```shell
//! cargo add ratatui-macros
@ -24,161 +22,98 @@
//! Then, import the macros in your Rust file:
//!
//! ```rust
//! use ratatui_macros::{
//! constraint,
//! constraints,
//! horizontal,
//! vertical,
//! span,
//! line,
//! };
//! use ratatui_macros::{constraint, constraints, horizontal, line, row, span, text, vertical};
//! ```
//!
//! # Macros
//! # Text Macros
//!
//! ## Layout
//!
//! If you are new to Ratatui, check out the [Layout concepts] article on the Ratatui website before
//! proceeding.
//!
//! Use the `constraints!` macro to define layout constraints:
//!
//! ```rust
//! # use ratatui_core::layout::Constraint;
//! use ratatui_macros::constraints;
//!
//! assert_eq!(
//! constraints![==50, ==30%, >=3, <=1, ==1/2, *=1],
//! [
//! Constraint::Length(50),
//! Constraint::Percentage(30),
//! Constraint::Min(3),
//! Constraint::Max(1),
//! Constraint::Ratio(1, 2),
//! Constraint::Fill(1),
//! ]
//! )
//! ```
//!
//! ```rust
//! # use ratatui_core::layout::Constraint;
//! use ratatui_macros::constraints;
//!
//! assert_eq!(
//! constraints![==1/4; 4],
//! [
//! Constraint::Ratio(1, 4),
//! Constraint::Ratio(1, 4),
//! Constraint::Ratio(1, 4),
//! Constraint::Ratio(1, 4),
//! ]
//! )
//! ```
//!
//! Use the `constraint!` macro to define individual constraints:
//!
//! ```rust
//! # use ratatui_core::layout::Constraint;
//! use ratatui_macros::constraint;
//!
//! assert_eq!(
//! constraint!(==50),
//! Constraint::Length(50),
//! )
//! ```
//!
//! Create vertical and horizontal layouts using the `vertical!` and `horizontal!` macros:
//!
//! ```rust
//! # use ratatui_core::layout::Rect;
//! use ratatui_macros::{vertical, horizontal};
//!
//! let area = Rect { x: 0, y: 0, width: 10, height: 10 };
//!
//! let [main, bottom] = vertical![==100%, >=3].areas(area);
//!
//! assert_eq!(bottom.y, 7);
//! assert_eq!(bottom.height, 3);
//!
//! let [left, main, right] = horizontal![>=3, ==100%, >=3].areas(area);
//!
//! assert_eq!(left.width, 3);
//! assert_eq!(right.width, 3);
//! ```
//!
//! ## Spans
//!
//! The `span!` macro create raw and styled `Span`s. They each take a format string and arguments.
//! `span!` accepts as the first parameter any value that can be converted to a `Style` followed by
//! a `;` followed by the format string and arguments.
//! The [`span!`] macro creates raw or styled [`Span`]s.
//!
//! ```rust
//! # use ratatui_core::style::{Color, Modifier, Style, Stylize};
//! use ratatui_macros::span;
//!
//! # use ratatui_macros::span;
//! let name = "world!";
//! let raw_greeting = span!("hello {name}");
//! let styled_greeting = span!(Style::new().green(); "hello {name}");
//! let styled_greeting = span!(Color::Green; "hello {name}");
//! let styled_greeting = span!(Modifier::BOLD; "hello {name}");
//! let colored_greeting = span!(Color::Green; "hello {name}");
//! let modified_greeting = span!(Modifier::BOLD; "hello {name}");
//! ```
//!
//! ## Line
//!
//! The `line!` macro creates a `Line` that contains a sequence of spans. It is similar to the
//! `vec!` macro.
//! The [`line!`] macro creates a [`Line`] that contains a sequence of [`Span`]s. It is similar to
//! the [`vec!`] macro. Each element is converted into a [`Span`] using [`Into::into`].
//!
//! ```rust
//! use ratatui_macros::line;
//!
//! # use ratatui_core::style::{Color, Stylize};
//! # use ratatui_macros::{line, span};
//! let name = "world!";
//! let line = line!["hello", format!("{name}")];
//! let line = line!["hello ", span!(Color::Green; "{name}")];
//! let line = line!["Name: ".bold(), "Remy".italic()];
//! let line = line!["bye"; 2];
//! ```
//!
//! ## Text
//!
//! The `text!` macro creates a `Text` that contains a sequence of lines. It is similar to the
//! `vec!` macro.
//!
//! ```rust
//! use ratatui_macros::{span, line, text};
//!
//! let name = "world!";
//! let text = text!["hello", format!("{name}")];
//! let text = text!["bye"; 2];
//! ```
//!
//! It is even possible to use `span!` and `line!` in the `text!` macro:
//! The [`text!`] macro creates a [`Text`] that contains a sequence of [`Line`]. It is similar to
//! the [`vec!`] macro. Each element is converted to a [`Line`] using [`Into::into`].
//!
//! ```rust
//! # use ratatui_core::style::{Modifier, Stylize};
//! use ratatui_macros::{span, line, text};
//! # use ratatui_macros::{span, line, text};
//! let name = "world!";
//! let text = text!["hello", format!("{name}")];
//! let text = text!["bye"; 2];
//! let name = "Bye!!!";
//! let text = text![line!["hello", "world".bold()], span!(Modifier::BOLD; "{name}")];
//! ```
//!
//! ## Row
//! # Layout Macros
//!
//! The `row!` macro creates a `Row` that contains a sequence of `Cell`. It is similar to the `vec!`
//! macro. A `Row` represents a sequence of `Cell`s in a single row of a table.
//! If you are new to Ratatui, check out the [Layout concepts] article on the Ratatui website before
//! proceeding.
//!
//! The [`constraints!`] macro defines an array of [`Constraint`]s:
//!
//! ```rust
//! use ratatui_macros::row;
//!
//! let rows = [
//! row!["hello", "world"],
//! row!["goodbye", "world"],
//! ];
//! # use ratatui_core::layout::Layout;
//! # use ratatui_macros::constraints;
//! let layout = Layout::horizontal(constraints![==50, ==30%, >=3, <=1, ==1/2, *=1]);
//! ```
//!
//! It is even possible to use `span!`, `line!` and `text!` in the `row!` macro:
//! The [`constraint!`] macro defines individual [`Constraint`]s:
//!
//! ```rust
//! # use ratatui_core::layout::Layout;
//! # use ratatui_macros::constraint;
//! let layout = Layout::horizontal([constraint!(==50)]);
//! ```
//!
//! The [`vertical!`] and [`horizontal!`] macros are a shortcut to defining a [`Layout`]:
//!
//! ```rust
//! # use ratatui_core::layout::Rect;
//! # use ratatui_macros::{vertical, horizontal};
//! # let area = Rect { x: 0, y: 0, width: 10, height: 10 };
//! let [top, main, bottom] = vertical![==1, *=1, >=3].areas(area);
//! let [left, main, right] = horizontal![>=20, *=1, >=20].areas(main);
//! ```
//!
//! # Table Macros
//!
//! The [`row!`] macro creates a [`Row`] for a [`Table`] that contains a sequence of [`Cell`]s. It
//! is similar to the [`vec!`] macro.
//!
//! ```rust
//! # use ratatui_core::style::{Modifier, Stylize};
//! use ratatui_macros::{span, line, text, row};
//! let name = "Bye!!!";
//! let text = row![text![line!["hello", "world".bold()]], span!(Modifier::BOLD; "{name}")];
//! # use ratatui_macros::{constraints, line, row, span, text};
//! # use ratatui_widgets::table::Table;
//! let rows = [
//! row!["hello", "world"],
//! row!["goodbye", "world"],
//! row![
//! text!["line 1", line!["Line", "2".bold()]],
//! span!(Modifier::BOLD; "Cell 2"),
//! ],
//! ];
//! let table = Table::new(rows, constraints![==20, *=1]);
//! ```
//!
//! # Contributing
@ -198,6 +133,14 @@
//! [CI Status]: https://github.com/ratatui/ratatui/actions
//! [Ratatui]: https://github.com/ratatui/ratatui
//! [Layout concepts]: https://ratatui.rs/concepts/layout
//! [`Constraint`]: ratatui_core::layout::Constraint
//! [`Layout`]: ratatui_core::layout::Layout
//! [`Span`]: ratatui_core::text::Span
//! [`Line`]: ratatui_core::text::Line
//! [`Text`]: ratatui_core::text::Text
//! [`Row`]: ratatui_widgets::table::Row
//! [`Cell`]: ratatui_widgets::table::Cell
//! [`Table`]: ratatui_widgets::table::Table
extern crate alloc;