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 aForeground
style and takes aColor
value in lowercase -
bg
specifies aBackground
style and also takes aColor
value in lowercase -
bold
,normal
andfaint
take no parameters and specify anIntensity
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
ansi
Helpers for writing styles as ANSI escape codes.
html
Helpers for writing styles as HTML elements.
std
Traits and associated types for writing attributed data to fallible IO sinks.
plain
Helpers for discarding styles.
Macros
alloc
and macros
Create a stylish::String
using interpolation of runtime elements.
macros
Constructs parameters for the other string-formatting macros.
macros
Writes attributed and formatted data into a buffer.
macros
Write attributed and formatted data into a buffer, with a newline appended.
Structs
ansi
An adaptor to allow writing stylish
attributed data to an output stream
by turning attributes into inline ANSI escape codes.
A precompiled version of a format string and its by-reference arguments.
A Restyle
implementor for setting Style::background
.
The error type which is returned from formatting a message into a stream.
A Restyle
implementor for setting Style::foreground
.
A configured output stream.
html
An adaptor to allow writing stylish
attributed data to an output stream
by turning attributes into HTML elements.
plain
An adaptor to allow writing stylish
attributed data to an output stream
by discarding style attributes.
alloc
An attributed version of alloc::string::String
which has a specific
Style
associated with each character.
A style to render text with, setting the foreground and background colors, along with intensity.
A diff between two styles.
Enums
A color that can be used with Foreground
to modify Style::foreground
or Background
to modify Style::background
.
An intensity to render text with, to emphasise or de-emphasise it as needed.
Traits
Format trait for the stylish
format,
{:s}
.
A trait for modifications to Style
, allowing an ergonomic API with
Style::with
and stylish::Formatter::with
.
ansi
and alloc
and macros
A trait for converting a value to a String
with integrated ANSI styling.
html
and alloc
and macros
A trait for converting a value to a String
with integrated HTML styling.
plain
and alloc
and macros
A trait for converting a value to a String
without styling.
alloc
and macros
A trait for converting a value to a stylish::String
.
A trait for writing or formatting into attributed Unicode-accepting buffers or streams.
Functions
ansi
An alias for stylish::Ansi::new
for more succinct code.
alloc
The format
function takes a stylish::Arguments
struct and returns the
resulting attributed and formatted stylish::String
.
html
An alias for stylish::Html::new
for more succinct code.
plain
An alias for stylish::Plain::new
for more succinct code.
Type Definitions
The type returned by formatter methods.