Expand description
parse-style
is a Rust library for parsing &
displaying strings describing styles for terminal text using a syntax
compatible with the Python library
rich
.
use parse_style::{Color256, Style};
assert_eq!(
"bold red on blue".parse::<Style>().unwrap(),
Style::new()
.foreground(Some(Color256::RED.into()))
.background(Some(Color256::BLUE.into()))
.bold()
);
let style = Style::from(Color256::BRIGHT_GREEN).underline();
assert_eq!(style.to_string(), "underline bright_green");
Note that this library does not provide functionality for rendering styles
as ANSI escape sequences; there are plenty of crates that do that already,
and parse-style
provides conversions to some of those crates’ types so
you can use them for your actual styling.
§Style String Syntax
parse-style
follows rich
’s style string syntax specification,
specifically:
-
A style string may be the empty string or
"none"
(case insensitive), denoting an empty style, or it may be a space-separated sequence of one or more of the following tokens in any order:-
A color word (see below), denoting a foreground color
-
The word “
on
” followed by a color word, denoting a background color -
One of the following attribute names (case insensitive), indicating that the given text attribute should be enabled:
- “
bold
” or “b
” — bold text - “
dim
” or “d
” — dim/faint text - “
italic
” or “i
” — italic text - “
underline
” or “u
” — underlined text - “
blink
” — blinking text - “
blink2
” — fast/rapidly blinking text - “
reverse
” or “r
” — reverse-video text - “
conceal
” or “c
” — concealed/hidden text - “
strike
” or “s
” — struck-through text - “
underline2
” or “uu
” — double-underlined text - “
frame
” — framed text - “
encircle
” — encircled text - “
overline
” — overlined text
- “
-
The word “
not
” followed by one of the above attribute names, indicating that the given text attribute should be disabled
-
-
Colors may be specified as any of the following:
-
“
default
” (case insensitive), denoting the default terminal foreground or background color -
a color name (case insensitive) from this table
-
a word of the form
color({index})
(case insensitive) where{index}
is a decimal integer from 0 through 255, denoting the 8-bit color with the given index -
a word of the form
#xxxxxx
, where thex
’s are hexadecimal digits, denoting an RGB color -
a word of the form
rgb({red},{green},{blue})
(case insensitive) where{red}
,{green}
, and{blue}
are decimal integers from 0 though 255, denoting an RGB color
-
-
If a style string contains two or more foreground colors, the last one is used, and likewise for background colors.
-
If a style string contains both an attribute and
not
the same attribute, the last occurrence wins.
§Differences from rich
Style Syntax
-
Hyperlink syntax (
"link https://www.example.com"
) is not supported. -
Minor technical difference:
parse-style
uses Rust’s definition of whitespace for splitting strings into tokens, whilerich
uses Python’s space definition, which includes a few extra control characters.
§Features
The parse-style
crate has the following optional features:
-
anstyle
— Enables conversions betweenparse-style
types and types from theanstyle
crate -
crossterm
— Enables conversions betweenparse-style
types and types from thecrossterm
crate -
ratatui
— Enables conversions betweenparse-style
types and types from theratatui
crate -
serde
— Enablesserde
implementations for (de)serializingStyle
values as style strings and colors as color strings. When combined with one or more of the above features, also enables#[serde(with)]
-compatible modules for (de)serializing foreign types in the same way.
§Important: Lossy Conversions
Different terminal text-styling crates support different styling features,
making perfect interoperability impossible. As a result, some conversions
between parse-style
types and foreign types must discard some information
due to the target type being unable to represent it. See the “Data Loss”
sections in the documentation of the From
impls for specific information.
Modules§
- serde
serde
- (De)serializing foreign types as style strings & color words
Structs§
- Attribute
Iter - An iterator over the variants of Attribute
- Attribute
Set - A set of
Attribute
values. - Attribute
SetIter - An iterator over the
Attribute
s in anAttributeSet
- Color256
- Colors in a 256-value (8-bit) palette
- Conversion
Error - Error returned when conversion between a
parse_style
type and a foreign type fails - Parse
Attribute Error - Error returned when parsing an attribute fails
- Parse
Color Error - Error returned when parsing a color string fails
- RgbColor
- A 24-bit color composed of red, green, and blue components
- Style
- A terminal text style
Enums§
- Attribute
- Individual effects that can be applied to text in a terminal.
- Color
- An enum of the different color types
- Parse
Style Error - Error returned when parsing a style fails