diff --git a/README.md b/README.md index c12734d..ff25b3a 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) @@ -47,10 +47,11 @@ libraries and such might not want. - [... multiple related errors](#-multiple-related-errors) - [... delayed source code](#-delayed-source-code) - [... handler options](#-handler-options) + - [... dynamic diagnostics](#-dynamic-diagnostics) - [Acknowledgements](#acknowledgements) - [License](#license) -### Features +## Features - Generic [`Diagnostic`] protocol, compatible (and dependent on) [`std::error::Error`]. @@ -75,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 @@ -87,7 +88,7 @@ If you want to use the fancy printer in all these screenshots: $ cargo add miette --features fancy ``` -### Example +## Example ```rust /* @@ -169,9 +170,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 @@ -205,7 +206,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 @@ -247,11 +248,11 @@ pub fn some_tool() -> Result { } ``` -To construct your own simple adhoc error use the `miette::miette!` macro: +To construct your own simple adhoc error use the [`miette!`] macro: ```rust // my_app/lib/my_internal_file.rs -use miette::{IntoDiagnostic, Result, WrapErr, miette}; +use miette::{miette, IntoDiagnostic, Result, WrapErr}; use semver::Version; pub fn some_tool() -> Result { @@ -262,9 +263,7 @@ pub fn some_tool() -> Result { } ``` -There are also similar `miette::bail!` and `miette::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 @@ -294,7 +293,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: @@ -347,7 +346,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 @@ -395,8 +394,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 @@ -432,7 +430,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. @@ -452,7 +450,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) @@ -535,7 +533,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 @@ -568,7 +566,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 @@ -587,13 +585,32 @@ miette::set_hook(Box::new(|_| { .build(), ) })) - ``` See the docs for [`MietteHandlerOpts`] for more details on what you can customize! -### Acknowledgements +### ... dynamic diagnostics + +If you... +- ...don't know all the possible errors upfront +- ...need to serialize/deserialize errors +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[ + LabeledSpan::at(12..13, "this should be 6"), + ], + help = "'*' has greater precedence than '+'", + "Wrong answer" +).with_source_code(source); +println!("{:?}", report) +``` + +## Acknowledgements `miette` was not developed in a void. It owes enormous credit to various other projects and their authors: @@ -612,7 +629,7 @@ other projects and their authors: - [`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). @@ -623,11 +640,13 @@ under the Apache License. Some code is taken from [`ariadne`](https://github.com/zesterer/ariadne), which is MIT licensed. [`miette!`]: https://docs.rs/miette/latest/miette/macro.miette.html +[`diagnostic!`]: https://docs.rs/miette/latest/miette/macro.diagnostic.html [`std::error::Error`]: https://doc.rust-lang.org/nightly/std/error/trait.Error.html [`Diagnostic`]: https://docs.rs/miette/latest/miette/trait.Diagnostic.html [`IntoDiagnostic`]: https://docs.rs/miette/latest/miette/trait.IntoDiagnostic.html [`MietteHandlerOpts`]: https://docs.rs/miette/latest/miette/struct.MietteHandlerOpts.html [`MietteHandler`]: https://docs.rs/miette/latest/miette/struct.MietteHandler.html +[`MietteDiagnostic`]: https://docs.rs/miette/latest/miette/struct.MietteDiagnostic.html [`Report`]: https://docs.rs/miette/latest/miette/struct.Report.html [`ReportHandler`]: https://docs.rs/miette/latest/miette/struct.ReportHandler.html [`Result`]: https://docs.rs/miette/latest/miette/type.Result.html