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

Sync README.md

This commit is contained in:
Gavrilikhin Daniil 2023-05-12 22:07:36 +08:00
parent 5e6795399e
commit 5c94dd08fc
1 changed files with 43 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
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)
@ -47,10 +47,11 @@ libraries and such might not want.
- [... multiple related errors](#-multiple-related-errors) - [... multiple related errors](#-multiple-related-errors)
- [... delayed source code](#-delayed-source-code) - [... delayed source code](#-delayed-source-code)
- [... handler options](#-handler-options) - [... handler options](#-handler-options)
- [... dynamic diagnostics](#-dynamic-diagnostics)
- [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`].
@ -75,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
@ -87,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
/* /*
@ -169,9 +170,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
@ -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 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
@ -247,11 +248,11 @@ pub fn some_tool() -> Result<Version> {
} }
``` ```
To construct your own simple adhoc error use the `miette::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::{IntoDiagnostic, Result, WrapErr, miette}; use miette::{miette, IntoDiagnostic, Result, WrapErr};
use semver::Version; use semver::Version;
pub fn some_tool() -> Result<Version> { pub fn some_tool() -> Result<Version> {
@ -262,9 +263,7 @@ pub fn some_tool() -> Result<Version> {
} }
``` ```
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 `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
@ -294,7 +293,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:
@ -347,7 +346,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
@ -395,8 +394,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
@ -432,7 +430,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.
@ -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. 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)
@ -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 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
@ -568,7 +566,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
@ -587,13 +585,32 @@ 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!
### 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 `miette` was not developed in a void. It owes enormous credit to various
other projects and their authors: other projects and their authors:
@ -612,7 +629,7 @@ other projects and their authors:
- [`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).
@ -623,11 +640,13 @@ under the Apache License. Some code is taken from
[`ariadne`](https://github.com/zesterer/ariadne), which is MIT licensed. [`ariadne`](https://github.com/zesterer/ariadne), which is MIT licensed.
[`miette!`]: https://docs.rs/miette/latest/miette/macro.miette.html [`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 [`std::error::Error`]: https://doc.rust-lang.org/nightly/std/error/trait.Error.html
[`Diagnostic`]: https://docs.rs/miette/latest/miette/trait.Diagnostic.html [`Diagnostic`]: https://docs.rs/miette/latest/miette/trait.Diagnostic.html
[`IntoDiagnostic`]: https://docs.rs/miette/latest/miette/trait.IntoDiagnostic.html [`IntoDiagnostic`]: https://docs.rs/miette/latest/miette/trait.IntoDiagnostic.html
[`MietteHandlerOpts`]: https://docs.rs/miette/latest/miette/struct.MietteHandlerOpts.html [`MietteHandlerOpts`]: https://docs.rs/miette/latest/miette/struct.MietteHandlerOpts.html
[`MietteHandler`]: https://docs.rs/miette/latest/miette/struct.MietteHandler.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 [`Report`]: https://docs.rs/miette/latest/miette/struct.Report.html
[`ReportHandler`]: https://docs.rs/miette/latest/miette/struct.ReportHandler.html [`ReportHandler`]: https://docs.rs/miette/latest/miette/struct.ReportHandler.html
[`Result`]: https://docs.rs/miette/latest/miette/type.Result.html [`Result`]: https://docs.rs/miette/latest/miette/type.Result.html