itsscb/ratatui
1
0
Fork 0
mirror of https://github.com/ratatui/ratatui.git synced 2025-09-26 20:40:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix: ratatui-macros readme and doc links

Browse Source
This commit is contained in:
Josh McKinney 2025-02-05 13:33:19 -08:00
parent d4415204e1
commit e48bcf5f21
No known key found for this signature in database
GPG Key ID: 722287396A903BC5
7 changed files with 256 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
ratatui-macros/README.md
View File

@ -1,20 +1,26 @@
# Ratatui Macros
[![Crates.io badge]][ratatui_macros crate] [![License badge]](./LICENSE)
[![Docs.rs badge]][API Docs] [![CI Badge]][CI Status]
[![Crates.io badge]][ratatui_macros crate]
[![License badge]](./LICENSE)
[![Docs.rs badge]][API Docs]
[![CI Badge]][CI Status]
[![Crate Downloads badge]][ratatui_macros crate]
<!-- ⚠️ DO NOT EDIT THIS FILE DIRECTLY, EDIT lib.rs AND THEN RUN `cargo rdme` to update this file. -->
<!-- cargo-rdme start -->
`ratatui-macros` is a Rust crate that provides easy-to-use macros for simplifying boilerplate
associated with creating UI using [Ratatui].
This is an experimental playground for us to explore macros that would be useful to have in Ratatui
proper.
This is an experimental playground for us to explore macros that would be useful to have in
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.
- 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.
## Getting Started
@ -38,14 +44,16 @@ use ratatui_macros::{
};
```
## Macros
### Layout
If you are new to Ratatui, check out the [Layout concepts] article on the Ratatui website before proceeding.
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!(
@ -62,7 +70,6 @@ assert_eq!(
```
```rust
# use ratatui_core::layout::Constraint;
use ratatui_macros::constraints;
assert_eq!(
@ -79,7 +86,6 @@ assert_eq!(
Use the `constraint!` macro to define individual constraints:
```rust
# use ratatui_core::layout::Constraint;
use ratatui_macros::constraint;
assert_eq!(
@ -91,7 +97,6 @@ assert_eq!(
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 };
@ -107,14 +112,13 @@ assert_eq!(left.width, 3);
assert_eq!(right.width, 3);
```
## Spans
### 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.
`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_core::style::{Color, Modifier, Style, Stylize};
use ratatui_macros::span;
let name = "world!";
@ -124,10 +128,10 @@ let styled_greeting = span!(Color::Green; "hello {name}");
let styled_greeting = span!(Modifier::BOLD; "hello {name}");
```
## Line
### 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 spans. It is similar to the
`vec!` macro.
```rust
use ratatui_macros::line;
@ -137,10 +141,10 @@ let line = line!["hello", format!("{name}")];
let line = line!["bye"; 2];
```
## Text
### 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 lines. It is similar to the
`vec!` macro.
```rust
use ratatui_macros::{span, line, text};
@ -153,13 +157,12 @@ let text = text!["bye"; 2];
It is even possible to use `span!` and `line!` in the `text!` macro:
```rust
# use ratatui_core::style::{Modifier, Stylize};
use ratatui_macros::{span, line, text};
let name = "Bye!!!";
let text = text![line!["hello", "world".bold()], span!(Modifier::BOLD; "{name}")];
```
## Row
### Row
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.
@ -176,7 +179,6 @@ let rows = [
It is even possible to use `span!`, `line!` and `text!` in the `row!` 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}")];
@ -190,11 +192,14 @@ request, or a pull request, all forms of contributions are valued and appreciate
[Crates.io badge]: https://img.shields.io/crates/v/ratatui-macros?logo=rust&style=flat-square
[License badge]: https://img.shields.io/crates/l/ratatui-macros
[CI Badge]:
https://img.shields.io/github/actions/workflow/status/ratatui-org/ratatui-macros/ci.yml?logo=github&style=flat-square
https://img.shields.io/github/actions/workflow/status/ratatui/ratatui/ci.yml?logo=github&style=flat-square
[Docs.rs badge]: https://img.shields.io/docsrs/ratatui-macros?logo=rust&style=flat-square
[Crate Downloads badge]: https://img.shields.io/crates/d/ratatui-macros?logo=rust&style=flat-square
[Crate Downloads badge]:
https://img.shields.io/crates/d/ratatui-macros?logo=rust&style=flat-square
[ratatui_macros crate]: https://crates.io/crates/ratatui-macros
[API Docs]: https://docs.rs/ratatui-macros
[CI Status]: https://github.com/kdheepak/ratatui-macros/actions
[Ratatui]: https://github.com/ratatui-org/ratatui
[CI Status]: https://github.com/ratatui/ratatui/actions
[Ratatui]: https://github.com/ratatui/ratatui
[Layout concepts]: https://ratatui.rs/concepts/layout
<!-- cargo-rdme end -->

6
ratatui-macros/src/layout.rs
View File

@ -15,6 +15,8 @@
/// assert_eq!(constraint!(== 10 %), Constraint::Percentage(10));
/// assert_eq!(constraint!(*= 1), Constraint::Fill(1));
/// ```
///
/// [`constraints!`]: crate::constraints
#[macro_export]
macro_rules! constraint {
(== $token:tt %) => {
@ -67,6 +69,10 @@ macro_rules! constraint {
/// ]
/// )
/// ```
///
/// [`constraint!`]: crate::constraint
/// [`vertical!`]: crate::vertical
/// [`horizontal!`]: crate::horizontal
#[macro_export]
macro_rules! constraints {
// Note: this implementation forgoes speed for the sake of simplicity. Adding variations of the

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

@ -1,5 +1,202 @@
#![doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/README.md"))]
//! `ratatui-macros` is a Rust crate that provides easy-to-use macros for simplifying boilerplate
//! associated with creating UI using [Ratatui].
//!
//! This is an experimental playground for us to explore macros that would be useful to have in
//! 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.
//!
//! # Getting Started
//!
//! To use `ratatui-macros` in your Rust project, add it as a dependency in your `Cargo.toml`:
//!
//! ```shell
//! cargo add ratatui-macros
//! ```
//!
//! Then, import the macros in your Rust file:
//!
//! ```rust
//! use ratatui_macros::{
//! constraint,
//! constraints,
//! horizontal,
//! vertical,
//! span,
//! line,
//! };
//! ```
//!
//! # 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.
//!
//! ```rust
//! # use ratatui_core::style::{Color, Modifier, Style, Stylize};
//! 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}");
//! ```
//!
//! ## Line
//!
//! The `line!` macro creates a `Line` that contains a sequence of spans. It is similar to the
//! `vec!` macro.
//!
//! ```rust
//! use ratatui_macros::line;
//!
//! let name = "world!";
//! let line = line!["hello", format!("{name}")];
//! 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:
//!
//! ```rust
//! # use ratatui_core::style::{Modifier, Stylize};
//! use ratatui_macros::{span, line, text};
//! let name = "Bye!!!";
//! let text = text![line!["hello", "world".bold()], span!(Modifier::BOLD; "{name}")];
//! ```
//!
//! ## Row
//!
//! 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.
//!
//! ```rust
//! use ratatui_macros::row;
//!
//! let rows = [
//! row!["hello", "world"],
//! row!["goodbye", "world"],
//! ];
//! ```
//!
//! It is even possible to use `span!`, `line!` and `text!` in the `row!` 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}")];
//! ```
//!
//! # Contributing
//!
//! Contributions to `ratatui-macros` are welcome! Whether it's submitting a bug report, a feature
//! request, or a pull request, all forms of contributions are valued and appreciated.
//!
//! [Crates.io badge]: https://img.shields.io/crates/v/ratatui-macros?logo=rust&style=flat-square
//! [License badge]: https://img.shields.io/crates/l/ratatui-macros
//! [CI Badge]:
//! https://img.shields.io/github/actions/workflow/status/ratatui/ratatui/ci.yml?logo=github&style=flat-square
//! [Docs.rs badge]: https://img.shields.io/docsrs/ratatui-macros?logo=rust&style=flat-square
//! [Crate Downloads badge]:
//! https://img.shields.io/crates/d/ratatui-macros?logo=rust&style=flat-square
//! [ratatui_macros crate]: https://crates.io/crates/ratatui-macros
//! [API Docs]: https://docs.rs/ratatui-macros
//! [CI Status]: https://github.com/ratatui/ratatui/actions
//! [Ratatui]: https://github.com/ratatui/ratatui
//! [Layout concepts]: https://ratatui.rs/concepts/layout
mod layout;
mod line;
mod row;

5
ratatui-macros/src/line.rs
View File

@ -30,8 +30,9 @@
/// let line = line![span!("hello {}", "world"), span!(Modifier::BOLD; "goodbye {}", "world")];
/// ```
///
/// [`Line`]: crate::text::Line
/// [`Span`]: crate::text::Span
/// [`span!`]: crate::span
/// [`Line`]: ratatui_core::text::Line
/// [`Span`]: ratatui_core::text::Span
#[macro_export]
macro_rules! line {
() => {

8
ratatui-macros/src/row.rs
View File

@ -40,8 +40,12 @@
/// ];
/// ```
///
/// [`Row`]: crate::widgets::Row
/// [`Cell`]: crate::widgets::Cell
/// [`text!`]: crate::text
/// [`line!`]: crate::line
/// [`span!`]: crate::span
/// [`row!`]: crate::row
/// [`Row`]: ratatui_widgets::table::Row
/// [`Cell`]: ratatui_widgets::table::Cell
#[macro_export]
macro_rules! row {
() => {

7
ratatui-macros/src/span.rs
View File

@ -88,10 +88,9 @@
/// let span = span!("hello {}", "world");
/// ```
///
/// [`Color`]: crate::style::Color
/// [`Style`]: crate::style::Style
/// [`Span`]: crate::text::Span
/// [`Style`]: crate::style::Style
/// [`Color`]: ratatui_core::style::Color
/// [`Span`]: ratatui_core::text::Span
/// [`Style`]: ratatui_core::style::Style
#[macro_export]
macro_rules! span {
($string:literal) => {

8
ratatui-macros/src/text.rs
View File

@ -30,9 +30,11 @@
/// let text = text![line!["hello", "world"], span!(Modifier::BOLD; "goodbye {}", "world")];
/// ```
///
/// [`Text`]: crate::text::Text
/// [`Line`]: crate::text::Line
/// [`Span`]: crate::text::Span
/// [`span!`]: crate::span
/// [`text!`]: crate::text
/// [`Text`]: ratatui_core::text::Text
/// [`Line`]: ratatui_core::text::Line
/// [`Span`]: ratatui_core::text::Span
#[macro_export]
macro_rules! text {
() => {