Crate miette

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

DefaultReportPrinter

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.

DiagnosticError

Convenience Diagnostic that can be used as an “anonymous” wrapper for Errors. This is intended to be paired with IntoDiagnostic.

DiagnosticReport

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.

DiagnosticSnippet

A snippet from a Source to be displayed with a message and possibly some highlights.

JokeReporter

Literally what it says on the tin.

MietteCharacters

MietteSpanContents

Basic implementation of the SpanContents trait, for convenience.

MietteStyles

MietteTheme

NarratableReportPrinter

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.

SourceOffset

Newtype that represents the ByteOffset from the beginning of a Source

SourceSpan

Span within a Source with an associated message.

Enums

MietteError

Error enum for miette. Used by certain operations in the protocol.

Severity

Diagnostic severity. Intended to be used by DiagnosticReportPrinters to change the way different Diagnostics are displayed.

Traits

Diagnostic

Adds rich metadata to your Error that can be used by DiagnosticReportPrinter to print really nice and human-friendly error messages.

DiagnosticReportPrinter

Protocol for Diagnostic handlers, which are responsible for actually printing out Diagnostics.

IntoDiagnostic

Source

Represents a readable source of some sort.

SpanContents

Contents of a Source covered by SourceSpan.

Functions

get_reporter

Used by [DiagnosticReport] to fetch the reporter that will be used to print stuff out.

set_reporter

Set the global DiagnosticReportPrinter that will be used when you report using [DiagnosticReport].

Type Definitions

ByteOffset

“Raw” type for the byte offset from the beginning of a Source.

DiagnosticResult

Convenience alias. This is intended to be used as the return type for main()

Derive Macros

Diagnostic