greg/mentat
1
0
Fork 0
Code Issues 294 Pull requests Projects Releases 9 Packages Wiki Activity
mentat/docs/apis/rust/quick_error/index.html

381 lines
22 KiB
HTML
Raw Normal View History

Add docs to documentation site
2018-06-21 14:44:35 +00:00
<!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 `quick_error` crate.">
<meta name="keywords" content="rust, rustlang, rust-lang, quick_error">
<title>quick_error - Rust</title>
<link rel="stylesheet" type="text/css" href="../normalize.css">
<link rel="stylesheet" type="text/css" href="../rustdoc.css"
id="mainThemeStyle">
<link rel="stylesheet" type="text/css" href="../dark.css">
<link rel="stylesheet" type="text/css" href="../light.css" id="themeStyle">
<script src="../storage.js"></script>
</head>
<body class="rustdoc mod">
<!--[if lte IE 8]>
<div class="warning">
This old browser is unsupported and will most likely display funky
things.
</div>
<![endif]-->
<nav class="sidebar">
<div class="sidebar-menu">&#9776;</div>
<p class='location'>Crate quick_error</p><div class="sidebar-elems"><div class="block items"><ul><li><a href="#macros">Macros</a></li><li><a href="#structs">Structs</a></li><li><a href="#traits">Traits</a></li></ul></div><p class='location'></p><script>window.sidebarCurrent = {name: 'quick_error', ty: 'mod', relpath: '../'};</script></div>
</nav>
<div class="theme-picker">
<button id="theme-picker" aria-label="Pick another theme!">
<img src="../brush.svg" width="18" alt="Pick another theme!">
</button>
<div id="theme-choices"></div>
</div>
<script src="../theme.js"></script>
<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"><h1 class='fqn'><span class='in-band'>Crate <a class="mod" href=''>quick_error</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'>&#x2212;</span>]
</a>
</span><a class='srclink' href='../src/quick_error/lib.rs.html#1-1309' title='goto source code'>[src]</a></span></h1><div class='docblock'><p>A macro which makes errors easy to write</p>
<p>Minimum type is like this:</p>
<pre class="rust rust-example-rendered">
<span class="attribute">#[<span class="ident">macro_use</span>]</span> <span class="kw">extern</span> <span class="kw">crate</span> <span class="ident">quick_error</span>;
<span class="macro">quick_error</span><span class="macro">!</span> {
<span class="attribute">#[<span class="ident">derive</span>(<span class="ident">Debug</span>)]</span>
<span class="kw">pub</span> <span class="kw">enum</span> <span class="ident">SomeError</span> {
<span class="ident">Variant1</span> {}
}
}</pre>
<p>Both <code>pub</code> and non-public types may be declared, and all meta attributes
(such as <code>#[derive(Debug)]</code>) are forwarded as is. The <code>Debug</code> must be
implemented (but you may do that yourself if you like). The documentation
comments <code>/// something</code> (as well as other meta attrbiutes) on variants
are allowed.</p>
<h1 id="allowed-syntax" class="section-header"><a href="#allowed-syntax">Allowed Syntax</a></h1>
<p>You may add arbitrary parameters to any struct variant:</p>
<pre class="rust rust-example-rendered">
<span class="macro">quick_error</span><span class="macro">!</span> {
<span class="attribute">#[<span class="ident">derive</span>(<span class="ident">Debug</span>)]</span>
<span class="kw">pub</span> <span class="kw">enum</span> <span class="ident">SomeError</span> {
<span class="doccomment">/// IO Error</span>
<span class="ident">Io</span>(<span class="ident">err</span>: <span class="ident">std</span>::<span class="ident">io</span>::<span class="ident">Error</span>) {}
<span class="doccomment">/// Utf8 Error</span>
<span class="ident">Utf8</span>(<span class="ident">err</span>: <span class="ident">std</span>::<span class="ident">str</span>::<span class="ident">Utf8Error</span>) {}
}
}</pre>
<p>Note unlike in normal Enum declarations you declare names of fields (which
are omitted from type). How they can be used is outlined below.</p>
<p>Now you might have noticed trailing braces <code>{}</code>. They are used to define
implementations. By default:</p>
<ul>
<li><code>Error::description()</code> returns variant name as static string</li>
<li><code>Error::cause()</code> returns None (even if type wraps some value)</li>
<li><code>Display</code> outputs <code>description()</code></li>
<li>No <code>From</code> implementations are defined</li>
</ul>
<p>To define description simply add <code>description(value)</code> inside braces:</p>
<pre class="rust rust-example-rendered">
<span class="macro">quick_error</span><span class="macro">!</span> {
<span class="attribute">#[<span class="ident">derive</span>(<span class="ident">Debug</span>)]</span>
<span class="kw">pub</span> <span class="kw">enum</span> <span class="ident">SomeError</span> {
<span class="ident">Io</span>(<span class="ident">err</span>: <span class="ident">std</span>::<span class="ident">io</span>::<span class="ident">Error</span>) {
<span class="ident">description</span>(<span class="ident">err</span>.<span class="ident">description</span>())
}
<span class="ident">Utf8</span>(<span class="ident">err</span>: <span class="ident">std</span>::<span class="ident">str</span>::<span class="ident">Utf8Error</span>) {
<span class="ident">description</span>(<span class="string">&quot;utf8 error&quot;</span>)
}
}
}</pre>
<p>Normal rules for borrowing apply. So most of the time description either
returns constant string or forwards description from enclosed type.</p>
<p>To change <code>cause</code> method to return some error, add <code>cause(value)</code>, for
example:</p>
<pre class="rust rust-example-rendered">
<span class="macro">quick_error</span><span class="macro">!</span> {
<span class="attribute">#[<span class="ident">derive</span>(<span class="ident">Debug</span>)]</span>
<span class="kw">pub</span> <span class="kw">enum</span> <span class="ident">SomeError</span> {
<span class="ident">Io</span>(<span class="ident">err</span>: <span class="ident">std</span>::<span class="ident">io</span>::<span class="ident">Error</span>) {
<span class="ident">cause</span>(<span class="ident">err</span>)
<span class="ident">description</span>(<span class="ident">err</span>.<span class="ident">description</span>())
}
<span class="ident">Utf8</span>(<span class="ident">err</span>: <span class="ident">std</span>::<span class="ident">str</span>::<span class="ident">Utf8Error</span>) {
<span class="ident">description</span>(<span class="string">&quot;utf8 error&quot;</span>)
}
<span class="ident">Other</span>(<span class="ident">err</span>: <span class="ident">Box</span><span class="op">&lt;</span><span class="ident">std</span>::<span class="ident">error</span>::<span class="ident">Error</span><span class="op">&gt;</span>) {
<span class="ident">cause</span>(<span class="kw-2">&amp;</span><span class="kw-2">*</span><span class="kw-2">*</span><span class="ident">err</span>)
<span class="ident">description</span>(<span class="ident">err</span>.<span class="ident">description</span>())
}
}
}</pre>
<p>Note you don't need to wrap value in <code>Some</code>, its implicit. In case you want
<code>None</code> returned just omit the <code>cause</code>. You can't return <code>None</code>
conditionally.</p>
<p>To change how each clause is <code>Display</code>ed add <code>display(pattern,..args)</code>,
for example:</p>
<pre class="rust rust-example-rendered">
<span class="macro">quick_error</span><span class="macro">!</span> {
<span class="attribute">#[<span class="ident">derive</span>(<span class="ident">Debug</span>)]</span>
<span class="kw">pub</span> <span class="kw">enum</span> <span class="ident">SomeError</span> {
<span class="ident">Io</span>(<span class="ident">err</span>: <span class="ident">std</span>::<span class="ident">io</span>::<span class="ident">Error</span>) {
<span class="ident">display</span>(<span class="string">&quot;I/O error: {}&quot;</span>, <span class="ident">err</span>)
}
<span class="ident">Utf8</span>(<span class="ident">err</span>: <span class="ident">std</span>::<span class="ident">str</span>::<span class="ident">Utf8Error</span>) {
<span class="ident">display</span>(<span class="string">&quot;Utf8 error, valid up to {}&quot;</span>, <span class="ident">err</span>.<span class="ident">valid_up_to</span>())
}
}
}</pre>
<p>If you need a reference to the error when <code>Display</code>ing, you can instead use
<code>display(x) -&gt; (pattern, ..args)</code>, where <code>x</code> sets the name of the reference.</p>
<pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">error</span>::<span class="ident">Error</span>; <span class="comment">// put methods like `description()` of this trait into scope</span>
<span class="macro">quick_error</span><span class="macro">!</span> {
<span class="attribute">#[<span class="ident">derive</span>(<span class="ident">Debug</span>)]</span>
<span class="kw">pub</span> <span class="kw">enum</span> <span class="ident">SomeError</span> {
<span class="ident">Io</span>(<span class="ident">err</span>: <span class="ident">std</span>::<span class="ident">io</span>::<span class="ident">Error</span>) {
<span class="ident">display</span>(<span class="ident">x</span>) <span class="op">-&gt;</span> (<span class="string">&quot;{}: {}&quot;</span>, <span class="ident">x</span>.<span class="ident">description</span>(), <span class="ident">err</span>)
}
<span class="ident">Utf8</span>(<span class="ident">err</span>: <span class="ident">std</span>::<span class="ident">str</span>::<span class="ident">Utf8Error</span>) {
<span class="ident">display</span>(<span class="ident">self_</span>) <span class="op">-&gt;</span> (<span class="string">&quot;{}, valid up to {}&quot;</span>, <span class="ident">self_</span>.<span class="ident">description</span>(), <span class="ident">err</span>.<span class="ident">valid_up_to</span>())
}
}
}</pre>
<p>To convert to the type from any other, use one of the three forms of
<code>from</code> clause.</p>
<p>For example, to convert simple wrapper use bare <code>from()</code>:</p>
<pre class="rust rust-example-rendered">
<span class="macro">quick_error</span><span class="macro">!</span> {
<span class="attribute">#[<span class="ident">derive</span>(<span class="ident">Debug</span>)]</span>
<span class="kw">pub</span> <span class="kw">enum</span> <span class="ident">SomeError</span> {
<span class="ident">Io</span>(<span class="ident">err</span>: <span class="ident">std</span>::<span class="ident">io</span>::<span class="ident">Error</span>) {
<span class="ident">from</span>()
}
}
}</pre>
<p>This implements <code>From&lt;io::Error&gt;</code>.</p>
<p>To convert to singleton enumeration type (discarding the value), use
the <code>from(type)</code> form:</p>
<pre class="rust rust-example-rendered">
<span class="macro">quick_error</span><span class="macro">!</span> {
<span class="attribute">#[<span class="ident">derive</span>(<span class="ident">Debug</span>)]</span>
<span class="kw">pub</span> <span class="kw">enum</span> <span class="ident">SomeError</span> {
<span class="ident">FormatError</span> {
<span class="ident">from</span>(<span class="ident">std</span>::<span class="ident">fmt</span>::<span class="ident">Error</span>)
}
}
}</pre>
<p>And the most powerful form is <code>from(var: type) -&gt; (arguments...)</code>. It
might be used to convert to type with multiple arguments or for arbitrary
value conversions:</p>
<pre class="rust rust-example-rendered">
<span class="macro">quick_error</span><span class="macro">!</span> {
<span class="attribute">#[<span class="ident">derive</span>(<span class="ident">Debug</span>)]</span>
<span class="kw">pub</span> <span class="kw">enum</span> <span class="ident">SomeError</span> {
<span class="ident">FailedOperation</span>(<span class="ident">s</span>: <span class="kw-2">&amp;</span><span class="lifetime">&#39;static</span> <span class="ident">str</span>, <span class="ident">errno</span>: <span class="ident">i32</span>) {
<span class="ident">from</span>(<span class="ident">errno</span>: <span class="ident">i32</span>) <span class="op">-&gt;</span> (<span class="string">&quot;os error&quot;</span>, <span class="ident">errno</span>)
<span class="ident">from</span>(<span class="ident">e</span>: <span class="ident">std</span>::<span class="ident">io</span>::<span class="ident">Error</span>) <span class="op">-&gt;</span> (<span class="string">&quot;io error&quot;</span>, <span class="ident">e</span>.<span class="ident">raw_os_error</span>().<span class="ident">unwrap</span>())
}
<span class="doccomment">/// Converts from both kinds of utf8 errors</span>
<span class="ident">Utf8</span>(<span class="ident">err</span>: <span class="ident">std</span>::<span class="ident">str</span>::<span class="ident">Utf8Error</span>) {
<span class="ident">from</span>()
<span class="ident">from</span>(<span class="ident">err</span>: <span class="ident">std</span>::<span class="ident">string</span>::<span class="ident">FromUtf8Error</span>) <span class="op">-&gt;</span> (<span class="ident">err</span>.<span class="ident">utf8_error</span>())
}
}
}</pre>
<h1 id="context" class="section-header"><a href="#context">Context</a></h1>
<p>Since quick-error 1.1 we also have a <code>context</code> declaration, which is
similar to (the longest form of) <code>from</code>, but allows adding some context to
the error. We need a longer example to demonstrate this:</p>
<pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">quick_error</span>::<span class="ident">ResultExt</span>;
<span class="macro">quick_error</span><span class="macro">!</span> {
<span class="attribute">#[<span class="ident">derive</span>(<span class="ident">Debug</span>)]</span>
<span class="kw">pub</span> <span class="kw">enum</span> <span class="ident">Error</span> {
<span class="ident">File</span>(<span class="ident">filename</span>: <span class="ident">PathBuf</span>, <span class="ident">err</span>: <span class="ident">io</span>::<span class="ident">Error</span>) {
<span class="ident">context</span>(<span class="ident">path</span>: <span class="kw-2">&amp;</span><span class="lifetime">&#39;a</span> <span class="ident">Path</span>, <span class="ident">err</span>: <span class="ident">io</span>::<span class="ident">Error</span>)
<span class="op">-&gt;</span> (<span class="ident">path</span>.<span class="ident">to_path_buf</span>(), <span class="ident">err</span>)
}
}
}
<span class="kw">fn</span> <span class="ident">openfile</span>(<span class="ident">path</span>: <span class="kw-2">&amp;</span><span class="ident">Path</span>) <span class="op">-&gt;</span> <span class="prelude-ty">Result</span><span class="op">&lt;</span>(), <span class="ident">Error</span><span class="op">&gt;</span> {
<span class="macro">try</span><span class="macro">!</span>(<span class="ident">File</span>::<span class="ident">open</span>(<span class="ident">path</span>).<span class="ident">context</span>(<span class="ident">path</span>));
<span class="comment">// If we didn&#39;t have context, the line above would be written as;</span>
<span class="comment">//</span>
<span class="comment">// try!(File::open(path)</span>
<span class="comment">// .map_err(|err| Error::File(path.to_path_buf(), err)));</span>
<span class="prelude-val">Ok</span>(())
}
</pre>
<p>Each <code>context(a: A, b: B)</code> clause implements
<code>From&lt;Context&lt;A, B&gt;&gt; for Error</code>. Which means multiple <code>context</code> clauses
are a subject to the normal coherence rules. Unfortunately, we can't
provide full support of generics for the context, but you may either use a
lifetime <code>'a</code> for references or <code>AsRef&lt;Type&gt;</code> (the latter means <code>A: AsRef&lt;Type&gt;</code>, and <code>Type</code> must be concrete). It's also occasionally useful
to use a tuple as a type of the first argument.</p>
<p>You also need to <code>use quick_error::ResultExt</code> extension trait to get
working <code>.context()</code> method.</p>
<p>More info on context in <a href="http://bit.ly/1PsuxDt">this article</a>.</p>
<p>All forms of <code>from</code>, <code>display</code>, <code>description</code>, <code>cause</code>, and <code>context</code>
clauses can be combined and put in arbitrary order. Only <code>from</code> and
<code>context</code> can be used multiple times in single variant of enumeration.
Docstrings are also okay. Empty braces can be omitted as of quick_error
0.1.3.</p>
<h1 id="private-enums" class="section-header"><a href="#private-enums">Private Enums</a></h1>
<p>Since quick-error 1.2.0 we have a way to make a private enum that is
wrapped by public structure:</p>
<pre class="rust rust-example-rendered">
<span class="attribute">#[<span class="ident">macro_use</span>]</span> <span class="kw">extern</span> <span class="kw">crate</span> <span class="ident">quick_error</span>;
<span class="macro">quick_error</span><span class="macro">!</span> {
<span class="attribute">#[<span class="ident">derive</span>(<span class="ident">Debug</span>)]</span>
<span class="kw">pub</span> <span class="kw">enum</span> <span class="ident">PubError</span> <span class="ident">wraps</span> <span class="ident">ErrorEnum</span> {
<span class="ident">Variant1</span> {}
}
}</pre>
<p>This generates data structures like this</p>
<pre class="rust rust-example-rendered">
<span class="kw">pub</span> <span class="kw">struct</span> <span class="ident">PubError</span>(<span class="ident">ErrorEnum</span>);
<span class="kw">enum</span> <span class="ident">ErrorEnum</span> {
<span class="ident">Variant1</span>,
}
</pre>
<p>Which in turn allows you to export just <code>PubError</code> in your crate and keep
actual enumeration private to the crate. This is useful to keep backwards
compatibility for error types. Currently there is no shorcuts to define
error constructors for the inner type, but we consider adding some in
future versions.</p>
<p>It's possible to declare internal enum as public too.</p>
</div><h2 id='macros' class='section-header'><a href="#macros">Macros</a></h2>
<table>
<tr class=' module-item'>
<td><a class="macro" href="macro.quick_error.html"
title='macro quick_error::quick_error'>quick_error</a></td>
<td class='docblock-short'>
<p>Main macro that does all the work</p>
</td>
</tr></table><h2 id='structs' class='section-header'><a href="#structs">Structs</a></h2>
<table>
<tr class=' module-item'>
<td><a class="struct" href="struct.Context.html"
title='struct quick_error::Context'>Context</a></td>
<td class='docblock-short'>
<p>Generic context type</p>
</td>
</tr></table><h2 id='traits' class='section-header'><a href="#traits">Traits</a></h2>
<table>
<tr class=' module-item'>
<td><a class="trait" href="trait.ResultExt.html"
title='trait quick_error::ResultExt'>ResultExt</a></td>
<td class='docblock-short'>
<p>Result extension trait adding a <code>context</code> method</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><kbd>?</kbd></dt>
<dd>Show this help dialog</dd>
<dt><kbd>S</kbd></dt>
<dd>Focus the search field</dd>
<dt><kbd>↑</kbd></dt>
<dd>Move up in search results</dd>
<dt><kbd>↓</kbd></dt>
<dd>Move down in search results</dd>
<dt><kbd>↹</kbd></dt>
<dd>Switch tab</dd>
<dt><kbd>&#9166;</kbd></dt>
<dd>Go to active search result</dd>
<dt><kbd>+</kbd></dt>
<dd>Expand all sections</dd>
<dt><kbd>-</kbd></dt>
<dd>Collapse all sections</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 = "quick_error";
</script>
<script src="../main.js"></script>
<script defer src="../search-index.js"></script>
</body>
</html>
Reference in a new issue Copy permalink