Crate stylish

Source

Expand description

Yet another crate implementing colorized text.

There was one primary design goal separating stylish from existing crates:

Applying styling to data should be decoupled from how that styling is output.

This came out of two usecases:

A library crate that renders a “diagnostic” representation of a data format (think something JSON-like). This library is being used in both a WASM based web application and a CLI application; in both cases these applications would be improved by adding some syntax highlighting to the rendered data, but in one case we want to output HTML while the other requires ANSI color codes.
A (different) CLI application which could use semantic coloring of different data types embedded in the output messages to make them easier to parse, with an option to turn the color off. To simplify toggling the color the rendering of the messages shouldn’t need to continuously check whether color is currently on or not.

Along with this primary design goal, there was a secondary design goal:

Integrate into std::fmt as much as possible to leverage existing knowledge.

We already have a standardized formatting infrastructure in std::fmt. Developers already know how to work with this, and it is very easy to use. By reusing that existing design and just extending it where needed it should be trivial to get started with stylish.

§Writing data with attributes

There are two primary mechanisms you can use to output data with attached attributes; either applying the attributes as part of the format string, or implementing stylish::Display to be able to print some type with attributes.

§Applying attributes in format string

stylish’s macros extend the standard fmt parameters to support setting attributes within (). These must come at the end of the parameters just before selecting which trait.

assert_eq!(
    stylish::html::format!("Hello {:(fg=red)}", "Ferris"),
    "Hello <span style=color:red>Ferris</span>",
);

§Allowed attributes

There are two parameterised attributes, and 3 non-parameterised attributes:

fg specifies a Foreground style and takes a Color value in lowercase
bg specifies a Background style and also takes a Color value in lowercase
bold, normal and faint take no parameters and specify an Intensity style

§Syntax change

The specific syntax change is extending format_spec like so:

format_spec := [[fill]align][sign]['#']['0'][width]['.' precision][attributes]type
attributes := '(' [attribute [',' attribute]* [',']] ')'
attribute := key ['=' value]
key := identifier
value := identifier

§Implementing a style for a type

stylish::Display is similar to std::fmt::Display but with a Formatter that supports setting style attributes. It can be specified by using the trait-selector s in a format string. See the Formatter docs for more details on how you can programmatically set the styles as you write out your data.

struct Name(&'static str);

impl stylish::Display for Name {
    fn fmt(&self, f: &mut stylish::Formatter<'_>) -> stylish::Result {
        let color = match self.0 {
            "Ferris" => stylish::Color::Red,
            "Gorris" => stylish::Color::Cyan,
            _ => stylish::Color::Default,
        };
        f.with(stylish::Foreground(color)).write_str(self.0)
    }
}

assert_eq!(
    stylish::html::format!("Hello {:s} and {:s}", Name("Ferris"), Name("Gorris")),
    "Hello <span style=color:red>Ferris</span> and <span style=color:cyan>Gorris</span>",
);

§Features

Feature	Activation	Effect
`std`	on-by-default	Enables the `io` module (and `io` helpers in other modules)
`alloc`	implied by `std`	Enables `String` and a variety of items that use it
`macros`	on-by-default	Enables macros throughout the other enabled modules
`ansi`	off-by-default	Enables the `ansi` module and items that use it
`html`	off-by-default	Enables the `html` module and items that use it
`plain`	off-by-default	Enables the `plain` module and items that use it

§Rust Version Policy

This crate only supports the current stable version of Rust, patch releases may use new features at any time.

§License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be dual licensed as above, without any additional terms or conditions.

Modules§

ansiansi: Helpers for writing styles as ANSI escape codes.
htmlhtml: Helpers for writing styles as HTML elements.
iostd: Traits and associated types for writing attributed data to fallible IO sinks.
plainplain: Helpers for discarding styles.

Macros§

formatalloc: Create a [stylish::String] using interpolation of runtime elements.
format_argsmacros: Constructs parameters for the other string-formatting macros.
writemacros: Writes attributed and formatted data into a buffer.
writelnmacros: Write attributed and formatted data into a buffer, with a newline appended.

Structs§

Ansiansi: An adaptor to allow writing [stylish] attributed data to an output stream by turning attributes into inline ANSI escape codes.
Arguments: A precompiled version of a format string and its by-reference arguments.
Background: A Restyle implementor for setting Style::background.
Error: The error type which is returned from formatting a message into a stream.
Foreground: A Restyle implementor for setting Style::foreground.
Formatter: A configured output stream.
Htmlhtml: An adaptor to allow writing [stylish] attributed data to an output stream by turning attributes into HTML elements.
Plainplain: An adaptor to allow writing [stylish] attributed data to an output stream by discarding style attributes.
Stringalloc: An attributed version of alloc::string::String which has a specific Style associated with each character.
Style: A style to render text with, setting the foreground and background colors, along with intensity.
StyleDiff: A diff between two styles.

Enums§

Color: A color that can be used with Foreground to modify Style::foreground or Background to modify Style::background.
Intensity: An intensity to render text with, to emphasise or de-emphasise it as needed.

Traits§

Display: Format trait for the stylish format, {:s}.
Restyle: A trait for modifications to Style, allowing an ergonomic API with Style::with and stylish::Formatter::with.
ToAnsiStringansi and alloc and macros: A trait for converting a value to a String with integrated ANSI styling.
ToHtmlStringhtml and alloc and macros: A trait for converting a value to a String with integrated HTML styling.
ToPlainStringplain and alloc and macros: A trait for converting a value to a String without styling.
ToStylishStringalloc and macros: A trait for converting a value to a [stylish::String].
Write: A trait for writing or formatting into attributed Unicode-accepting buffers or streams.

Functions§

ansiansi: An alias for stylish::Ansi::new for more succinct code.
formatalloc: The format function takes a [stylish::Arguments] struct and returns the resulting attributed and formatted [stylish::String].
htmlhtml: An alias for stylish::Html::new for more succinct code.
plainplain: An alias for stylish::Plain::new for more succinct code.

Type Aliases§

Result: The type returned by formatter methods.

Crate stylishCopy item path