[−][src]Crate text_style

The text_style crate provides types and conversions for styled text.

Overview

The central types of this crate are StyledStr and StyledString: owned and borrowed strings that are annotated with an optional style information, Style. This style information consists of foreground and background colors (Color) and multiple effects (Effect: bold, italic or underline).

text_style’s types can be created directly or converted from or to several formats (all optional and activated by features):

ansi_term: convert to ansi_term::ANSIString
crossterm: convert to crossterm::style::StyledContent
cursive: convert to cursive::utils::markup::StyledString
syntect: convert from syntect::highlighting::Style
termion: convert to a termion escape string

Background

There is a plethora of crates that produce or consume styled text. Most of these crates use very similar types: ANSI and RGB colors, text effects, styled strings. But converting between these types requires a lot of boilerplate code. The goal of this crate is to provide a subset of common style types to enable conversion between the different crates.

Usage

Creating styled text

The StyledString and StyledStr structs provide many utility methods for creating styled strings easily:

use text_style::{AnsiColor, Effect, StyledStr};
let s = StyledStr::plain("text")
    .with(AnsiColor::Red.light())
    .on(AnsiColor::Green.dark())
    .bold();
text_style::ansi_term::render(std::io::stdout(), s)
    .expect("Could not render line");

If the syntect feature is activated, conversion traits from syntect’s style types are implemented:

use syntect::{easy, parsing, highlighting, util};

let ps = parsing::SyntaxSet::load_defaults_newlines();
let ts = highlighting::ThemeSet::load_defaults();

let syntax = ps.find_syntax_by_extension("rs").unwrap();
let mut h = easy::HighlightLines::new(syntax, &ts.themes["base16-ocean.dark"]);
let s = "pub struct Wow { hi: u64 }\nfn blah() -> u64 {}";
for line in util::LinesWithEndings::from(s) {
    let ranges: Vec<(highlighting::Style, &str)> = h.highlight(line, &ps);
    text_style::ansi_term::render_iter(std::io::stdout(), ranges.iter())
        .expect("Could not render line");
}

Rendering styled text

All backends (except cursive) define render and render_iter methods to display a styled string or an iterator over styled strings:

let s = text_style::StyledStr::plain("test").bold();

let mut w = std::io::stdout();
text_style::ansi_term::render(&mut w, &s).expect("Rendering failed");
text_style::crossterm::render(&mut w, &s).expect("Rendering failed");
text_style::termion::render(&mut w, &s).expect("Rendering failed");

For more information, see the module documentations.

Modules

ansi_term	Conversion methods for `ansi_term`’s text style types.
crossterm	Conversion methods for `crossterm`’s text style types.
cursive	Conversion methods for `cursive`’s text style types.
syntect	Conversion methods for `syntect`’s text style types.
termion	Conversion methods for `termion`’s text style types.

Structs

Effects	A set of text effects.
EffectsIter	An iterator over text effects.
Style	A text style, a combination of a foreground color, a background color and text effects (all optional).
StyledStr	A borrowed string with an optional style annotation.
StyledString	An owned string with an optional style annotation.

Enums

AnsiColor	An ANSI base color.
AnsiMode	An ANSI color mode.
Color	A color.
Effect	A text effect.

Constants

EFFECTS

All available text effects.