tui_markup/generator/
mod.rs

1//! Generator generates final output for showing.
2
3pub mod helper;
4mod tag;
5
6#[cfg(feature = "ratatui")]
7#[cfg_attr(docsrs, doc(cfg(feature = "ratatui")))]
8pub mod ratatui;
9#[cfg(feature = "ratatui")]
10pub use self::ratatui::RatatuiTextGenerator;
11
12#[cfg(feature = "ansi")]
13#[cfg_attr(docsrs, doc(cfg(feature = "ansi")))]
14pub mod ansi;
15#[cfg(feature = "ansi")]
16pub use self::ansi::ANSIStringsGenerator;
17
18#[cfg(feature = "crossterm")]
19#[cfg_attr(docsrs, doc(cfg(feature = "crossterm")))]
20pub mod crossterm;
21#[cfg(feature = "crossterm")]
22pub use self::crossterm::CrosstermCommandsGenerator;
23
24// TODO: crossterm generator
25// TODO: termion generator
26
27use std::fmt::{Debug, Display};
28
29use crate::{error::LocatedError, parser::ItemG, Error};
30
31pub use tag::{Tag, TagConvertor, TagG};
32
33/// Generator generates final output to show tui markup in some backend.
34///
35/// ## How to add support for new backend
36///
37/// Some concepts:
38///
39/// - Markup text/Source: the text you write in tui markup language.
40/// - [Parser][crate::parser::parse]: parse markup text into a series of [Item][crate::parser::Item],
41///   which usually be called as AST.
42/// - [Tag Convertor][TagConvertor]: Convert raw tag string like `green`, `bg:66ccff`, `mod:b` into [Tag].
43/// - [Generator]: generator final output from `Item<Tag>`.
44///
45/// So the whole pipeline is:
46///
47/// ```none
48/// Source --- Parser --> Item --- Tag Convertor --> Item<Tag> --- Generator --> Output --> Show it in some backend
49/// ```
50///
51/// The source, parser, Item, Tag, is already defined, so just write a [Tag Convertor][TagConvertor]
52/// and a [Generator], a new backend will be supported.
53///
54/// ## Generic implementation using flatten
55///
56/// Your tag convertor will parse color/modifiers string to some `Color`/`Modifier` type, and will support custom tag
57/// by a `Style` type, which can be converted from `Color` and `Modifier` too.
58///
59/// In this case, a [Tag] of this convertor can be convert to the `Style` type easily.
60///
61/// If this `Style` can be patched by other, then you can use the [`flatten`][helper::flatten]
62/// help method to do almost all the convert staff from AST to your final result.
63///
64/// Read document of [`flatten`][helper::flatten] to learn more, or just checkout a builtin implementation.
65pub trait Generator<'a> {
66    /// Tag convertor type.
67    type Convertor: TagConvertor<'a>;
68
69    /// Output type.
70    type Output;
71
72    /// Error type.
73    ///
74    /// If the generator can't fall, please use [`GeneratorInfallible`][helper::GeneratorInfallible].
75    type Err: LocatedError + Display + Debug + Into<Error<'a, Self::Err>>;
76
77    /// Get the tag convertor.
78    fn convertor(&mut self) -> &mut Self::Convertor;
79
80    /// Generates final output from IR, which is output result of the Convertor.
81    ///
82    /// ## Errors
83    ///
84    /// When the generator can't process the IR. This should be documented details.
85    fn generate(&mut self, ir: Vec<Vec<ItemG<'a, Self>>>) -> Result<Self::Output, Self::Err>;
86}
87
88impl<'a, G: Generator<'a>> Generator<'a> for &mut G {
89    type Convertor = G::Convertor;
90
91    type Output = G::Output;
92
93    type Err = G::Err;
94
95    fn convertor(&mut self) -> &mut Self::Convertor {
96        <G as Generator<'a>>::convertor(self)
97    }
98
99    fn generate(&mut self, ir: Vec<Vec<ItemG<'a, G>>>) -> Result<Self::Output, Self::Err> {
100        <G as Generator<'a>>::generate(self, ir)
101    }
102}
tui_markup/generator/mod.rs

tui_markup/generator/
mod.rs
