1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198
// Copyright 2020 the Tectonic Project.
// Licensed under the MIT License.
#![deny(missing_docs)]
//! Generic error handling for Tectonic.
//!
//! This crate provides a generic boxed error type, plus supporting utilities.
//! In particular:
//!
//! - The basic `Error` type is an `anyhow` 1.x boxed Error
//! - The `atry!` macro allows simple structured annotations to be added to `?`
//! operations
//! - The `a_ok_or!` macro allows for annotations to `Option::ok_or_else` calls.
use std::{error, fmt, result::Result as StdResult};
/// The generic error type, for complex operations that can fail for a wide
/// range of reasons. This type is a reexport of the `anyhow` 1.x series Error
/// type.
///
/// There’s an appeal to not explicitly committing ourselves to using this
/// particular error implementation, but the `anyhow` error type has a
/// sufficient number of special methods and traits that it would be pretty
/// tedious to re-implement them all while pretending that we're using some
/// different type.
pub use anyhow::Error;
/// A preloaded result type where the error type is our generic error type.
pub use anyhow::Result;
/// The specific version of `anyhow` used by this crate.
pub use anyhow;
/// A simple annotated message that can be attached to errors using the
/// `anyhow::Context` methods, or be used as an error type itself. The
/// recommended way to use this for error context is using `atry!` or related
/// macros.
///
/// The `std::fmt::Display` of this type yields its primary “message”. Consumers
/// that are aware of this type can obtain additional context through its
/// `notes()` method.
#[derive(Debug, Default)]
pub struct AnnotatedMessage {
/// The main message.
message: String,
/// Additional annotations that can be displayed after the primary message.
notes: Vec<String>,
}
impl AnnotatedMessage {
/// Set the primary message associated with this annotated report.
pub fn set_message<T: fmt::Display>(&mut self, m: T) {
self.message = format!("{m}");
}
/// Add an additional note to be associated with this annotated report.
pub fn add_note<T: fmt::Display>(&mut self, n: T) {
self.notes.push(format!("{n}"));
}
/// Obtain the set of notes associated with this report.
pub fn notes(&self) -> &[String] {
&self.notes[..]
}
}
impl fmt::Display for AnnotatedMessage {
fn fmt(&self, f: &mut fmt::Formatter) -> StdResult<(), fmt::Error> {
write!(f, "{}", self.message)
}
}
impl error::Error for AnnotatedMessage {}
/// "Annotated try” — like `try!`, but with the ability to add extended context
/// to the error message. This tries to provide a bit more syntactic sugar than
/// anyhow's `with_context()`, and it supports our AnnotatedMessage context type.
///
/// # Example
///
/// ```
/// # use tectonic_errors::{atry, Result};
/// # fn my_fallible_operation(a: bool, b: bool) -> Result<()> { Ok(()) }
/// # fn my_caller() -> Result<()> {
/// # let arg = true;
/// # let option = true;
/// let ok_val = atry!(
/// my_fallible_operation(arg, option);
/// ["the operation on `{}` failed", arg]
/// (note "option was `{}`; maybe you should choose a better value next time", option)
/// );
/// # Ok(())
/// # }
/// ```
///
/// This is equivalent to `let ok_val = my_fallible_operation(arg)?;`, but if the
/// operation fails, the returned error will have a message formatted as per the
/// format expression in square brackets, with attached "note" text formatted as
/// per the parenthesized `note` expression. There may be zero, one, or many notes
/// attached.
#[macro_export]
macro_rules! atry {
(@aa $ar:ident [ $($inner:tt)+ ] ) => {
$ar.set_message(format!($($inner)+));
};
(@aa $ar:ident ( note $($inner:tt)+ ) ) => {
$ar.add_note(format!($($inner)+));
};
($op:expr ; $( $annotation:tt )+) => {{
use $crate::anyhow::Context;
$op.with_context(|| {
let mut ar = $crate::AnnotatedMessage::default();
$(
atry!(@aa ar $annotation);
)+
ar
})?
}};
}
/// "annotated ok_or” — like `Option::ok_or_else()?`, but with the ability to
/// add extended context to the error. This yields an `AnnotatedMessage` as its
/// error type.
#[macro_export]
macro_rules! a_ok_or {
($option:expr ; $( $annotation:tt )+) => {{
use $crate::atry;
$option.ok_or_else(|| {
let mut ar = $crate::AnnotatedMessage::default();
$(
atry!(@aa ar $annotation);
)+
ar
})?
}};
}
/// A “prelude” module providing a collection of useful names, without
/// causing compiler complaints about the ones you don’t use.
///
/// Provided names are:
///
/// - The core `anyhow::Error` type
/// - The core `anyhow::Result` type, which is `Result<T, anyhow::Error>`
/// - The `anyhow!` macro to create an Error value from a string-format expression
/// - The `bail!` macro: `bail!(...)` = `return Err(anyhow!(...))`
/// - The `ensure!` macro: `ensure!(cond, err)` = `if !cond { bail!(err); }`
/// - The `atry!` macro for annotated question-mark behavior
/// - The `a_ok_or!` macro for annotated, fallibale Option unwrapping
/// - Rust's `std::result::Result` type aliased as StdResult for convenience
pub mod prelude {
pub use crate::{a_ok_or, atry};
pub use anyhow::{anyhow, bail, ensure, Error, Result};
pub use std::result::Result as StdResult;
}
#[cfg(test)]
mod test {
use super::*;
fn atry_eval() -> Result<()> {
let fine: Result<usize> = Ok(0);
let display = "a string";
atry!(
fine;
["message {}", display]
(note "but what about {}", display)
);
Ok(())
}
#[test]
fn atry_compile() {
atry_eval().unwrap();
}
fn a_ok_or_eval() -> Result<()> {
let fine: Option<usize> = Some(0);
let display = "a string";
a_ok_or!(
fine;
["message {}", display]
(note "but what about {}", display)
);
Ok(())
}
#[test]
fn a_ok_or_compile() {
a_ok_or_eval().unwrap();
}
}