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. 💚
 

src/eyreish/macros.rs

@@ -48,6 +48,17 @@
 /// #     Ok(())
 /// # }
 /// ```
+///
+/// ```
+/// use miette::{bail, Result, Severity};
+///
+/// fn divide(x: f64, y: f64) -> Result<f64> {
+///     if y.abs() < 1e-3 {
+///         bail!("dividing by value close to 0", severity = Severity::Warning);
+///     }
+///     Ok(x / y)
+/// }
+/// ```
 #[macro_export]
 macro_rules! bail {
     ($msg:literal $(,)?) => {
@@ -56,6 +67,9 @@ macro_rules! bail {
     ($err:expr $(,)?) => {
         return $crate::private::Err($crate::miette!($err));
     };
+    ($fmt:expr $(, $key:ident = $value:expr)* $(,)?) => {
+        return $crate::private::Err($crate::miette!($fmt, $($key = $value),*));
+    };
     ($fmt:expr, $($arg:tt)*) => {
         return $crate::private::Err($crate::miette!($fmt, $($arg)*));
     };
@@ -105,6 +119,19 @@ macro_rules! bail {
 /// #     Ok(())
 /// # }
 /// ```
+///
+/// ```
+/// use miette::{ensure, Result, Severity};
+///
+/// fn divide(x: f64, y: f64) -> Result<f64> {
+///     ensure!(
+///         y.abs() >= 1e-3,
+///         "dividing by value close to 0",
+///         severity = Severity::Warning
+///     );
+///     Ok(x / y)
+/// }
+/// ```
 #[macro_export]
 macro_rules! ensure {
     ($cond:expr, $msg:literal $(,)?) => {
@@ -117,21 +144,23 @@ macro_rules! ensure {
             return $crate::private::Err($crate::miette!($err));
         }
     };
+    ($cond:expr, $fmt:expr $(, $key:ident = $value:expr)* $(,)?) => {
+        if !$cond {
+            return $crate::private::Err($crate::miette!($fmt, $($key = $value),*));
+        }
+    };
     ($cond:expr, $fmt:expr, $($arg:tt)*) => {
         if !$cond {
             return $crate::private::Err($crate::miette!($fmt, $($arg)*));
         }
     };
 }
 
-/// Construct an ad-hoc error from a string.
-///
-/// This evaluates to an `Error`. It can take either just a string, or a format
-/// string with arguments. It also can take any custom type which implements
-/// `Debug` and `Display`.
+/// Construct an ad-hoc [`Report`].
 ///
-/// # Example
+/// # Examples
 ///
+/// With string literal and interpolation:
 /// ```
 /// # type V = ();
 /// #
@@ -147,6 +176,23 @@ macro_rules! ensure {
 /// }
 /// ```
 ///
+/// With [`MietteDiagnostic`]-like arguments:
+/// ```
+/// use miette::{miette, LabeledSpan, Severity};
+///
+/// let source = "(2 + 2".to_string();
+/// let report = miette!(
+///     "expected closing ')'",
+///     // Those fields are optional
+///     severity = Severity::Error,
+///     code = "expected::rparen",
+///     help = "always close your parens",
+///     labels = vec![LabeledSpan::at_offset(6, "here")],
+///     url = "https://example.com"
+/// )
+/// .with_source_code(source);
+/// ```
+///
 /// ## `anyhow`/`eyre` Users
 ///
 /// You can just replace `use`s of the `anyhow!`/`eyre!` macros with `miette!`.
@@ -162,7 +208,36 @@ macro_rules! miette {
         let error = $err;
         (&error).miette_kind().new(error)
     });
+    ($fmt:expr $(, $key:ident = $value:expr)* $(,)?) => {
+        $crate::Report::from($crate::miette_diagnostic!($fmt, $($key = $value,)*))
+    };
     ($fmt:expr, $($arg:tt)*) => {
         $crate::private::new_adhoc(format!($fmt, $($arg)*))
     };
 }
+
+/// Construct a [`MietteDiagnostic`] in more user-friendly way.
+///
+/// # Examples
+/// ```
+/// use miette::{miette_diagnostic, LabeledSpan, Severity};
+///
+/// let source = "(2 + 2".to_string();
+/// let diag = miette_diagnostic!(
+///     "expected closing ')'",
+///     // Those fields are optional
+///     severity = Severity::Error,
+///     code = "expected::rparen",
+///     help = "always close your parens",
+///     labels = vec![LabeledSpan::at_offset(6, "here")],
+///     url = "https://example.com"
+/// );
+/// ```
+#[macro_export]
+macro_rules! miette_diagnostic {
+    ($fmt:expr $(, $key:ident = $value:expr)* $(,)?) => {{
+        let mut diag = $crate::MietteDiagnostic::new(format!("{}", $fmt));
+        $(diag.$key = Some($value.into());)*
+        diag
+    }};
+}

src/lib.rs

@@ -46,6 +46,7 @@
 //!   - [... multiple related errors](#-multiple-related-errors)
 //!   - [... delayed source code](#-delayed-source-code)
 //!   - [... handler options](#-handler-options)
+//!   - [... dynamic diagnostics](#-dynamic-diagnostics)
 //! - [Acknowledgements](#acknowledgements)
 //! - [License](#license)
 //!
@@ -249,7 +250,7 @@
 //! 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> {
@@ -590,6 +591,28 @@
 //! See the docs for [`MietteHandlerOpts`] for more details on what you can
 //! customize!
 //!
+//! ### ... dynamic diagnostics
+//!
+//! If you...
+//! - ...don't know all the possible errors upfront
+//! - ...need to serialize/deserialize errors
+//! then you may want to use [`miette!`], [`miette_diagnostic!`] macros or
+//! [`MietteDiagnostic`] directly to create diagnostic on the fly.
+//!
+//! ```rs
+//! # use miette::{miette, LabeledSpan, Report};
+//!
+//! let source = "2 + 2 * 2 = 8".to_string();
+//! let report = miette!(
+//!   "Wrong answer",
+//!   labels = vec[
+//!       LabeledSpan::at(12..13, "this should be 6"),
+//!   ],
+//!   help = "'*' has greater precedence than '+'"
+//! ).with_source_code(source);
+//! println!("{:?}", report)
+//! ```
+//!
 //! ## Acknowledgements
 //!
 //! `miette` was not developed in a void. It owes enormous credit to various
@@ -624,6 +647,7 @@ pub use eyreish::*;
 #[cfg(feature = "fancy-no-backtrace")]
 pub use handler::*;
 pub use handlers::*;
+pub use miette_diagnostic::*;
 pub use named_source::*;
 #[cfg(feature = "fancy")]
 pub use panic::*;
@@ -638,6 +662,7 @@ mod handler;
 mod handlers;
 #[doc(hidden)]
 pub mod macro_helpers;
+mod miette_diagnostic;
 mod named_source;
 #[cfg(feature = "fancy")]
 mod panic;