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 You run miette? You run her code like the software? Oh. Oh! Error code for
coder! Error code for One Thousand Lines! coder! Error code for One Thousand Lines!
## About ### About
`miette` is a diagnostic library for Rust. It includes a series of `miette` is a diagnostic library for Rust. It includes a series of
traits/protocols that allow you to hook into its error reporting facilities, 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 toplevel crate, as the fancy feature pulls in a number of dependencies that
libraries and such might not want. libraries and such might not want.
## Table of Contents <!-- omit in toc --> ### Table of Contents <!-- omit in toc -->
- [About](#about) - [About](#about)
- [Features](#features) - [Features](#features)
@ -51,7 +51,7 @@ libraries and such might not want.
- [Acknowledgements](#acknowledgements) - [Acknowledgements](#acknowledgements)
- [License](#license) - [License](#license)
## Features ### Features
- Generic [`Diagnostic`] protocol, compatible (and dependent on) - Generic [`Diagnostic`] protocol, compatible (and dependent on)
[`std::error::Error`]. [`std::error::Error`].
@ -76,7 +76,7 @@ the following features:
- Cause chain printing - Cause chain printing
- Turns diagnostic codes into links in [supported terminals](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda). - Turns diagnostic codes into links in [supported terminals](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda).
## Installing ### Installing
```sh ```sh
$ cargo add miette $ cargo add miette
@ -88,7 +88,7 @@ If you want to use the fancy printer in all these screenshots:
$ cargo add miette --features fancy $ cargo add miette --features fancy
``` ```
## Example ### Example
```rust ```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 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"> 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 `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 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 ```rust
// lib/error.rs // lib/error.rs
use miette::Diagnostic; use miette::{Diagnostic, SourceSpan};
use thiserror::Error; use thiserror::Error;
#[derive(Error, Diagnostic, Debug)] #[derive(Error, Diagnostic, Debug)]
@ -197,6 +197,18 @@ pub enum MyLibError {
#[error("Oops it blew up")] #[error("Oops it blew up")]
#[diagnostic(code(my_lib::bad_code))] #[diagnostic(code(my_lib::bad_code))]
BadThingHappened, 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 practice to wrap any "external" error types in your error `enum` instead of
using something like [`Report`] in a library. using something like [`Report`] in a library.
### ... in application code #### ... in application code
Application code tends to work a little differently than libraries. You Application code tends to work a little differently than libraries. You
don't always need or care to define dedicated error wrappers for errors 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 ```rust
// my_app/lib/my_internal_file.rs // my_app/lib/my_internal_file.rs
use miette::{miette, IntoDiagnostic, Result, WrapErr}; use miette::{miette, IntoDiagnostic, Result, WrapErr};
@ -260,8 +271,9 @@ pub fn some_tool() -> Result<Version> {
.map_err(|_| miette!("Invalid version {}", 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 `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 `Result` as your return value, and it will pretty-print your diagnostics
@ -291,7 +303,7 @@ enabled:
miette = { version = "X.Y.Z", features = ["fancy"] } miette = { version = "X.Y.Z", features = ["fancy"] }
``` ```
### ... diagnostic code URLs #### ... diagnostic code URLs
`miette` supports providing a URL for individual diagnostics. This URL will `miette` supports providing a URL for individual diagnostics. This URL will
be displayed as an actual link in supported terminals, like so: be displayed as an actual link in supported terminals, like so:
@ -344,7 +356,7 @@ use thiserror::Error;
struct MyErr; struct MyErr;
``` ```
### ... snippets #### ... snippets
Along with its general error handling and reporting features, `miette` also Along with its general error handling and reporting features, `miette` also
includes facilities for adding error spans/annotations/labels to your 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: `miette` provides two facilities for supplying help text for your errors:
The first is the `#[help()]` format attribute that applies to structs or 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 `miette` supports collecting multiple errors into a single diagnostic, and
printing them all together nicely. 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. 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) 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 When one uses the `#[source]` attribute on a field, that usually comes
from `thiserror`, and implements a method for from `thiserror`, and implements a method for
@ -564,7 +576,7 @@ struct MyError {
struct OtherError; struct OtherError;
``` ```
### ... handler options #### ... handler options
[`MietteHandler`] is the default handler, and is very customizable. In [`MietteHandler`] is the default handler, and is very customizable. In
most cases, you can simply use [`MietteHandlerOpts`] to tweak its behavior most cases, you can simply use [`MietteHandlerOpts`] to tweak its behavior
@ -583,12 +595,13 @@ miette::set_hook(Box::new(|_| {
.build(), .build(),
) )
})) }))
``` ```
See the docs for [`MietteHandlerOpts`] for more details on what you can See the docs for [`MietteHandlerOpts`] for more details on what you can
customize! customize!
### ... dynamic diagnostics #### ... dynamic diagnostics
If you... If you...
- ...don't know all the possible errors upfront - ...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. [`MietteDiagnostic`] directly to create diagnostic on the fly.
```rust ```rust
let source = "2 + 2 * 2 = 8".to_string(); let source = "2 + 2 * 2 = 8".to_string();
let report = miette!( let report = miette!(
labels = vec[ labels = vec[
@ -608,26 +622,25 @@ let report = miette!(
println!("{:?}", report) println!("{:?}", report)
``` ```
## Acknowledgements ### Acknowledgements
`miette` was not developed in a void. It owes enormous credit to various `miette` was not developed in a void. It owes enormous credit to various
other projects and their authors: other projects and their authors:
- [`anyhow`](http://crates.io/crates/anyhow) and - [`anyhow`](http://crates.io/crates/anyhow) and [`color-eyre`](https://crates.io/crates/color-eyre):
[`color-eyre`](https://crates.io/crates/color-eyre): these two these two enormously influential error handling libraries have pushed
enormously influential error handling libraries have pushed forward the forward the experience of application-level error handling and error
experience of application-level error handling and error reporting. reporting. `miette`'s `Report` type is an attempt at a very very rough
`miette`'s `Report` type is an attempt at a very very rough version of version of their `Report` types.
their `Report` types. - [`thiserror`](https://crates.io/crates/thiserror) for setting the standard
- [`thiserror`](https://crates.io/crates/thiserror) for setting the for library-level error definitions, and for being the inspiration behind
standard for library-level error definitions, and for being the `miette`'s derive macro.
inspiration behind `miette`'s derive macro.
- `rustc` and [@estebank](https://github.com/estebank) for their - `rustc` and [@estebank](https://github.com/estebank) for their
state-of-the-art work in compiler diagnostics. state-of-the-art work in compiler diagnostics.
- [`ariadne`](https://crates.io/crates/ariadne) for pushing forward how - [`ariadne`](https://crates.io/crates/ariadne) for pushing forward how
_pretty_ these diagnostics can really look! _pretty_ these diagnostics can really look!
## License ### License
`miette` is released to the Rust community under the [Apache license `miette` is released to the Rust community under the [Apache license
2.0](./LICENSE). 2.0](./LICENSE).

14
src/lib.rs
View File

@ -186,7 +186,7 @@
//! //!
//! ```rust //! ```rust
//! // lib/error.rs //! // lib/error.rs
//! use miette::Diagnostic; //! use miette::{Diagnostic, SourceSpan};
//! use thiserror::Error; //! use thiserror::Error;
//! //!
//! #[derive(Error, Diagnostic, Debug)] //! #[derive(Error, Diagnostic, Debug)]
@ -198,6 +198,18 @@
//! #[error("Oops it blew up")] //! #[error("Oops it blew up")]
//! #[diagnostic(code(my_lib::bad_code))] //! #[diagnostic(code(my_lib::bad_code))]
//! BadThingHappened, //! 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
//! } //! }
//! ``` //! ```
//! //!