277 lines
No EOL
16 KiB
HTML
277 lines
No EOL
16 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<meta name="generator" content="rustdoc">
|
||
<meta name="description" content="API documentation for the Rust `ansi_term` crate.">
|
||
<meta name="keywords" content="rust, rustlang, rust-lang, ansi_term">
|
||
|
||
<title>ansi_term - Rust</title>
|
||
|
||
<link rel="stylesheet" type="text/css" href="../rustdoc.css">
|
||
<link rel="stylesheet" type="text/css" href="../main.css">
|
||
|
||
|
||
|
||
</head>
|
||
<body class="rustdoc">
|
||
<!--[if lte IE 8]>
|
||
<div class="warning">
|
||
This old browser is unsupported and will most likely display funky
|
||
things.
|
||
</div>
|
||
<![endif]-->
|
||
|
||
|
||
|
||
<nav class="sidebar">
|
||
|
||
<p class='location'></p><script>window.sidebarCurrent = {name: 'ansi_term', ty: 'mod', relpath: '../'};</script>
|
||
</nav>
|
||
|
||
<nav class="sub">
|
||
<form class="search-form js-only">
|
||
<div class="search-container">
|
||
<input class="search-input" name="search"
|
||
autocomplete="off"
|
||
placeholder="Click or press ‘S’ to search, ‘?’ for more options…"
|
||
type="search">
|
||
</div>
|
||
</form>
|
||
</nav>
|
||
|
||
<section id='main' class="content mod">
|
||
<h1 class='fqn'><span class='in-band'>Crate <a class='mod' href=''>ansi_term</a></span><span class='out-of-band'><span id='render-detail'>
|
||
<a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">
|
||
[<span class='inner'>−</span>]
|
||
</a>
|
||
</span><a id='src-0' class='srclink' href='../src/ansi_term/lib.rs.html.html#1-823' title='goto source code'>[src]</a></span></h1>
|
||
<div class='docblock'><p>This is a library for controlling colours and formatting, such as
|
||
red bold text or blue underlined text, on ANSI terminals.</p>
|
||
|
||
<h2 id='basic-usage' class='section-header'><a href='#basic-usage'>Basic usage</a></h2>
|
||
<p>There are two main data structures in this crate that you need to be
|
||
concerned with: <code>ANSIString</code> and <code>Style</code>. A <code>Style</code> holds stylistic
|
||
information: colours, whether the text should be bold, or blinking, or
|
||
whatever. There are also <code>Colour</code> variants that represent simple foreground
|
||
colour styles. An <code>ANSIString</code> is a string paired with a <code>Style</code>.</p>
|
||
|
||
<p>(Yes, it’s British English, but you won’t have to write “colour” very often.
|
||
<code>Style</code> is used the majority of the time.)</p>
|
||
|
||
<p>To format a string, call the <code>paint</code> method on a <code>Style</code> or a <code>Colour</code>,
|
||
passing in the string you want to format as the argument. For example,
|
||
here’s how to get some red text:</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>use</span> <span class='ident'>ansi_term</span>::<span class='ident'>Colour</span>::<span class='ident'>Red</span>;
|
||
<span class='macro'>println</span><span class='macro'>!</span>(<span class='string'>"This is in red: {}"</span>, <span class='ident'>Red</span>.<span class='ident'>paint</span>(<span class='string'>"a red string"</span>));</pre>
|
||
|
||
<p>It’s important to note that the <code>paint</code> method does <em>not</em> actually return a
|
||
string with the ANSI control characters surrounding it. Instead, it returns
|
||
an <code>ANSIString</code> value that has a <code>Display</code> implementation that, when
|
||
formatted, returns the characters. This allows strings to be printed with a
|
||
minimum of <code>String</code> allocations being performed behind the scenes.</p>
|
||
|
||
<p>If you <em>do</em> want to get at the escape codes, then you can convert the
|
||
<code>ANSIString</code> to a string as you would any other <code>Display</code> value:</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>use</span> <span class='ident'>ansi_term</span>::<span class='ident'>Colour</span>::<span class='ident'>Red</span>;
|
||
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>string</span>::<span class='ident'>ToString</span>;
|
||
<span class='kw'>let</span> <span class='ident'>red_string</span> <span class='op'>=</span> <span class='ident'>Red</span>.<span class='ident'>paint</span>(<span class='string'>"a red string"</span>).<span class='ident'>to_string</span>();</pre>
|
||
|
||
<h2 id='bold-underline-background-and-other-styles' class='section-header'><a href='#bold-underline-background-and-other-styles'>Bold, underline, background, and other styles</a></h2>
|
||
<p>For anything more complex than plain foreground colour changes, you need to
|
||
construct <code>Style</code> objects themselves, rather than beginning with a <code>Colour</code>.
|
||
You can do this by chaining methods based on a new <code>Style</code>, created with
|
||
<code>Style::new()</code>. Each method creates a new style that has that specific
|
||
property set. For example:</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>use</span> <span class='ident'>ansi_term</span>::<span class='ident'>Style</span>;
|
||
<span class='macro'>println</span><span class='macro'>!</span>(<span class='string'>"How about some {} and {}?"</span>,
|
||
<span class='ident'>Style</span>::<span class='ident'>new</span>().<span class='ident'>bold</span>().<span class='ident'>paint</span>(<span class='string'>"bold"</span>),
|
||
<span class='ident'>Style</span>::<span class='ident'>new</span>().<span class='ident'>underline</span>().<span class='ident'>paint</span>(<span class='string'>"underline"</span>));</pre>
|
||
|
||
<p>For brevity, these methods have also been implemented for <code>Colour</code> values,
|
||
so you can give your styles a foreground colour without having to begin with
|
||
an empty <code>Style</code> value:</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>use</span> <span class='ident'>ansi_term</span>::<span class='ident'>Colour</span>::{<span class='ident'>Blue</span>, <span class='ident'>Yellow</span>};
|
||
<span class='macro'>println</span><span class='macro'>!</span>(<span class='string'>"Demonstrating {} and {}!"</span>,
|
||
<span class='ident'>Blue</span>.<span class='ident'>bold</span>().<span class='ident'>paint</span>(<span class='string'>"blue bold"</span>),
|
||
<span class='ident'>Yellow</span>.<span class='ident'>underline</span>().<span class='ident'>paint</span>(<span class='string'>"yellow underline"</span>));
|
||
<span class='macro'>println</span><span class='macro'>!</span>(<span class='string'>"Yellow on blue: {}"</span>, <span class='ident'>Yellow</span>.<span class='ident'>on</span>(<span class='ident'>Blue</span>).<span class='ident'>paint</span>(<span class='string'>"wow!"</span>));</pre>
|
||
|
||
<p>The complete list of styles you can use are: <code>bold</code>, <code>dimmed</code>, <code>italic</code>,
|
||
<code>underline</code>, <code>blink</code>, <code>reverse</code>, <code>hidden</code>, and <code>on</code> for background colours.</p>
|
||
|
||
<p>Finally, you can turn a <code>Colour</code> into a <code>Style</code> with the <code>normal</code> method.
|
||
This will produce the exact same <code>ANSIString</code> as if you just used the
|
||
<code>paint</code> method on the <code>Colour</code> directly, but it’s useful in certain cases:
|
||
for example, you may have a method that returns <code>Styles</code>, and need to
|
||
represent both the “red bold” and “red, but not bold” styles with values of
|
||
the same type. The <code>Style</code> struct also has a <code>Default</code> implementation if you
|
||
want to have a style with <em>nothing</em> set.</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>use</span> <span class='ident'>ansi_term</span>::<span class='ident'>Style</span>;
|
||
<span class='kw'>use</span> <span class='ident'>ansi_term</span>::<span class='ident'>Colour</span>::<span class='ident'>Red</span>;
|
||
<span class='ident'>Red</span>.<span class='ident'>normal</span>().<span class='ident'>paint</span>(<span class='string'>"yet another red string"</span>);
|
||
<span class='ident'>Style</span>::<span class='ident'>default</span>().<span class='ident'>paint</span>(<span class='string'>"a completely regular string"</span>);</pre>
|
||
|
||
<h2 id='extended-colours' class='section-header'><a href='#extended-colours'>Extended colours</a></h2>
|
||
<p>You can access the extended range of 256 colours by using the <code>Fixed</code> colour
|
||
variant, which takes an argument of the colour number to use. This can be
|
||
included wherever you would use a <code>Colour</code>:</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>use</span> <span class='ident'>ansi_term</span>::<span class='ident'>Colour</span>::<span class='ident'>Fixed</span>;
|
||
<span class='ident'>Fixed</span>(<span class='number'>134</span>).<span class='ident'>paint</span>(<span class='string'>"A sort of light purple"</span>);
|
||
<span class='ident'>Fixed</span>(<span class='number'>221</span>).<span class='ident'>on</span>(<span class='ident'>Fixed</span>(<span class='number'>124</span>)).<span class='ident'>paint</span>(<span class='string'>"Mustard in the ketchup"</span>);</pre>
|
||
|
||
<p>The first sixteen of these values are the same as the normal and bold
|
||
standard colour variants. There’s nothing stopping you from using these as
|
||
<code>Fixed</code> colours instead, but there’s nothing to be gained by doing so
|
||
either.</p>
|
||
|
||
<h2 id='combining-successive-coloured-strings' class='section-header'><a href='#combining-successive-coloured-strings'>Combining successive coloured strings</a></h2>
|
||
<p>The benefit of writing ANSI escape codes to the terminal is that they
|
||
<em>stack</em>: you do not need to end every coloured string with a reset code if
|
||
the text that follows it is of a similar style. For example, if you want to
|
||
have some blue text followed by some blue bold text, it’s possible to send
|
||
the ANSI code for blue, followed by the ANSI code for bold, and finishing
|
||
with a reset code without having to have an extra one between the two
|
||
strings.</p>
|
||
|
||
<p>This crate can optimise the ANSI codes that get printed in situations like
|
||
this, making life easier for your terminal renderer. The <code>ANSIStrings</code>
|
||
struct takes a slice of several <code>ANSIString</code> values, and will iterate over
|
||
each of them, printing only the codes for the styles that need to be updated
|
||
as part of its formatting routine.</p>
|
||
|
||
<p>The following code snippet uses this to enclose a binary number displayed in
|
||
red bold text inside some red, but not bold, brackets:</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>use</span> <span class='ident'>ansi_term</span>::<span class='ident'>Colour</span>::<span class='ident'>Red</span>;
|
||
<span class='kw'>use</span> <span class='ident'>ansi_term</span>::{<span class='ident'>ANSIString</span>, <span class='ident'>ANSIStrings</span>};
|
||
<span class='kw'>let</span> <span class='ident'>some_value</span> <span class='op'>=</span> <span class='macro'>format</span><span class='macro'>!</span>(<span class='string'>"{:b}"</span>, <span class='number'>42</span>);
|
||
<span class='kw'>let</span> <span class='ident'>strings</span>: <span class='kw-2'>&</span>[<span class='ident'>ANSIString</span><span class='op'><</span><span class='lifetime'>'static</span><span class='op'>></span>] <span class='op'>=</span> <span class='kw-2'>&</span>[
|
||
<span class='ident'>Red</span>.<span class='ident'>paint</span>(<span class='string'>"["</span>),
|
||
<span class='ident'>Red</span>.<span class='ident'>bold</span>().<span class='ident'>paint</span>(<span class='ident'>some_value</span>),
|
||
<span class='ident'>Red</span>.<span class='ident'>paint</span>(<span class='string'>"]"</span>),
|
||
];
|
||
<span class='macro'>println</span><span class='macro'>!</span>(<span class='string'>"Value: {}"</span>, <span class='ident'>ANSIStrings</span>(<span class='ident'>strings</span>));</pre>
|
||
|
||
<p>There are several things to note here. Firstly, the <code>paint</code> method can take
|
||
<em>either</em> an owned <code>String</code> or a borrowed <code>&str</code>. Internally, an <code>ANSIString</code>
|
||
holds a copy-on-write (<code>Cow</code>) string value to deal with both owned and
|
||
borrowed strings at the same time. This is used here to display a <code>String</code>,
|
||
the result of the <code>format!</code> call, using the same mechanism as some
|
||
statically-available <code>&str</code> slices. Secondly, that the <code>ANSIStrings</code> value
|
||
works in the same way as its singular counterpart, with a <code>Display</code>
|
||
implementation that only performs the formatting when required.</p>
|
||
</div><h2 id='structs' class='section-header'><a href="#structs">Structs</a></h2>
|
||
<table>
|
||
<tr class=' module-item'>
|
||
<td><a class='struct' href='struct.ANSIString.html'
|
||
title='ansi_term::ANSIString'>ANSIString</a></td>
|
||
<td class='docblock short'>
|
||
<p>An ANSI String is a string coupled with the Style to display it
|
||
in a terminal.</p>
|
||
</td>
|
||
</tr>
|
||
|
||
<tr class=' module-item'>
|
||
<td><a class='struct' href='struct.ANSIStrings.html'
|
||
title='ansi_term::ANSIStrings'>ANSIStrings</a></td>
|
||
<td class='docblock short'>
|
||
<p>A set of <code>ANSIString</code>s collected together, in order to be written with a
|
||
minimum of control characters.</p>
|
||
</td>
|
||
</tr>
|
||
|
||
<tr class=' module-item'>
|
||
<td><a class='struct' href='struct.Style.html'
|
||
title='ansi_term::Style'>Style</a></td>
|
||
<td class='docblock short'>
|
||
<p>A style is a collection of properties that can format a string
|
||
using ANSI escape codes.</p>
|
||
</td>
|
||
</tr>
|
||
</table><h2 id='enums' class='section-header'><a href="#enums">Enums</a></h2>
|
||
<table>
|
||
<tr class=' module-item'>
|
||
<td><a class='enum' href='enum.Colour.html'
|
||
title='ansi_term::Colour'>Colour</a></td>
|
||
<td class='docblock short'>
|
||
<p>A colour is one specific type of ANSI escape code, and can refer
|
||
to either the foreground or background colour.</p>
|
||
</td>
|
||
</tr>
|
||
</table></section>
|
||
<section id='search' class="content hidden"></section>
|
||
|
||
<section class="footer"></section>
|
||
|
||
<aside id="help" class="hidden">
|
||
<div>
|
||
<h1 class="hidden">Help</h1>
|
||
|
||
<div class="shortcuts">
|
||
<h2>Keyboard Shortcuts</h2>
|
||
|
||
<dl>
|
||
<dt>?</dt>
|
||
<dd>Show this help dialog</dd>
|
||
<dt>S</dt>
|
||
<dd>Focus the search field</dd>
|
||
<dt>⇤</dt>
|
||
<dd>Move up in search results</dd>
|
||
<dt>⇥</dt>
|
||
<dd>Move down in search results</dd>
|
||
<dt>⏎</dt>
|
||
<dd>Go to active search result</dd>
|
||
</dl>
|
||
</div>
|
||
|
||
<div class="infos">
|
||
<h2>Search Tricks</h2>
|
||
|
||
<p>
|
||
Prefix searches with a type followed by a colon (e.g.
|
||
<code>fn:</code>) to restrict the search to a given type.
|
||
</p>
|
||
|
||
<p>
|
||
Accepted types are: <code>fn</code>, <code>mod</code>,
|
||
<code>struct</code>, <code>enum</code>,
|
||
<code>trait</code>, <code>type</code>, <code>macro</code>,
|
||
and <code>const</code>.
|
||
</p>
|
||
|
||
<p>
|
||
Search functions by type signature (e.g.
|
||
<code>vec -> usize</code> or <code>* -> vec</code>)
|
||
</p>
|
||
</div>
|
||
</div>
|
||
</aside>
|
||
|
||
|
||
|
||
<script>
|
||
window.rootPath = "../";
|
||
window.currentCrate = "ansi_term";
|
||
window.playgroundUrl = "";
|
||
</script>
|
||
<script src="../jquery.js"></script>
|
||
<script src="../main.js"></script>
|
||
|
||
<script defer src="../search-index.js"></script>
|
||
</body>
|
||
</html> |