<!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><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-46f98efaafac5295.ttf.woff2,FiraSans-Regular-018c141bf0843ffd.woff2,FiraSans-Medium-8f9a781e4970d388.woff2,SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2,SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/${f}">`).join(""))</script><linkrel="stylesheet"href="../static.files/normalize-76eba96aa4d2e634.css"><linkrel="stylesheet"href="../static.files/rustdoc-dd39b87e5fcfba68.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.80.0 (051478957 2024-07-21)"data-channel="1.80.0"data-search-js="search-d52510db62a78183.js"data-settings-js="settings-4313503d2e1961c2.js"><scriptsrc="../static.files/storage-118b08c4c78b968e.js"></script><scriptdefersrc="../crates.js"></script><scriptdefersrc="../static.files/main-20a3ad099b048cf2.js"></script><noscript><linkrel="stylesheet"href="../static.files/noscript-df360f571f6edeae.css"></noscript><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><aclass="logo-container"href="../yansi/index.html"><imgsrc="https://raw.githubusercontent.com/SergioBenitez/yansi/master/.github/yansi-logo.png"alt=""></a></nav><navclass="sidebar"><divclass="sidebar-crate"><aclass="logo-container"href="../yansi/index.html"><imgsrc="https://raw.githubusercontent.com/SergioBenitez/yansi/master/.github/yansi-logo.png"alt="logo"></a><h2><ahref="../yansi/index.html">yansi</a><spanclass="version">1.0.1</span></h2></div><divclass="sidebar-elems"><ulclass="block"><li><aid="all-types"href="all.html">All Items</a></li></ul><section><ulclass="block"><li><ahref="#structs">Structs</a></li><li><ahref="#enums">Enums</a></li><li><ahref="#traits">Traits</a></li><li><ahref="#functions">Functions</a></li></ul></section></div></nav><divclass="sidebar-resizer"></div><main><divclass="width-limiter"><rustdoc-search></rustdoc-search><sectionid="main-content"class="content"><divclass="main-heading"><h1>Crate <aclass="mod"href="#">yansi</a><buttonid="copy-path"title="Copy item path to clipboard">Copy item path</button></h1><spanclass="out-of-band"><aclass="src"href="../src/yansi/lib.rs.html#1-373">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>
<p>Why <em>y</em>et another <em>ANSI</em> terminal coloring library? Here are some reasons:</p>
<ul>
<li>This library makes simple things <em>simple</em>: <code>use</code><ahref="trait.Paint.html"title="trait yansi::Paint"><code>Paint</code></a> and go!</li>
<li>Zero dependencies by default. It really is simple.</li>
<li>Zero allocations except as needed by opt-in <ahref="#wrapping">wrapping</a>.</li>
<li><ahref="#windows">Automatic Windows support</a> for the vast majority (95%+) of Windows
users.</li>
<li><ahref="#crate-features">Featureful <code>no_std</code></a>, no-<code>alloc</code>, support with <code>default-features = false</code>.</li>
<li><ahref="#uniform-const-builders"><code>Style</code> constructors are <code>const</code></a>: store styles statically, even with
dynamic conditions!</li>
<li><em>Any</em> type implementing a formatting trait can be styled, not just
strings.</li>
<li>Styling can be <ahref="fn.enable.html"title="fn yansi::enable">enabled</a> and <ahref="fn.disable.html"title="fn yansi::disable">disabled</a> globally and <ahref="fn.whenever.html"title="fn yansi::whenever">dynamically</a>, on
the fly.</li>
<li>A <code>Style</code> can be predicated on arbitrary <ahref="#per-style">conditions</a>.</li>
<li>Formatting specifiers like <code>{:x}</code> and <code>{:08b}</code> are supported and
preserved!</li>
<li><ahref="struct.Condition.html#built-in-conditions"title="struct yansi::Condition">Built-in (optional) conditions</a> for <ahref="struct.Condition.html#impl-Condition-1"title="struct yansi::Condition">TTY detection</a> and <ahref="struct.Condition.html#impl-Condition-2"title="struct yansi::Condition">common
environment variables</a>.</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> to preserve styling across resets.</li>
<li>Styling can <ahref="#lingering"><em>linger</em></a> beyond a single value.</li>
<li>Experimental support for <ahref="hyperlink">hyperlinking</a> is included.</li>
<li>The name <code>yansi</code> is pretty cool 😎.</li>
</ul>
<p>All that said, <code>yansi</code> borrows API ideas from older libraries as well as
implementation details from <ahref="https://crates.io/crates/ansi_term"><code>ansi_term</code></a>.</p>
<p>The methods return a <ahref="struct.Painted.html"title="struct yansi::Painted"><code>Painted</code></a> type which consists of a <ahref="struct.Style.html"title="struct yansi::Style"><code>Style</code></a> and a
reference to the receiver. Displaying a <ahref="struct.Painted.html"title="struct yansi::Painted"><code>Painted</code></a> (via <code>print!()</code>,
<code>format!()</code>, etc) results in emitting ANSI escape codes that effectuate the
<p>All builder methods are uniformly available for <ahref="struct.Style.html"title="struct yansi::Style"><code>Style</code></a>, <ahref="enum.Color.html"title="enum yansi::Color"><code>Color</code></a>, and
<ahref="struct.Painted.html"title="struct yansi::Painted"><code>Painted</code></a>, which means you can chain calls across library types. All
methods are <code>const</code>, allowing creations of <code>const</code> or <code>static</code><ahref="struct.Style.html"title="struct yansi::Style"><code>Style</code></a>s. A
<code>Style</code> can be directly applied to values with <ahref="trait.Paint.html#method.paint"title="method yansi::Paint::paint"><code>.paint()</code></a>,
from <ahref="trait.Paint.html#method.paint"title="method yansi::Paint::paint"><code>Paint::paint()</code></a>, available for every type:</p>
<p>Styling is enabled by default but can be enabled and disabled globally via
<ahref="fn.enable.html"title="fn yansi::enable"><code>enable()</code></a> and <ahref="fn.disable.html"title="fn yansi::disable"><code>disable()</code></a>. When styling is disabled, no ANSI escape
codes are emitted, and <ahref="#masking"><em>masked</em></a> values are omitted entirely.</p>
<p>Global styling can also be dynamically enabled and disabled using
<ahref="fn.whenever.html"title="fn yansi::whenever"><code>whenever()</code></a> with an arbitrary <ahref="struct.Condition.html"title="struct yansi::Condition"><code>Condition</code></a>: a function that returns
<code>true</code> or <code>false</code>. This condition is evaluated each time a <ahref="struct.Painted.html"title="struct yansi::Painted"><code>Painted</code></a> item
is displayed. The associated styling is enabled, and mask values emitted,
exactly when and only when the condition returns <code>true</code>.</p>
<spanclass="macro">eprintln!</span>(<spanclass="string">"{}"</span>, <spanclass="string">"Bees can sting!"</span>.paint(WARNING));</code></pre></div>
<p>With the above, if <code>stderr</code> is a TTY, then:
<code>></code><spanstyle="background: yellow; color: black;"><b>Bees can sting!</b></span></p>
<p>If it is not a TTY, styling is not emitted:
<code>></code> Bees can sting!</p>
<p>See <ahref="struct.Condition.html"title="struct yansi::Condition"><code>Condition</code></a> for a list of built-in conditions which require enabling
<p>Items can be arbitrarily <em>masked</em> with the <ahref="trait.Paint.html#tymethod.mask"title="method yansi::Paint::mask"><code>mask()</code></a> builder
method. Masked values are not emitted when styling is disabled, globally or
for a given style. This allows selective output based on whether styling is
enabled.</p>
<p>One use for this feature is to print certain characters only when styling 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:</p>
<p><strong>Note:</strong><em>Either the <code>std</code> or <code>alloc</code> feature is required for wrapping.
<code>std</code> is enabled by default. See <ahref="#crate-features">crate features</a>.</em></p>
<p>Styling can <em>wrap</em> via <ahref="enum.Quirk.html#variant.Wrap"title="variant yansi::Quirk::Wrap"><code>Quirk::Wrap</code></a> or the equivalent
<ahref="struct.Painted.html#method.wrap"title="method yansi::Painted::wrap"><code>wrap()</code></a> constructor. A wrapping style modifies any
styling resets emitted by the internal value so that they correspond to the
wrapping style. In other words, the “reset” style of the wrapped item is
modified to be the style being <code>.wrap()</code>d.</p>
<p>Wrapping is useful in situations where opaque and arbitrary values must be
styled consistently irrespective of any existing styling. For example, a
generic logger might want to style messages based on log levels
consistently, even when those messages may already include styling. Wrapping
<p>Styling can <em>linger</em> beyond a single value via <ahref="enum.Quirk.html#variant.Linger"title="variant yansi::Quirk::Linger"><code>Quirk::Linger</code></a> or the
equivalent <ahref="struct.Painted.html#method.linger"title="method yansi::Painted::linger"><code>linger()</code></a> constructor. A lingering style
does not reset itself after being applied. In other words, the style lingers
on beyond the value it’s applied to, until something else resets the
respective styling.</p>
<p>The complement to lingering is force resetting via <ahref="enum.Quirk.html#variant.Resetting"title="variant yansi::Quirk::Resetting"><code>Quirk::Resetting</code></a> or
the equivalent <ahref="struct.Painted.html#method.resetting"title="method yansi::Painted::resetting"><code>resetting()</code></a> constructor. Force
resetting, as the name implies, forces a reset suffix to be emitted after
the value, irrespective of any lingering applied. It can be used as a way to
finalize a lingering style.</p>
<p>Lingering itself is useful in situations where a given style is to be
repeated across multiple values, or when style is intended to persist even
across values that are not styled with <code>yansi</code>. It also allows avoiding
unnecessarily repeated ANSI code sequences. The examples below illustrate
<p>Most pimrary colors are available in regular and <em>bright</em> variants, e.g.,
<ahref="enum.Color.html#variant.Red"title="variant yansi::Color::Red"><code>Color::Red</code></a> and <ahref="enum.Color.html#variant.BrightRed"title="variant yansi::Color::BrightRed"><code>Color::BrightRed</code></a>. The <ahref="enum.Quirk.html#variant.Bright"title="variant yansi::Quirk::Bright"><code>Quirk::Bright</code></a> and
<ahref="enum.Quirk.html#variant.OnBright"title="variant yansi::Quirk::OnBright"><code>Quirk::OnBright</code></a> quirks, typically applied via
<ahref="struct.Painted.html#method.bright"title="method yansi::Painted::bright"><code>.bright()</code></a> and <ahref="struct.Painted.html#method.on_bright"title="method yansi::Painted::on_bright"><code>.on_bright()</code></a>,
provide an alternative, convenient mechanism to select the bright variant of
the selected foreground or background color, respectively. The quirk
provides no additional colors and is equivalent to selecting the bright
<p>Styling is supported and enabled automatically on Windows beginning with
the Windows 10 Anniversary Update, or about <ahref="https://gs.statcounter.com/os-version-market-share/windows/desktop/worldwide">96% of all Windows machines
worldwide</a>,
and likely closer to 100% of developer machines (e.g., 99% of visitors to
<ahref="https://rocket.rs">rocket.rs</a> on Windows are on Windows 10+).</p>
<p>Yansi enables styling support on Windows by querying the Windows API on the
first attempt to color. If support is available, it is enabled. If support
is not available, styling is disabled and no styling sequences are emitted.</p>
<p>With <code>default-features = false</code>, this crate is <code>#[no_std]</code>.</p>
<p>Without any features enabled, all functionality except <ahref="#wrapping">wrapping</a> is
available. To recover wrapping <em>with</em><code>#[no_std]</code>, set <code>default-features = false</code> and enable the <code>alloc</code> feature, which requires <code>alloc</code> support.</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.Condition.html"title="struct yansi::Condition">Condition</a></div><divclass="desc docblock-short">A function that decides whether styling should be applied.</div></li><li><divclass="item-name"><aclass="struct"href="struct.Painted.html"title="struct yansi::Painted">Painted</a></div><divclass="desc docblock-short">An arbitrary value with a <ahref="struct.Style.html"title="struct yansi::Style"><code>Style</code></a> applied to it.</div></li><li><divclass="item-name"><aclass="struct"href="struct.Style.html"title="struct yansi::Style">Style</a></div><divclass="desc docblock-short">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.Attribute.html"title="enum yansi::Attribute">Attribute</a></div><divclass="desc docblock-short">Enum representing text attributes, largely for text formatting.</div></li><li><divclass="item-name"><aclass="enum"href="enum.Color.html"title="enum yansi::Color">Color</a></div><divclass="desc docblock-short">Enum representing a terminal color.</div></li><li><divclass="item-name"><aclass="enum"href="enum.Quirk.html"title="enum yansi::Quirk">Quirk</a></div><divclass="desc docblock-short">Enum representing a <code>yansi</code> quirk.</div></li></ul><h2id="traits"class="section-header">Traits<ahref="#traits"class="anchor">§</a></h2><ulclass="item-table"><li><divclass="item-name"><aclass="trait"href="trait.Paint.html"title="trait yansi::Paint">Paint</a></div><divclass="desc docblock-short">A trait to apply styling to any value. Implemented for all types.</div></li></ul><h2id="functions"class="section-header">Functions<ahref="#functions"class="anchor">§</a></h2><ulclass="item-table"><li><divclass="item-name"><aclass="fn"href="fn.disable.html"title="fn yansi::disable">disable</a></div><divclass="desc docblock-short">Unconditionally disables styling globally.</div></li><li><divclass="item-name"><aclass="fn"href="fn.enable.html"title="fn yansi::enable">enable</a></div><divclass="desc docblock-short">Unconditionally enables styling globally.</div></li><li><divclass="item-name"><aclass="fn"href="fn.is_enabled.html"title="fn yansi::is_enabled">is_enabled</a></div><divclass="desc docblock-short">Returns <code>true</code> if styling is globally enabled and <code>false</code> otherwise.</div></li><li><divclass="item-name"><aclass="fn"href="fn.whenever.html"title="fn yansi::whenever">whenever</a></div><divclass="desc docblock-short">Dynamically enables and disables styling globally based on <code>condition</code>.</div></li></ul></section></div></main></body></html>
