tui_markup/
lib.rs

1#![forbid(unsafe_code)]
2#![cfg_attr(docsrs, feature(doc_cfg))]
3//! # tui markup
4//!
5//! This crate provides a markup language to
6//! quickly write colorful and styled terminal text in plain text.
7//!
8//! I suggest to check [examples/help.txt], which generated this self-describing
9//! syntax help document:
10//!
11//! ![][help-text-screenshot]
12//!
13//! For formal syntax specification, see [docs/syntax.ebnf].
14//!
15//! ## How to use
16//!
17//! ```ignore
18//! let output = tui_markup::compile::<Generator>("<bg:blue,green,b hello>").unwrap();
19//! ```
20//!
21//! The string wrapped in `<>`(like the `bg:blue,green,b` in above example) is
22//! called a element, start with a tag list(comma separated), those tags add
23//! styles to inner items.
24//!
25//! Usable tags are vary depending on the the [Generator] you use,
26//! and generator will ignore all tags it does not understand.
27//!
28//! So it's better checkout their document before write your markup text.
29//!
30//! ### Builtin generators
31//!
32//! The builtin generators are under feature gates:
33//!
34//! | feature     | Target                                                          | generator type                                                        |
35//! | :---------- | :-------------------------------------------------------------- | :-------------------------------------------------------------------- |
36//! | `ansi`      | Direct print into stdout when using an asni compatible terminal | [`ANSIStringsGenerator`][generator::ANSIStringsGenerator]             |
37//! | `ratatui`   | Integrated with the [ratatui] crate                             | [`RatatuiTextGenerator`][generator::RatatuiTextGenerator]             |
38//! | `crossterm` | Integrated with [crossterm] crate                               | [`CrosstermCommandsGenerator`][generator::CrosstermCommandsGenerator] |
39//!
40//! The example screenshot above is using the `ratatui` generator, print in
41//! Windows Terminal.
42//!
43//! If you want write your own generator, please checkout documents of
44//! [Generator] trait.
45//!
46//! [docs/syntax.ebnf]: https://github.com/7sDream/tui-markup/blob/master/docs/syntax.ebnf
47//! [help-text-screenshot]: https://rikka.7sdre.am/files/ee68d36d-b1e7-4575-bb13-e37ba7ead044.png
48//! [examples/help.txt]: https://github.com/7sDream/tui-markup/blob/master/examples/help.txt
49//! [ratatui]: https://docs.rs/ratatui/latest/ratatui/
50
51mod error;
52pub mod generator;
53pub mod parser;
54
55pub use error::{Error, LocatedError};
56pub use generator::Generator;
57use generator::TagConvertor;
58
59/// Parse markup language source, then generate final output using the default
60/// configure of a generator type.
61///
62/// See document of generator type for examples.
63///
64/// ## Errors
65///
66/// If input source contains invalid syntax or generator failed.
67pub fn compile<'a, G>(s: &'a str) -> Result<G::Output, Error<'a, G::Err>>
68where
69    G: Generator<'a> + Default,
70{
71    compile_with(s, G::default())
72}
73
74/// Parse markup language source, then generate final output using the provided
75/// generator.
76///
77/// See document of generator type for examples.
78///
79/// ## Errors
80///
81/// If input source contains invalid syntax or generator failed.
82pub fn compile_with<'a, G>(s: &'a str, mut generator: G) -> Result<G::Output, Error<'a, G::Err>>
83where
84    G: Generator<'a>,
85{
86    let ast = parser::parse(s)?;
87    let ir = generator.convertor().convert_ast(ast);
88    match generator.generate(ir) {
89        Ok(result) => Ok(result),
90        Err(err) => Err(err.into()),
91    }
92}
tui_markup/lib.rs

tui_markup/
lib.rs
