# tui markup
[![crates.io][badge-crate-version]][crate]
[![changelog][badge-changelog]][changelog]
[![docs.rs][badge-docs-rs]][doc]
![deps state][badge-deps-state]
This crate provides a markup language to quickly write colorful and styled terminal text in plain text.
## Usage
```rust
use anstyle::{Style, AnsiColor};
use tui_markup::{compile, compile_with, generator::ANSIStringsGenerator};
// Parse markup into some final result for showing
let result = compile::<ANSIStringsGenerator>("You got a <yellow Coin>").unwrap();
// Show it
println!("{}", result);
// With custom tag
Style::new()
.fg_color(Some(AnsiColor::Blue.into()))
.bg_color(Some(AnsiColor::Black.into()))
.bold(),
),
_ => None,
});
let result = compile_with("Press <keyboard Space> to jump", generator).unwrap();
println!("{}", result);
```
Result:
![result of example][usage-screenshot]
Notice the result type and how to show it is vary depends on what `Generator` you use.
Current available [built-in generators][doc-builtin-gens]:
- `ansi`: `ANSIStringsGenerator` for directly print result in any ANSI compliant terminal.
- `ratatui`: `RatatuiTextGenerator` for create `Text` struct of `ratatui` crate to show the result.
- `crossterm`: `CrosstermCommandsGenerator` for create a series of Command of `crossterm` crate to print the result.
There is also a macro([`tui-markup-ansi-macro`] crate) to compile markup source into ANSI sequence at compile time, check it if you need.
You can add this markup support for other terminal/library/application easily by create you own generator.
## Examples
![help text][help-text-screenshot]
The example is shown in Windows Terminal, using the following command:
`cargo run --example ratatui --features ratatui,crossterm -- examples/help.txt`
The source markup text of this article can be found in [examples/help.txt].
you can change the last argument to your file to render other article, for example `examples/indexed.txt` for a full xterm256 color chart:
![color chart][indexed-screenshot]
Those two screenshot are using built-in `ratatui` generator.
## Markup syntax
Only one syntax `<taglist content>` to add style to content.
`taglist` is a `tag` list sep by `,`.
`tag` has format of `mode:value`, available `mode` are:
- `fg:` for foreground color.
- `bg:` for background color.
- `mod:` for modifiers.
Mode and `:` is optional except for `bg:`, so `66ccff` = `fg:66ccf` , and `b` = `mod:b`.
Some examples:
- `<green text>` for a green color text, `<66ccff text>` for a #66ccff color text.
- `<bg:blue text>` for a blue background text, `<bg:66ccff text>` for a #66ccff background text.
- `<b text>` for a bold text, `<i text>` for a italic/slant text.
- `<bg:blue one<green two>>`, is a blue background one followed by a blue background and green foreground two.
- `<bg:blue,green,b,i text>` is a blue background, green foreground, bold, italic text.
And you can define your own tag, like example code above.
The formal syntax spec can be found in [docs/syntax.ebnf].
Color and modifier supports vary by generator you want to use, see their document for details.
## TODO
- [ ] Generator for `termion`
- [ ] Generator for `ncurses`
## LICENSE
BSD-3-Clause-Clear, See [LICENSE].
[badge-crate-version]: https://img.shields.io/crates/v/tui-markup?style=for-the-badge
[badge-changelog]: https://img.shields.io/badge/-CHANGELOG-brightgreen?style=for-the-badge
[badge-docs-rs]: https://img.shields.io/docsrs/tui-markup?style=for-the-badge
[badge-deps-state]: https://img.shields.io/librariesio/release/cargo/tui-markup?style=for-the-badge
[crate]: https://crates.io/crates/tui-markup
[doc]: https://docs.rs/tui-markup/latest
[changelog]: https://github.com/7sDream/tui-markup/blob/master/CHANGELOG.md
[`tui-markup-ansi-macro`]: https://github.com/7sDream/tui-markup-ansi-macro
[usage-screenshot]: https://rikka.7sdre.am/files/79f88353-e689-49f6-a0fc-e8f9e373445f.png
[help-text-screenshot]: https://rikka.7sdre.am/files/ee68d36d-b1e7-4575-bb13-e37ba7ead044.png
[indexed-screenshot]: https://rikka.7sdre.am/files/788ef47c-2a8a-4667-b9b7-8f2b1b78e083.png
[doc-builtin-gens]: https://docs.rs/tui-markup/latest/tui_markup/index.html#builtin-generators
[examples/help.txt]: https://github.com/7sDream/tui-markup/blob/master/examples/help.txt
[docs/syntax.ebnf]: https://github.com/7sDream/tui-markup/blob/master/docs/syntax.ebnf
[LICENSE]: https://github.com/7sDream/tui-markup/blob/master/LICENSE