Crate miette[−][src]
Expand description
you run miette? You run her code like the software? Oh. Oh! Error code for coder! Error code for One Thousand Lines!
About
miette
is a diagnostic library for Rust. It includes a series of protocols
that allow you to hook into its error reporting facilities, and even write
your own error reports! It lets you define error types that can print out like
this (or in any format you like!):
The Diagnostic trait in miette
is an extension of std::error::Error
that
adds various facilities like Severity, error codes that could be looked up
by users, and snippet display with support for multiline reports, arbitrary
Sources, and pretty printing.
miette
also includes a (lightweight) anyhow
/eyre
-style
DiagnosticReport type which can be returned from application-internal
functions to make the ?
experience nicer. It’s extra easy to use when using
DiagnosticResult!
While the miette
crate bundles some baseline implementations for Source
and DiagnosticReportPrinter, it’s intended to define a protocol that other crates
can build on top of to provide rich error reporting, and encourage an
ecosystem that leans on this extra metadata to provide it for others in a way
that’s compatible with std::error::Error.
Installing
Using cargo-edit
:
$ cargo add miette
Example and Guide
/*
You can derive a Diagnostic from any `std::error::Error` type.
`thiserror` is a great way to define them, and plays nicely with `miette`!
*/
use miette::{Diagnostic, SourceSpan};
use thiserror::Error;
#[derive(Error, Debug, Diagnostic)]
#[error("oops!")]
#[diagnostic(
code(oops::my::bad),
help("try doing it better next time?"),
)]
struct MyBad {
// The Source that we're gonna be printing snippets out of.
src: String,
// Snippets and highlights can be included in the diagnostic!
#[snippet(src, "This is the part that broke")]
snip: SourceSpan,
#[highlight(snip)]
bad_bit: SourceSpan,
}
/*
Now let's define a function!
Use this DiagnosticResult type (or its expanded version) as the return type
throughout your app (but NOT your libraries! Those should always return concrete
types!).
*/
use miette::DiagnosticResult as Result;
fn this_fails() -> Result<()> {
// You can use plain strings as a `Source`, or anything that implements
// the one-method `Source` trait.
let src = "source\n text\n here".to_string();
let len = src.len();
Err(MyBad {
src,
snip: ("bad_file.rs", 0, len).into(),
bad_bit: ("this bit here", 9, 4).into(),
})?;
Ok(())
}
/*
Now to get everything printed nicely, just return a Result<(), DiagnosticReport>
and you're all set!
Note: You can swap out the default reporter for a custom one using `miette::set_reporter()`
*/
fn pretend_this_is_main() -> Result<()> {
// kaboom~
this_fails()?;
Ok(())
}
And this is the output you’ll get if you run this program:
License
miette
is released to the Rust community under the Apache license 2.0.
It also includes some code taken from eyre
,
and some from thiserror
, also under
the Apache License. Some code is taken from
ariadne
, which is MIT licensed.
Structs
Reference implementation of the DiagnosticReportPrinter trait. This is generally
good enough for simple use-cases, and is the default one installed with miette
,
but you might want to implement your own if you want custom reporting for your
tool or app.
Convenience Diagnostic that can be used as an “anonymous” wrapper for Errors. This is intended to be paired with IntoDiagnostic.
When used with ?
/From
, this will wrap any Diagnostics and, when
formatted with Debug
, will fetch the current DiagnosticReportPrinter and
use it to format the inner Diagnostic.
A snippet from a Source to be displayed with a message and possibly some highlights.
Literally what it says on the tin.
Basic implementation of the SpanContents trait, for convenience.
Reference implementation of the DiagnosticReportPrinter trait. This is generally
good enough for simple use-cases, and is the default one installed with miette
,
but you might want to implement your own if you want custom reporting for your
tool or app.
Newtype that represents the ByteOffset from the beginning of a Source
Span within a Source with an associated message.
Enums
Error enum for miette. Used by certain operations in the protocol.
Diagnostic severity. Intended to be used by DiagnosticReportPrinters to change the way different Diagnostics are displayed.
Traits
Adds rich metadata to your Error that can be used by DiagnosticReportPrinter to print really nice and human-friendly error messages.
Protocol for Diagnostic handlers, which are responsible for actually printing out Diagnostics.
Represents a readable source of some sort.
Contents of a Source covered by SourceSpan.
Functions
Used by [DiagnosticReport] to fetch the reporter that will be used to print stuff out.
Set the global DiagnosticReportPrinter that will be used when you report using [DiagnosticReport].
Type Definitions
“Raw” type for the byte offset from the beginning of a Source.
Convenience alias. This is intended to be used as the return type for main()