mirror of https://github.com/zkat/miette.git
Sync README.md
This commit is contained in:
Gavrilikhin Daniil
parent
5e6795399e
commit
5c94dd08fc
67
README.md
67
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 <!-- omit in toc -->
|
||||
## Table of Contents <!-- omit in toc -->
|
||||
|
||||
- [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<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
|
||||
// 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<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
|
||||
`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
|
||||
|
|
|
|||
Loading…
Reference in New Issue