<!DOCTYPE html><htmllang="en"><head><metacharset="utf-8"><metaname="viewport"content="width=device-width, initial-scale=1.0"><metaname="generator"content="rustdoc"><metaname="description"content="A dead simple ANSI terminal color painting library."><title>yansi - Rust</title><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../static.files/SourceSerif4-Regular-46f98efaafac5295.ttf.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../static.files/FiraSans-Regular-018c141bf0843ffd.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../static.files/FiraSans-Medium-8f9a781e4970d388.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../static.files/SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../static.files/SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2"><linkrel="stylesheet"href="../static.files/normalize-76eba96aa4d2e634.css"><linkrel="stylesheet"href="../static.files/rustdoc-5bc39a1768837dd0.css"><metaname="rustdoc-vars"data-root-path="../"data-static-root-path="../static.files/"data-current-crate="yansi"data-themes=""data-resource-suffix=""data-rustdoc-version="1.77.2 (25ef9e3d8 2024-04-09)"data-channel="1.77.2"data-search-js="search-dd67cee4cfa65049.js"data-settings-js="settings-4313503d2e1961c2.js"><scriptsrc="../static.files/storage-4c98445ec4002617.js"></script><scriptdefersrc="../crates.js"></script><scriptdefersrc="../static.files/main-48f368f3872407c8.js"></script><noscript><linkrel="stylesheet"href="../static.files/noscript-04d5337699b92874.css"></noscript><linkrel="alternate icon"type="image/png"href="../static.files/favicon-16x16-8b506e7a72182f1c.png"><linkrel="alternate icon"type="image/png"href="../static.files/favicon-32x32-422f7d1d52889060.png"><linkrel="icon"type="image/svg+xml"href="../static.files/favicon-2c020d218678b618.svg"></head><bodyclass="rustdoc mod crate"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><navclass="mobile-topbar"><buttonclass="sidebar-menu-toggle"title="show sidebar"></button></nav><navclass="sidebar"><divclass="sidebar-crate"><h2><ahref="../yansi/index.html">yansi</a><spanclass="version">0.5.1</span></h2></div><divclass="sidebar-elems"><ulclass="block">
<main><divclass="width-limiter"><navclass="sub"><formclass="search-form"><span></span><divid="sidebar-button"tabindex="-1"><ahref="../yansi/all.html"title="show sidebar"></a></div><inputclass="search-input"name="search"aria-label="Run search in the documentation"autocomplete="off"spellcheck="false"placeholder="Click or press ‘S’ to search, ‘?’ for more options…"type="search"><divid="help-button"tabindex="-1"><ahref="../help.html"title="help">?</a></div><divid="settings-menu"tabindex="-1"><ahref="../settings.html"title="settings"><imgwidth="22"height="22"alt="Change settings"src="../static.files/wheel-7b819b6101059cd0.svg"></a></div></form></nav><sectionid="main-content"class="content"><divclass="main-heading"><h1>Crate <aclass="mod"href="#">yansi</a><buttonid="copy-path"title="Copy item path to clipboard"><imgsrc="../static.files/clipboard-7571035ce49a181d.svg"width="19"height="18"alt="Copy item path"></button></h1><spanclass="out-of-band"><aclass="src"href="../src/yansi/lib.rs.html#1-214">source</a> · <buttonid="toggle-all-docs"title="collapse all docs">[<span>−</span>]</button></span></div><detailsclass="toggle top-doc"open><summaryclass="hideme"><span>Expand description</span></summary><divclass="docblock"><p>A dead simple ANSI terminal color painting library.</p>
encapsulates a value of any type that implements the <ahref="https://doc.rust-lang.org/1.77.2/core/fmt/trait.Display.html"title="trait core::fmt::Display"><code>Display</code></a> or
<ahref="https://doc.rust-lang.org/1.77.2/core/fmt/trait.Debug.html"title="trait core::fmt::Debug"><code>Debug</code></a> trait. When a <code>Paint</code> is <code>Display</code>ed or <code>Debug</code>ed, the appropriate
<p>Styling can also be created independently from a <code>Paint</code> structure via the
<ahref="struct.Style.html"title="struct yansi::Style"><code>Style</code></a> structure. This allows common styling to be stored and reused. A
<code>Style</code> can be applied via the <ahref="struct.Style.html#method.paint"title="method yansi::Style::paint"><code>style.paint()</code></a> method or the
<p>Painting can be disabled globally via the <ahref="struct.Paint.html#method.disable"title="associated function yansi::Paint::disable"><code>Paint::disable()</code></a> method. When
painting is disabled, the <code>Display</code> and <code>Debug</code> implementations for <code>Paint</code>
will emit the <code>Display</code> or <code>Debug</code> of the contained object and nothing else.
Painting can be reenabled via the <ahref="struct.Paint.html#method.enable"title="associated function yansi::Paint::enable"><code>Paint::enable()</code></a> method.</p>
<p>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
<code>CLICOLOR</code> variable is set to <code>0</code>, you might write:</p>
<spanclass="kw">if let </span><spanclass="prelude-val">Ok</span>(<spanclass="bool-val">true</span>) = std::env::var(<spanclass="string">"CLICOLOR"</span>).map(|v| v == <spanclass="string">"0"</span>) {
<p>Items can be arbitrarily <em>masked</em>. When an item is masked and painting is
disabled, the <code>Display</code> and <code>Debug</code> implementations of <code>Paint</code> write
nothing. This allows you to selectively omit output when painting is
disabled. Values can be masked using the <ahref="struct.Paint.html#method.masked"title="associated function yansi::Paint::masked"><code>Paint::masked()</code></a> constructor
or <ahref="struct.Paint.html#method.mask"title="method yansi::Paint::mask"><code>paint.mask()</code></a> and <ahref="struct.Style.html#method.mask"title="method yansi::Style::mask"><code>style.mask()</code></a> style setters.</p>
<p>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
<p>Styling can be set to <em>wrap</em> existing styles using either the
<ahref="struct.Paint.html#method.wrapping"title="associated function yansi::Paint::wrapping"><code>Paint::wrapping()</code></a> constructor or the <ahref="struct.Paint.html#method.wrap"title="method yansi::Paint::wrap"><code>paint.wrap()</code></a> and
<ahref="struct.Style.html#method.wrap"title="method yansi::Style::wrap"><code>style.wrap()</code></a> style setters. When a style is <em>wrapping</em>, all color
resets written out by the internal item’s <code>Display</code> or <code>Debug</code>
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.</p>
<p>One use for this feature is to ensure that styling is consistently set
across items that may already be styled, such as when logging.</p>
<p>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. <code>yansi</code> provides the
<ahref="struct.Paint.html#method.enable_windows_ascii"title="associated function yansi::Paint::enable_windows_ascii"><code>Paint::enable_windows_ascii()</code></a> method to enable ASCII support on Windows
<ahref="https://crates.io/crates/term-painter"><code>term_painter</code></a>, to name a few), begging the question: why yet another?
Here are a few reasons:</p>
<ul>
<li>This library is <em>much</em> simpler: there are three types!</li>
<li>Unlike <ahref="https://crates.io/crates/ansi_term"><code>ansi_term</code></a> or <ahref="https://crates.io/crates/colored"><code>colored</code></a>, <em>any</em> type implementing <code>Display</code>
or <code>Debug</code> can be stylized, not only strings.</li>
<li>Styling can be enabled and disabled globally, on the fly.</li>
<li>Arbitrary items can be <ahref="#masking"><em>masked</em></a> for selective disabling.</li>
<li>Styling can <ahref="#wrapping"><em>wrap</em></a> any arbitrarily styled item.</li>
<li>Typically only one type needs to be imported: <ahref="struct.Paint.html"title="struct yansi::Paint"><code>Paint</code></a>.</li>
<li>Zero dependencies. It really is simple.</li>
<li>The name <code>yansi</code> is pretty short.</li>
</ul>
<p>All that being said, this library borrows API ideas from the three libraries
as well as implementation details from <ahref="https://crates.io/crates/ansi_term"><code>ansi_term</code></a>.</p>
</div></details><h2id="structs"class="section-header">Structs<ahref="#structs"class="anchor">§</a></h2><ulclass="item-table"><li><divclass="item-name"><aclass="struct"href="struct.Paint.html"title="struct yansi::Paint">Paint</a></div><divclass="desc docblock-short">A structure encapsulating an item and styling.</div></li><li><divclass="item-name"><aclass="struct"href="struct.Style.html"title="struct yansi::Style">Style</a></div><divclass="desc docblock-short">Represents a set of styling options.</div></li></ul><h2id="enums"class="section-header">Enums<ahref="#enums"class="anchor">§</a></h2><ulclass="item-table"><li><divclass="item-name"><aclass="enum"href="enum.Color.html"title="enum yansi::Color">Color</a></div><divclass="desc docblock-short">An enum representing an ANSI color code.</div></li></ul></section></div></main></body></html>
