1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
#![doc(html_root_url = "https://docs.rs/yansi/0.6.0-dev")]

//! A dead simple ANSI terminal color painting library.
//!
//! # Usage
//!
//! Usage is best illustrated via a quick example:
//!
//! ```rust
//! use yansi::{Paint, Color};
//!
//! println!("Testing, {}, {}, {}!",
//!     Paint::red(1),
//!     Paint::green(2).bold().underline(),
//!     Paint::blue("3").bg(Color::White).italic());
//! ```
//!
//! ## Paint
//!
//! The main entry point into this library is the [`Paint`] type. `Paint`
//! encapsulates a value of any type that implements the [`Display`] or
//! [`Debug`] trait. When a `Paint` is `Display`ed or `Debug`ed, the appropriate
//! ANSI escape characters are emitted before and after the wrapped type's `fmt`
//! implementation.
//!
//! `Paint` can be constructed via [a myriad of methods]. In addition to these
//! constructors, you can also use the [`color.paint()`](Color::paint()) method
//! on a given [`Color`] value to construct a `Paint` type. Both of these
//! approaches are shown below:
//!
//! ```rust
//! use yansi::Paint;
//! use yansi::Color::Red;
//!
//! println!("I'm {}!", Paint::red("red").bold());
//! println!("I'm also {}!", Red.paint("red").bold());
//! ```
//! [`Display`]: ::std::fmt::Display
//! [`Debug`]: ::std::fmt::Debug
//! [a myriad of methods]: struct.Paint.html#unstyled-constructors
//!
//! ## Styling
//!
//! Modifications to the styling of an item can be made via [a number of
//! chainable methods] on `Paint`.
//!
//! ```rust
//! use yansi::Paint;
//!
//! Paint::new("hi").underline().invert().italic().dimmed().bold();
//! ```
//!
//! Styling can also be created independently from a `Paint` structure via the
//! [`Style`] structure. This allows common styling to be stored and reused. A
//! `Style` can be applied via the [`style.paint()`] method or the
//! [`paint.with_style()`] method:
//!
//! ```rust
//! use yansi::{Paint, Color, Style};
//!
//! // A bold, itatlic style with red foreground.
//! let alert = Style::new(Color::Red).bold().italic();
//!
//! // Using `style.paint()`; this is preferred.
//! println!("Alert! {}", alert.paint("This is serious business!"));
//! println!("Hi! {}", alert.underline().paint("Super serious!"));
//!
//! // Using `paint.with_style()`.
//! println!("Alert! {}", Paint::new("Yet another.").with_style(alert));
//! ```
//!
//! [a number of chainable methods]: struct.Paint.html#setters
//! [`style.paint()`]: Style::paint()
//! [`paint.with_style()`]: Paint::with_style()
//!
//! # Disabling
//!
//! Painting can be disabled globally via the [`Paint::disable()`] method. When
//! painting is disabled, the `Display` and `Debug` implementations for `Paint`
//! will emit the `Display` or `Debug` of the contained object and nothing else.
//! Painting can be reenabled via the [`Paint::enable()`] method.
//!
//! One potential use of this feature is to allow users to control color ouput
//! via an environment variable. For instance, to disable coloring if the
//! `CLICOLOR` variable is set to `0`, you might write:
//!
//! ```rust
//! # { if false { // we don't actually want to disable coloring
//! use yansi::Paint;
//!
//! if let Ok(true) = std::env::var("CLICOLOR").map(|v| v == "0") {
//!     Paint::disable();
//! }
//! # } }
//! ```
//!
//! ## Masking
//!
//! Items can be arbitrarily _masked_. When an item is masked and painting is
//! disabled, the `Display` and `Debug` implementations of `Paint` write
//! nothing. This allows you to selectively omit output when painting is
//! disabled. Values can be masked using the [`Paint::masked()`] constructor
//! or [`paint.mask()`] and [`style.mask()`] style setters.
//!
//! [`paint.mask()`]: Paint::mask()
//! [`style.mask()`]: Style::mask()
//!
//! One use for this feature is to print certain characters only when painting
//! is enabled. For instance, you might wish to emit the 🎨 emoji when
//! coloring is enabled but not otherwise. This can be accomplished by masking
//! the emoji:
//!
//! ```rust
//! use yansi::Paint;
//!
//! println!("I like colors!{}", Paint::masked(" 🎨"));
//! ```
//!
//! This will print "I like colors! 🎨" when painting is enabled and "I like
//! colors!" when painting is disabled.
//!
//! ## Wrapping
//!
//! Styling can be set to _wrap_ existing styles using either the
//! [`Paint::wrapping()`] constructor or the [`paint.wrap()`] and
//! [`style.wrap()`] style setters. When a style is _wrapping_, all color
//! resets written out by the internal item's `Display` or `Debug`
//! implementation are set to the styling of the wrapping style itself. In other
//! words, the "default" style of the wrapped item is modified to be the
//! wrapping style. This allows for easy wrapping of other colored text. Without
//! this feature, the console would reset styling to the terminal's default
//! style instead of the wrapping style.
//!
//! [`paint.wrap()`]: Paint::wrap()
//! [`style.wrap()`]: Style::wrap()
//!
//! One use for this feature is to ensure that styling is consistently set
//! across items that may already be styled, such as when logging.
//!
//! ```rust
//! use yansi::{Paint, Color};
//!
//! let inner = format!("{} and {}", Paint::red("Stop"), Paint::green("Go"));
//! println!("Hey! {}", Paint::wrapping(inner).fg(Color::Blue));
//! ```
//!
//! This will print 'Hey!' unstyled, "Stop" in red, "and" in blue, and "Go" in
//! green. Without wrapping, "and" would be unstyled as `Paint::red()` resets
//! the style after printing the internal item.
//!
//! # Windows
//!
//! Coloring is supported on Windows beginning with the Windows 10 anniversary
//! update. Since this update, Windows consoles support ANSI escape sequences.
//! This support, however, must be explicitly enabled. `yansi` provides the
//! [`Paint::enable_windows_ascii()`] method to enable ASCII support on Windows
//! consoles when available.
//!
//! ```rust
//! use yansi::Paint;
//!
//! // Enable ASCII escape sequence support on Windows consoles.
//! Paint::enable_windows_ascii();
//! ```
//!
//! You may wish to disable coloring on unsupported Windows consoles to avoid
//! emitting unrecognized ASCII escape sequences:
//!
//! ```rust
//! use yansi::Paint;
//!
//! if cfg!(windows) && !Paint::enable_windows_ascii() {
//!     Paint::disable();
//! }
//! ```
//!
//! [`Paint::enable_windows_ascii()`]: Paint::enable_windows_ascii()
//!
//! # Why?
//!
//! Several terminal coloring libraries exist ([`ansi_term`], [`colored`],
//! [`term_painter`], to name a few), begging the question: why yet another?
//! Here are a few reasons:
//!
//!   * This library is _much_ simpler: there are three types!
//!   * Unlike [`ansi_term`] or [`colored`], _any_ type implementing `Display`
//!     or `Debug` can be stylized, not only strings.
//!   * Styling can be enabled and disabled globally, on the fly.
//!   * Arbitrary items can be [_masked_] for selective disabling.
//!   * Styling can [_wrap_] any arbitrarily styled item.
//!   * Typically only one type needs to be imported: [`Paint`].
//!   * Zero dependencies. It really is simple.
//!   * The name `yansi` is pretty short.
//!
//! All that being said, this library borrows API ideas from the three libraries
//! as well as implementation details from [`ansi_term`].
//!
//! [`ansi_term`]: https://crates.io/crates/ansi_term
//! [`colored`]: https://crates.io/crates/colored
//! [`term_painter`]: https://crates.io/crates/term-painter
//! [_masked_]: #masking
//! [_wrap_]: #wrapping

#[macro_use] mod macros;

#[cfg(test)] mod tests;
mod windows;
mod paint;
mod style;
mod color;

pub use color::Color;
pub use style::Style;
pub use paint::Paint;