Add dynamic diagnostic

CONTRIBUTING.md

@@ -23,7 +23,7 @@
 
 ## Introduction
 
-Thank you so much for your interest in contributing!. All types of contributions are encouraged and valued. See the [table of contents](#toc) for different ways to help and details about how this project handles them!📝
+Thank you so much for your interest in contributing! All types of contributions are encouraged and valued. See the [table of contents](#toc) for different ways to help and details about how this project handles them!📝
 
 Please make sure to read the relevant section before making your contribution! It will make it a lot easier for us maintainers to make the most of it and smooth out the experience for all involved. 💚
 

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

README.tpl

@@ -4,11 +4,13 @@
 {{readme}}
 
 [`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/struct.Diagnostic.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