mirror of
https://github.com/haraldh/chainerror.git
synced 2025-06-08 08:54:43 +02:00
publish: chore: Release chainerror version 1.0.0
generated from commit 24382fbaed
This commit is contained in:
parent
4d8e0bf76f
commit
7ebd88a910
GPG key ID:
900F3C4971086004
32 changed files with 6154 additions and 8673 deletions
199
index.html
199
index.html
|
|
@ -4,25 +4,16 @@
|
|||
<!-- Book generated using mdBook -->
|
||||
<meta charset="UTF-8">
|
||||
<title>chainerror - chainerror</title>
|
||||
|
||||
|
||||
|
||||
|
||||
<!-- Custom HTML head -->
|
||||
|
||||
|
||||
|
||||
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
|
||||
<meta name="description" content="A tutorial for the chainerror rust crate.">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<meta name="theme-color" content="#ffffff" />
|
||||
|
||||
|
||||
<link rel="icon" href="favicon.svg">
|
||||
|
||||
|
||||
<link rel="shortcut icon" href="favicon.png">
|
||||
|
||||
<link rel="stylesheet" href="css/variables.css">
|
||||
<link rel="stylesheet" href="css/general.css">
|
||||
<link rel="stylesheet" href="css/chrome.css">
|
||||
|
|
@ -30,9 +21,7 @@
|
|||
|
||||
<!-- Fonts -->
|
||||
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
|
||||
|
||||
<link rel="stylesheet" href="fonts/fonts.css">
|
||||
|
||||
|
||||
<!-- Highlight.js Stylesheets -->
|
||||
<link rel="stylesheet" href="highlight.css">
|
||||
|
|
@ -40,19 +29,18 @@
|
|||
<link rel="stylesheet" href="ayu-highlight.css">
|
||||
|
||||
<!-- Custom theme stylesheets -->
|
||||
|
||||
|
||||
|
||||
</head>
|
||||
<body>
|
||||
<div id="body-container">
|
||||
<!-- Provide site root to javascript -->
|
||||
<script type="text/javascript">
|
||||
<script>
|
||||
var path_to_root = "";
|
||||
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
|
||||
</script>
|
||||
|
||||
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||||
<script type="text/javascript">
|
||||
<script>
|
||||
try {
|
||||
var theme = localStorage.getItem('mdbook-theme');
|
||||
var sidebar = localStorage.getItem('mdbook-sidebar');
|
||||
|
|
@ -68,7 +56,7 @@
|
|||
</script>
|
||||
|
||||
<!-- Set the theme before any content is loaded, prevents flash -->
|
||||
<script type="text/javascript">
|
||||
<script>
|
||||
var theme;
|
||||
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||||
if (theme === null || theme === undefined) { theme = default_theme; }
|
||||
|
|
@ -80,12 +68,14 @@
|
|||
</script>
|
||||
|
||||
<!-- Hide / unhide sidebar before it is displayed -->
|
||||
<script type="text/javascript">
|
||||
<script>
|
||||
var html = document.querySelector('html');
|
||||
var sidebar = 'hidden';
|
||||
var sidebar = null;
|
||||
if (document.body.clientWidth >= 1080) {
|
||||
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
||||
sidebar = sidebar || 'visible';
|
||||
} else {
|
||||
sidebar = 'hidden';
|
||||
}
|
||||
html.classList.remove('sidebar-visible');
|
||||
html.classList.add("sidebar-" + sidebar);
|
||||
|
|
@ -98,12 +88,33 @@
|
|||
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
|
||||
</nav>
|
||||
|
||||
<!-- Track and set sidebar scroll position -->
|
||||
<script>
|
||||
var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
|
||||
sidebarScrollbox.addEventListener('click', function(e) {
|
||||
if (e.target.tagName === 'A') {
|
||||
sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
|
||||
}
|
||||
}, { passive: true });
|
||||
var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
|
||||
sessionStorage.removeItem('sidebar-scroll');
|
||||
if (sidebarScrollTop) {
|
||||
// preserve sidebar scroll position when navigating via links within sidebar
|
||||
sidebarScrollbox.scrollTop = sidebarScrollTop;
|
||||
} else {
|
||||
// scroll sidebar to current active section when navigating via "next/previous chapter" buttons
|
||||
var activeSection = document.querySelector('#sidebar .active');
|
||||
if (activeSection) {
|
||||
activeSection.scrollIntoView({ block: 'center' });
|
||||
}
|
||||
}
|
||||
</script>
|
||||
|
||||
<div id="page-wrapper" class="page-wrapper">
|
||||
|
||||
<div class="page">
|
||||
|
||||
<div id="menu-bar-hover-placeholder"></div>
|
||||
<div id="menu-bar" class="menu-bar sticky bordered">
|
||||
<div id="menu-bar-hover-placeholder"></div>
|
||||
<div id="menu-bar" class="menu-bar sticky">
|
||||
<div class="left-buttons">
|
||||
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
||||
<i class="fa fa-bars"></i>
|
||||
|
|
@ -112,17 +123,15 @@
|
|||
<i class="fa fa-paint-brush"></i>
|
||||
</button>
|
||||
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
||||
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
||||
</ul>
|
||||
|
||||
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
|
||||
<i class="fa fa-search"></i>
|
||||
</button>
|
||||
|
||||
</div>
|
||||
|
||||
<h1 class="menu-title">chainerror</h1>
|
||||
|
|
@ -131,14 +140,13 @@
|
|||
<a href="print.html" title="Print this book" aria-label="Print this book">
|
||||
<i id="print-button" class="fa fa-print"></i>
|
||||
</a>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
<div id="search-wrapper" class="hidden">
|
||||
<form id="searchbar-outer" class="searchbar-outer">
|
||||
<input type="search" name="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
||||
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
||||
</form>
|
||||
<div id="searchresults-outer" class="searchresults-outer hidden">
|
||||
<div id="searchresults-header" class="searchresults-header"></div>
|
||||
|
|
@ -146,10 +154,9 @@
|
|||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
||||
<script type="text/javascript">
|
||||
<script>
|
||||
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
||||
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
||||
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
||||
|
|
@ -161,12 +168,9 @@
|
|||
<main>
|
||||
<p><a href="https://crates.io/crates/chainerror"><img src="https://img.shields.io/crates/v/chainerror.svg" alt="Crate" /></a>
|
||||
<a href="https://docs.rs/chainerror/"><img src="https://img.shields.io/badge/api-rustdoc-blue.svg" alt="Rust Documentation" /></a>
|
||||
<a href="https://coveralls.io/github/haraldh/chainerror?branch=master"><img src="https://coveralls.io/repos/github/haraldh/chainerror/badge.svg?branch=master" alt="Coverage Status" /></a>
|
||||
<a href="https://github.com/haraldh/chainerror/actions?query=workflow%3A%22Rust%22"><img src="https://github.com/haraldh/chainerror/workflows/Rust/badge.svg" alt="Workflow Status" /></a>
|
||||
<a href="https://isitmaintained.com/project/haraldh/chainerror" title="Average time to resolve an issue"><img src="https://isitmaintained.com/badge/resolution/haraldh/chainerror.svg" alt="Average time to resolve an issue" /></a>
|
||||
<a href="https://isitmaintained.com/project/haraldh/chainerror" title="Percentage of issues still open"><img src="https://isitmaintained.com/badge/open/haraldh/chainerror.svg" alt="Percentage of issues still open" /></a>
|
||||
<a href="https://codecov.io/gh/haraldh/chainerror"><img src="https://codecov.io/gh/haraldh/chainerror/branch/master/graph/badge.svg?token=HGLJFGA11B" alt="Coverage Status" /></a>
|
||||
<img src="https://img.shields.io/badge/maintenance-activly--developed-brightgreen.svg" alt="Maintenance" /></p>
|
||||
<h1><a class="header" href="#chainerror" id="chainerror">chainerror</a></h1>
|
||||
<h1 id="chainerror"><a class="header" href="#chainerror">chainerror</a></h1>
|
||||
<p><code>chainerror</code> provides an error backtrace without doing a real backtrace, so even after you <code>strip</code> your
|
||||
binaries, you still have the error backtrace.</p>
|
||||
<p>Having nested function returning errors, the output doesn't tell where the error originates from.</p>
|
||||
|
|
@ -191,15 +195,14 @@ fn main() {
|
|||
if let Err(e) = process_config_file() {
|
||||
eprintln!("Error:\n{:?}", e);
|
||||
}
|
||||
}
|
||||
</code></pre></pre>
|
||||
}</code></pre></pre>
|
||||
<p>This gives the output:</p>
|
||||
<pre><code class="language-console">Error:
|
||||
Os { code: 2, kind: NotFound, message: "No such file or directory" }
|
||||
</code></pre>
|
||||
<p>and you have no idea where it comes from.</p>
|
||||
<p>With <code>chainerror</code>, you can supply a context and get a nice error backtrace:</p>
|
||||
<pre><pre class="playground"><code class="language-rust">use chainerror::prelude::v1::*;
|
||||
<pre><pre class="playground"><code class="language-rust">use chainerror::Context as _;
|
||||
use std::path::PathBuf;
|
||||
|
||||
type BoxedError = Box<dyn std::error::Error + Send + Sync>;
|
||||
|
|
@ -221,8 +224,7 @@ fn main() {
|
|||
if let Err(e) = process_config_file() {
|
||||
eprintln!("Error:\n{:?}", e);
|
||||
}
|
||||
}
|
||||
</code></pre></pre>
|
||||
}</code></pre></pre>
|
||||
<p>with the output:</p>
|
||||
<pre><code class="language-console">Error:
|
||||
examples/simple.rs:14:51: read the config file
|
||||
|
|
@ -233,22 +235,92 @@ Os { code: 2, kind: NotFound, message: "No such file or directory" }
|
|||
</code></pre>
|
||||
<p><code>chainerror</code> uses <code>.source()</code> of <code>std::error::Error</code> along with <code>#[track_caller]</code> and <code>Location</code> to provide a nice debug error backtrace.
|
||||
It encapsulates all types, which have <code>Display + Debug</code> and can store the error cause internally.</p>
|
||||
<p>Along with the <code>ChainError<T></code> struct, <code>chainerror</code> comes with some useful helper macros to save a lot of typing.</p>
|
||||
<p>Along with the <code>Error<T></code> struct, <code>chainerror</code> comes with some useful helper macros to save a lot of typing.</p>
|
||||
<p><code>chainerror</code> has no dependencies!</p>
|
||||
<p>Debug information is worth it!</p>
|
||||
<h3><a class="header" href="#features" id="features">Features</a></h3>
|
||||
<p><code>display-cause</code>
|
||||
: turn on printing a backtrace of the errors in <code>Display</code></p>
|
||||
<h2><a class="header" href="#tutorial" id="tutorial">Tutorial</a></h2>
|
||||
<h2 id="multiple-output-formats"><a class="header" href="#multiple-output-formats">Multiple Output Formats</a></h2>
|
||||
<p><code>chainerror</code> supports multiple output formats, which can be selected with the different format specifiers:</p>
|
||||
<ul>
|
||||
<li><code>{}</code>: Display</li>
|
||||
</ul>
|
||||
<pre><code class="language-console">func1 error calling func2
|
||||
</code></pre>
|
||||
<ul>
|
||||
<li><code>{:#}</code>: Alternative Display</li>
|
||||
</ul>
|
||||
<pre><code class="language-console">func1 error calling func2
|
||||
Caused by:
|
||||
func2 error: calling func3
|
||||
Caused by:
|
||||
(passed error)
|
||||
Caused by:
|
||||
Error reading 'foo.txt'
|
||||
Caused by:
|
||||
entity not found
|
||||
</code></pre>
|
||||
<ul>
|
||||
<li><code>{:?}</code>: Debug</li>
|
||||
</ul>
|
||||
<pre><code class="language-console">examples/example.rs:50:13: func1 error calling func2
|
||||
Caused by:
|
||||
examples/example.rs:25:13: Func2Error(func2 error: calling func3)
|
||||
Caused by:
|
||||
examples/example.rs:18:13: (passed error)
|
||||
Caused by:
|
||||
examples/example.rs:13:18: Error reading 'foo.txt'
|
||||
Caused by:
|
||||
Kind(NotFound)
|
||||
|
||||
</code></pre>
|
||||
<ul>
|
||||
<li><code>{:#?}</code>: Alternative Debug</li>
|
||||
</ul>
|
||||
<pre><code class="language-console">Error<example::Func1Error> {
|
||||
occurrence: Some(
|
||||
"examples/example.rs:50:13",
|
||||
),
|
||||
kind: func1 error calling func2,
|
||||
source: Some(
|
||||
Error<example::Func2Error> {
|
||||
occurrence: Some(
|
||||
"examples/example.rs:25:13",
|
||||
),
|
||||
kind: Func2Error(func2 error: calling func3),
|
||||
source: Some(
|
||||
Error<chainerror::AnnotatedError> {
|
||||
occurrence: Some(
|
||||
"examples/example.rs:18:13",
|
||||
),
|
||||
kind: (passed error),
|
||||
source: Some(
|
||||
Error<alloc::string::String> {
|
||||
occurrence: Some(
|
||||
"examples/example.rs:13:18",
|
||||
),
|
||||
kind: "Error reading 'foo.txt'",
|
||||
source: Some(
|
||||
Kind(
|
||||
NotFound,
|
||||
),
|
||||
),
|
||||
},
|
||||
),
|
||||
},
|
||||
),
|
||||
},
|
||||
),
|
||||
}
|
||||
</code></pre>
|
||||
<h2 id="tutorial"><a class="header" href="#tutorial">Tutorial</a></h2>
|
||||
<p>Read the <a href="https://haraldh.github.io/chainerror/tutorial1.html">Tutorial</a></p>
|
||||
<h2><a class="header" href="#license" id="license">License</a></h2>
|
||||
<h2 id="license"><a class="header" href="#license">License</a></h2>
|
||||
<p>Licensed under either of</p>
|
||||
<ul>
|
||||
<li>Apache License, Version 2.0, (<a href="LICENSE-APACHE">LICENSE-APACHE</a> or https://www.apache.org/licenses/LICENSE-2.0)</li>
|
||||
<li>MIT license (<a href="LICENSE-MIT">LICENSE-MIT</a> or https://opensource.org/licenses/MIT)</li>
|
||||
<li>Apache License, Version 2.0, (<a href="LICENSE-APACHE">LICENSE-APACHE</a> or <a href="https://www.apache.org/licenses/LICENSE-2.0">https://www.apache.org/licenses/LICENSE-2.0</a>)</li>
|
||||
<li>MIT license (<a href="LICENSE-MIT">LICENSE-MIT</a> or <a href="https://opensource.org/licenses/MIT">https://opensource.org/licenses/MIT</a>)</li>
|
||||
</ul>
|
||||
<p>at your option.</p>
|
||||
<h3><a class="header" href="#contribution" id="contribution">Contribution</a></h3>
|
||||
<h3 id="contribution"><a class="header" href="#contribution">Contribution</a></h3>
|
||||
<p>Unless you explicitly state otherwise, any contribution intentionally
|
||||
submitted for inclusion in the work by you, as defined in the Apache-2.0
|
||||
license, shall be dual licensed as above, without any additional terms or
|
||||
|
|
@ -258,13 +330,10 @@ conditions.</p>
|
|||
|
||||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||||
<!-- Mobile navigation buttons -->
|
||||
|
||||
|
||||
|
||||
<a rel="next" href="tutorial1.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||||
<i class="fa fa-angle-right"></i>
|
||||
</a>
|
||||
|
||||
|
||||
<div style="clear: both"></div>
|
||||
</nav>
|
||||
|
|
@ -272,45 +341,33 @@ conditions.</p>
|
|||
</div>
|
||||
|
||||
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
||||
|
||||
|
||||
|
||||
<a rel="next" href="tutorial1.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||||
<i class="fa fa-angle-right"></i>
|
||||
</a>
|
||||
|
||||
</nav>
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<script type="text/javascript">
|
||||
<script>
|
||||
window.playground_copyable = true;
|
||||
</script>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
|
||||
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
|
||||
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
|
||||
|
||||
<script src="elasticlunr.min.js"></script>
|
||||
<script src="mark.min.js"></script>
|
||||
<script src="searcher.js"></script>
|
||||
|
||||
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
|
||||
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
|
||||
<script src="book.js" type="text/javascript" charset="utf-8"></script>
|
||||
<script src="clipboard.min.js"></script>
|
||||
<script src="highlight.js"></script>
|
||||
<script src="book.js"></script>
|
||||
|
||||
<!-- Custom JS scripts -->
|
||||
|
||||
|
||||
|
||||
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue