[−][src]Crate termimad
This crate lets you display simple markdown snippets or scrollable wrapped markdown texts in the terminal.
In order to use Termimad you typically need
- some markdown, a string which you can have loaded or dynamically built
- a skin, which defines the colors and style attributes of every parts
Additionnaly, you might define an area of the screen in which to draw (and maybe scroll).
The skin
It's an instance of MadSkin
whose fields you customize according
to your tastes or (better) to your application's configuration.
use crossterm_style::{Color::*, Attribute::*}; use termimad::*; // start with the default skin let mut skin = MadSkin::default(); // let's decide bold is in light gray skin.bold.set_fg(gray(20)); // let's make strikeout not striked out but red skin.strikeout = CompoundStyle::new(Some(Red), None, vec![Bold]);
Beware:
- you may define colors in full
rgb
but this will limit compatibility with old terminals. It's recommended to stick to Ansi colors, gray levels, or Crossterm predefined values. - styles are composed. For example a word may very well be italic, bold and striked out. It might not be wise to have them differ only by their background color for example.
Display a simple inline snippet
use crossterm_cursor::TerminalCursor; // with the default skin, nothing simpler: termimad::print_inline("value: **52**"); // now in a precise position // (assuming an alternate terminal, see the "scrollable" example) // and with the skin we precedently customized: let cursor = TerminalCursor::new(); cursor.goto(0, 4).unwrap(); skin.print_inline("page *3* / 5");
Print a text
A multi-line markdown string can be printed the same way than an inline snippet, but you usually want it to be wrapped according to the available terminal width.
println!("{}", skin.term_text(my_markdown));
MadSkin
contains other functions to prepare a text for no specific size or for one which isn't the terminal's width.
Display a text, maybe scroll it
A terminal application often uses an alternate screen instead of just dumping its text to stdout, and you often want to display in a specific rect of that screen, with adequate wrapping and not writing outside that rect.
You may also want to display a scrollbar if the text doesn't fit the area. A MadView
makes that simple:
let area = Area::new(0, 0, 10, 12); let mut view = MadView::from(markdown, area, skin); view.write().unwrap();
If you don't want give ownership of the skin, markdown and area, you may prefer to use a TextView
.
You may see how to write a text viewer responding to key inputs to scroll a markdown text in the scrollable example.
The repository contains several other examples, which hopefully cover the whole API while being simple enough. It's recommended you start by trying them or at least glance at their code.
Structs
Area | A rectangular part of the screen |
CompoundStyle | A style which may be applied to a compound |
EventSource | a thread backed event listener emmiting events on a channel. |
FmtComposite | Wrap a Minimad Composite, which is a list of Compounds (which are strings with an homogeneous style) |
FmtInline | A directly printable markdown snippet, complete with the reference to a skin so that it can implement the Display trait. |
FmtText | a formatted text, implementing Display |
InputField | A simple input field, managing its cursor position. |
LineStyle | A style applicable to a type of line. |
ListView | A filterable list whose columns can be automatically resized. |
ListViewCell | |
ListViewColumn | |
MadSkin | A skin defining how a parsed mardkown appears on the terminal (fg and bg colors, bold, italic, underline, etc.) |
MadView | A MadView is like a textview but it owns everything, from the source markdown to the area and the skin, which often makes it more convenient for dynamic texts. It's also resizeable. |
ProgressBar | A pixel precise horizontal bar |
ScrollBarStyle | A scrollbar style defined by two styled chars, one for the track, and one for the thumb. |
Spacing | |
StyledChar | A modifiable character which can be easily written or repeated. Can be used for bullets, horizontal rules or quote marks. |
TextView | A scrollable text, in a specific area. |
Enums
Alignment | |
Event | a valid user event |
FmtLine | A line in a text. This structure should normally not be used outside of the lib. |
Functions
ansi | Build an ANSI color |
compute_scrollbar | |
get_default_skin | Return a reference to the global skin (modifiable). |
gray | Build a gray-level color, from 0 (dark) to 23 (light). |
inline | Return a formatted line, which implements Display. |
print_inline | Write a string interpreted as markdown with the default skin. |
print_text | Write a text interpreted as markdown with the default skin. |
rgb | Build a RGB color |
term_text | Return a terminal wrapped formatted text, implementing Display. |
terminal_size | Return a (width, height) with the dimensions of the available terminal in characters. |
text | Return an unwrapped formatted text, implementing Display. |