Crate termimad

Expand description

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 termimad::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, with no specific background, and bold
skin.strikeout = CompoundStyle::new(Some(Red), None, Bold.into());

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

// with the default skin, nothing simpler:
termimad::print_inline("value: **52**");

§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.

eprintln!("{}", 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. It also offers several functions to print it either on stdout or on a given Write.

§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 to 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.

§Templates

In order to separate the rendering format from the content, the format! macro is not always a good solution because you may not be sure the content is free of characters which may mess the markdown.

A solution is to use one of the templating functions or macros.

Example:

mad_print_inline!(
    &skin,
    "**$0 formula:** *$1*", // the markdown template, interpreted once
    "Disk",  // fills $0
    "2*π*r", // fills $1. Note that the stars don't mess the markdown
);

Main difference with using print!(format!( ... )):

the markdown parsing and template building are done only once (using once_cell internally)
the given values aren’t interpreted as markdown fragments and don’t impact the style
arguments can be omited, repeated, given in any order
no support for fmt parameters or arguments other than &str (in the current version)

You’ll find more examples and advice in the templates example.

§Examples

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.

Re-exports§

pub use crate::Error;
pub use coolor;
pub use crokey::crossterm;
pub use crossbeam;
pub use minimad;

Modules§

wrap

Macros§

ask: ask the user to choose among proposed answers.
mad_print_inline: print a markdown template, with other arguments taking $0 to $9 places in the template.
mad_write_inline: write a markdown template, with other arguments taking $0 to $9 places in the template.

Structs§

Answer: one of the proposed answers to a question
Area: A rectangular part of the screen
CompoundStyle: A style which may be applied to a compound
CropWriter: wrap a writer to ensure that at most allowed columns are written.
DisplayableLine: A facility to write just a line of a text.
EventSource: a thread backed event listener emmiting events on a channel.
EventSourceOptions
Filling: something to fill with
Fitter: A fitter can shorten a composite to make it fit a target width without wrapping (by removing parts and replacing them with ellipsis)
FmtComposite: Wrap Minimad compounds with their style and termimad specific information
FmtInline: A directly printable markdown snippet, complete with the reference to a skin so that it can implement the Display trait.
FmtTableRow: Wrap a standard table row
FmtTableRule: A separator or alignment rule in a table.
FmtText: a formatted text, implementing Display.
InputField: A simple input field, managing its cursor position and either handling the events you give it or being managed through direct manipulation functions (put_char, del_char_left, etc.).
InsufficientWidthError: Error thrown when fitting isn’t possible
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 markdown 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
Question: a question that can be asked to the user, requiring him to type the key of the desired answer
Rect: A drawable rect, with various types of borders and an optional filling.
RectBorderStyle
ScrollBarStyle: A scrollbar style defined by two styled chars, one for the track, and one for the thumb.
Spacing
StrFit: Information about the fitting of a string into a given width in cols.
StyledChar: A modifiable character which can be easily written or repeated. Can be used for bullets, horizontal rules or quote marks.
TableBorderChars: The set of characters to use to render table borders
TblFit: A fitter, accumulating data about the table which must fit into a given width, then computing the best column widths.
TblFitResult: Result of the fitting operation (always a success)
TextView: A scrollable text, in a specific area.
Ticker: A tick generator, sending a paylod of your choice (can be () for a simple timer) at regular inverval, once, several times or infinitely.
TimedEvent: A user event based on a crossterm event, decorated

Enums§

Alignment: Left, Center, Right or Unspecified
CompositeKind: The global kind of a composite
Error: Termimad error type
FmtLine: A line in a text. This structure should normally not be used outside of the lib.
ListItemsIndentationMode: Describe how list items are indented when the item has to be wrapped: either only the first line (the one with the bullet) or the whole item as a block.
ParseAlignError
ParseAttributeError
ParseColorError
ParseStyleTokenError
RelativePosition: Top, Bottom, or other
StyleToken: something which may be part of a style

Statics§

ASCII_TABLE_BORDER_CHARS: For tables made only of ASCII (not extended)
ATTRIBUTES: The attributes which are often supported
BORDER_STYLE_BLAND
BORDER_STYLE_HALF_WIDTH_OUTSIDE
BORDER_STYLE_MIDDLE_ROUND_LINE
BORDER_STYLE_MIDDLE_SQUARE_LINE
DEFAULT_TAB_REPLACEMENT
ELLIPSIS
ROUNDED_TABLE_BORDER_CHARS: Allow tables to be more rounded
SPACE_FILLING
STANDARD_TABLE_BORDER_CHARS: Default square tables
TAB_REPLACEMENT

Traits§

PushStyleTokens

Functions§

ansi: Build an ANSI color
compute_scrollbar: Compute the min and max y (from the top of the terminal, both inclusive) for the thumb part of the scrollbar which would represent the scrolled content in the available height.
fill_bg
fix_all_tables: Modify the rows of all tables in order to ensure it fits the widths and all cells have the widths of their column.
get_default_skin: Return a reference to the global skin
gray: Build a gray-level color, from 0 (mostly dark) to 23 (light).
inline: Return a formatted line, which implements Display.
parse_align: Read a Minimad Alignment from a string.
parse_attribute: Read a Minimad Attributement from a string.
parse_color: Read a Crossterm color from a string.
parse_compound_style: Read a Minimad CompoundStyle from a string.
parse_line_style: Read a line_style from a string.
parse_style_token
parse_style_tokens
parse_styled_char: Read a styled char from a string.
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
style_tokens_to_string
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.
write_align
write_attribute
write_color
write_style_tokens

Type Aliases§

TickBeamId

Crate termimadCopy item path