berkus
/
miette
mirror of https://github.com/zkat/miette.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: document `#[diagnostic(transparent)]` (#266)

This commit is contained in:
Gavrilikhin Daniil 2023-07-16 04:46:54 +03:00 committed by GitHub
parent c3d4db2618
commit bfacb6329f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 57 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
README.md
View File

@ -4,7 +4,7 @@
You run miette? You run her code like the software? Oh. Oh! Error code for
coder! Error code for One Thousand Lines!
## About
### About
`miette` is a diagnostic library for Rust. It includes a series of
traits/protocols that allow you to hook into its error reporting facilities,
@ -32,7 +32,7 @@ output like in the screenshots above.** You should only do this in your
toplevel crate, as the fancy feature pulls in a number of dependencies that
libraries and such might not want.
## Table of Contents <!-- omit in toc -->
### Table of Contents <!-- omit in toc -->
- [About](#about)
- [Features](#features)
@ -51,7 +51,7 @@ libraries and such might not want.
- [Acknowledgements](#acknowledgements)
- [License](#license)
## Features
### Features
- Generic [`Diagnostic`] protocol, compatible (and dependent on)
[`std::error::Error`].
@ -76,7 +76,7 @@ the following features:
- Cause chain printing
- Turns diagnostic codes into links in [supported terminals](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda).
## Installing
### Installing
```sh
$ cargo add miette
@ -88,7 +88,7 @@ If you want to use the fancy printer in all these screenshots:
$ cargo add miette --features fancy
```
## Example
### Example
```rust
/*
@ -168,9 +168,9 @@ diagnostic help: Change int or string to be the right types and try again.
diagnostic code: nu::parser::unsupported_operation
For more details, see https://docs.rs/nu-parser/0.1.0/nu-parser/enum.ParseError.html#variant.UnsupportedOperation">
## Using
### Using
### ... in libraries
#### ... in libraries
`miette` is _fully compatible_ with library usage. Consumers who don't know
about, or don't want, `miette` features can safely use its error types as
@ -185,7 +185,7 @@ the trait directly, just like with `std::error::Error`.
```rust
// lib/error.rs
use miette::Diagnostic;
use miette::{Diagnostic, SourceSpan};
use thiserror::Error;
#[derive(Error, Diagnostic, Debug)]
@ -197,6 +197,18 @@ pub enum MyLibError {
#[error("Oops it blew up")]
#[diagnostic(code(my_lib::bad_code))]
BadThingHappened,
#[error(transparent)]
// Use `#[diagnostic(transparent)]` to wrap another [`Diagnostic`]. You won't see labels otherwise
#[diagnostic(transparent)]
AnotherError(#[from] AnotherError),
}
#[derive(Error, Diagnostic, Debug)]
#[error("another error")]
pub struct AnotherError {
#[label("here")]
pub at: SourceSpan
}
```
@ -204,7 +216,7 @@ Then, return this error type from all your fallible public APIs. It's a best
practice to wrap any "external" error types in your error `enum` instead of
using something like [`Report`] in a library.
### ... in application code
#### ... in application code
Application code tends to work a little differently than libraries. You
don't always need or care to define dedicated error wrappers for errors
@ -246,8 +258,7 @@ pub fn some_tool() -> Result<Version> {
}
```
To construct your own simple adhoc error use the [`miette!`] macro:
To construct your own simple adhoc error use the [miette!] macro:
```rust
// my_app/lib/my_internal_file.rs
use miette::{miette, IntoDiagnostic, Result, WrapErr};
@ -260,8 +271,9 @@ pub fn some_tool() -> Result<Version> {
.map_err(|_| miette!("Invalid version {}", version))?)
}
```
There are also similar [bail!] and [ensure!] macros.
### ... in `main()`
#### ... in `main()`
`main()` is just like any other part of your application-internal code. Use
`Result` as your return value, and it will pretty-print your diagnostics
@ -291,7 +303,7 @@ enabled:
miette = { version = "X.Y.Z", features = ["fancy"] }
```
### ... diagnostic code URLs
#### ... diagnostic code URLs
`miette` supports providing a URL for individual diagnostics. This URL will
be displayed as an actual link in supported terminals, like so:
@ -344,7 +356,7 @@ use thiserror::Error;
struct MyErr;
```
### ... snippets
#### ... snippets
Along with its general error handling and reporting features, `miette` also
includes facilities for adding error spans/annotations/labels to your
@ -392,7 +404,7 @@ pub struct MyErrorType {
}
```
#### ... help text
##### ... help text
`miette` provides two facilities for supplying help text for your errors:
The first is the `#[help()]` format attribute that applies to structs or
@ -428,7 +440,7 @@ let err = Foo {
};
```
### ... multiple related errors
#### ... multiple related errors
`miette` supports collecting multiple errors into a single diagnostic, and
printing them all together nicely.
@ -448,7 +460,7 @@ struct MyError {
}
```
### ... delayed source code
#### ... delayed source code
Sometimes it makes sense to add source code to the error message later.
One option is to use [`with_source_code()`](Report::with_source_code)
@ -531,7 +543,7 @@ fn main() -> miette::Result<()> {
}
```
### ... Diagnostic-based error sources.
#### ... Diagnostic-based error sources.
When one uses the `#[source]` attribute on a field, that usually comes
from `thiserror`, and implements a method for
@ -564,7 +576,7 @@ struct MyError {
struct OtherError;
```
### ... handler options
#### ... handler options
[`MietteHandler`] is the default handler, and is very customizable. In
most cases, you can simply use [`MietteHandlerOpts`] to tweak its behavior
@ -583,12 +595,13 @@ miette::set_hook(Box::new(|_| {
.build(),
)
}))
```
See the docs for [`MietteHandlerOpts`] for more details on what you can
customize!
### ... dynamic diagnostics
#### ... dynamic diagnostics
If you...
- ...don't know all the possible errors upfront
@ -597,6 +610,7 @@ then you may want to use [`miette!`], [`diagnostic!`] macros or
[`MietteDiagnostic`] directly to create diagnostic on the fly.
```rust
let source = "2 + 2 * 2 = 8".to_string();
let report = miette!(
labels = vec[
@ -608,26 +622,25 @@ let report = miette!(
println!("{:?}", report)
```
## Acknowledgements
### Acknowledgements
`miette` was not developed in a void. It owes enormous credit to various
other projects and their authors:
- [`anyhow`](http://crates.io/crates/anyhow) and
[`color-eyre`](https://crates.io/crates/color-eyre): these two
enormously influential error handling libraries have pushed forward the
experience of application-level error handling and error reporting.
`miette`'s `Report` type is an attempt at a very very rough version of
their `Report` types.
- [`thiserror`](https://crates.io/crates/thiserror) for setting the
standard for library-level error definitions, and for being the
inspiration behind `miette`'s derive macro.
- [`anyhow`](http://crates.io/crates/anyhow) and [`color-eyre`](https://crates.io/crates/color-eyre):
these two enormously influential error handling libraries have pushed
forward the experience of application-level error handling and error
reporting. `miette`'s `Report` type is an attempt at a very very rough
version of their `Report` types.
- [`thiserror`](https://crates.io/crates/thiserror) for setting the standard
for library-level error definitions, and for being the inspiration behind
`miette`'s derive macro.
- `rustc` and [@estebank](https://github.com/estebank) for their
state-of-the-art work in compiler diagnostics.
- [`ariadne`](https://crates.io/crates/ariadne) for pushing forward how
_pretty_ these diagnostics can really look!
## License
### License
`miette` is released to the Rust community under the [Apache license
2.0](./LICENSE).

14
src/lib.rs
View File

@ -186,7 +186,7 @@
//!
//! ```rust
//! // lib/error.rs
//! use miette::Diagnostic;
//! use miette::{Diagnostic, SourceSpan};
//! use thiserror::Error;
//!
//! #[derive(Error, Diagnostic, Debug)]
@ -198,6 +198,18 @@
//! #[error("Oops it blew up")]
//! #[diagnostic(code(my_lib::bad_code))]
//! BadThingHappened,
//!
//! #[error(transparent)]
//! // Use `#[diagnostic(transparent)]` to wrap another [`Diagnostic`]. You won't see labels otherwise
//! #[diagnostic(transparent)]
//! AnotherError(#[from] AnotherError),
//! }
//!
//! #[derive(Error, Diagnostic, Debug)]
//! #[error("another error")]
//! pub struct AnotherError {
//! #[label("here")]
//! pub at: SourceSpan
//! }
//! ```
//!