From bfacb6329f0063b5dc5a8c0b4344743cf3fa183a Mon Sep 17 00:00:00 2001 From: Gavrilikhin Daniil Date: Sun, 16 Jul 2023 04:46:54 +0300 Subject: [PATCH] doc: document `#[diagnostic(transparent)]` (#266) --- README.md | 75 ++++++++++++++++++++++++++++++++---------------------- src/lib.rs | 14 +++++++++- 2 files changed, 57 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 8375876..a60ef11 100644 --- a/README.md +++ b/README.md @@ -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 +### Table of Contents - [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 { } ``` -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 { .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). diff --git a/src/lib.rs b/src/lib.rs index cc113ce..20589ef 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -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 //! } //! ``` //!