#![deny(missing_docs)]
#![doc(html_root_url = "
https://docs.rs/error-chain/0.12.4")]
//! A library for consistent and reliable error handling
//!
//! error-chain makes it easy to take full advantage of Rust's
//! powerful error handling features without the overhead of
//! maintaining boilerplate error types and conversions. It implements
//! an opinionated strategy for defining your own error types, as well
//! as conversions from others' error types.
//!
//! ## Quick start
//!
//! If you just want to set up your new project with error-chain,
//! follow the [quickstart.rs] template, and read this [intro]
//! to error-chain.
//!
//! [quickstart.rs]:
https://github.com/rust-lang-nursery/error-chain/blob/master/examples/quickstart.rs
//! [intro]:
http://brson.github.io/2016/11/30/starting-with-error-chain
//!
//! ## Why error chain?
//!
//! * error-chain is easy to configure. Handle errors robustly with minimal
//! effort.
//! * Basic error handling requires no maintenance of custom error types
//! nor the [`From`] conversions that make `?` work.
//! * error-chain scales from simple error handling strategies to more
//! rigorous. Return formatted strings for simple errors, only
//! introducing error variants and their strong typing as needed for
//! advanced error recovery.
//! * error-chain makes it trivial to correctly manage the [cause] of
//! the errors generated by your own code. This is the "chaining"
//! in "error-chain".
//!
//! [cause]:
https://doc.rust-lang.org/std/error/trait.Error.html#method.cause
//!
//! ## Principles of error-chain
//!
//! error-chain is based on the following principles:
//!
//! * No error should ever be discarded. This library primarily
//! makes it easy to "chain" errors with the [`chain_err`] method.
//! * Introducing new errors is trivial. Simple errors can be introduced
//! at the error site with just a string.
//! * Handling errors is possible with pattern matching.
//! * Conversions between error types are done in an automatic and
//! consistent way - [`From`] conversion behavior is never specified
//! explicitly.
//! * Errors implement [`Send`].
//! * Errors can carry backtraces.
//!
//! Similar to other libraries like [error-type] and [quick-error],
//! this library introduces the error chaining mechanism originally
//! employed by Cargo. The [`error_chain!`] macro declares the types
//! and implementation boilerplate necessary for fulfilling a
//! particular error-handling strategy. Most importantly it defines a
//! custom error type (called [`Error`] by convention) and the [`From`]
//! conversions that let the `?` operator work.
//!
//! This library differs in a few ways from previous error libs:
//!
//! * Instead of defining the custom [`Error`] type as an enum, it is a
//! struct containing an [`ErrorKind`][] (which defines the
//! [`description`] and [`display_chain`] methods for the error), an opaque,
//! optional, boxed [`std::error::Error`]` + `[`Send`]` + 'static` object
//! (which defines the [`cause`], and establishes the links in the
//! error chain), and a [`Backtrace`].
//! * The macro also defines a [`ResultExt`] trait that defines a
//! [`chain_err`] method. This method on all [`std::error::Error`]` + `[`Send`]` + 'static`
//! types extends the error chain by boxing the current
//! error into an opaque object and putting it inside a new concrete
//! error.
//! * It provides automatic [`From`] conversions between other error types
//! defined by the [`error_chain!`] that preserve type information,
//! and facilitate seamless error composition and matching of composed
//! errors.
//! * It provides automatic [`From`] conversions between any other error
//! type that hides the type of the other error in the [`cause`] box.
//! * If `RUST_BACKTRACE` is enabled, it collects a single backtrace at
//! the earliest opportunity and propagates it down the stack through
//! [`From`] and [`ResultExt`] conversions.
//!
//! To accomplish its goals it makes some tradeoffs:
//!
//! * The split between the [`Error`] and [`ErrorKind`] types can make it
//! slightly more cumbersome to instantiate new (unchained) errors,
//! requiring an [`Into`] or [`From`] conversion; as well as slightly
//! more cumbersome to match on errors with another layer of types
//! to match.
//! * Because the error type contains [`std::error::Error`]` + `[`Send`]` + 'static` objects
,
//! it can't implement [`PartialEq`] for easy comparisons.
//!
//! ## Declaring error types
//!
//! Generally, you define one family of error types per crate, though
//! it's also perfectly fine to define error types on a finer-grained
//! basis, such as per module.
//!
//! Assuming you are using crate-level error types, typically you will
//! define an `errors` module and inside it call [`error_chain!`]:
//!
//! ```
//! # #[macro_use] extern crate error_chain;
//! mod other_error {
//! error_chain! {}
//! }
//!
//! error_chain! {
//! // The type defined for this error. These are the conventional
//! // and recommended names, but they can be arbitrarily chosen.
//! //
//! // It is also possible to leave this section out entirely, or
//! // leave it empty, and these names will be used automatically.
//! types {
//! Error, ErrorKind, ResultExt, Result;
//! }
//!
//! // Without the `Result` wrapper:
//! //
//! // types {
//! // Error, ErrorKind, ResultExt;
//! // }
//!
//! // Automatic conversions between this error chain and other
//! // error chains. In this case, it will e.g. generate an
//! // `ErrorKind` variant called `Another` which in turn contains
//! // the `other_error::ErrorKind`, with conversions from
//! // `other_error::Error`.
//! //
//! // Optionally, some attributes can be added to a variant.
//! //
//! // This section can be empty.
//! links {
//! Another(other_error::Error, other_error::ErrorKind) #[cfg(unix)];
//! }
//!
//! // Automatic conversions between this error chain and other
//! // error types not defined by the `error_chain!`. These will be
//! // wrapped in a new error with, in the first case, the
//! // `ErrorKind::Fmt` variant. The description and cause will
//! // forward to the description and cause of the original error.
//! //
//! // Optionally, some attributes can be added to a variant.
//! //
//! // This section can be empty.
//! foreign_links {
//! Fmt(::std::fmt::Error);
//! Io(::std::io::Error) #[cfg(unix)];
//! }
//!
//! // Define additional `ErrorKind` variants. Define custom responses with the
//! // `description` and `display` calls.
//! errors {
//! InvalidToolchainName(t: String) {
//! description("invalid toolchain name")
//! display("invalid toolchain name: '{}'", t)
//! }
//!
//! // You can also add commas after description/display.
//! // This may work better with some editor auto-indentation modes:
//! UnknownToolchainVersion(v: String) {
//! description("unknown toolchain version"), // note the ,
//! display("unknown toolchain version: '{}'", v), // trailing comma is allowed
//! }
//! }
//!
//! // If this annotation is left off, a variant `Msg(s: String)` will be added, and `From`
//! // impls will be provided for `String` and `&str`
//! skip_msg_variant
//! }
//!
//! # fn main() {}
//! ```
//!
//! Each section, `types`, `links`, `foreign_links`, and `errors` may
//! be omitted if it is empty.
//!
//! This populates the module with a number of definitions,
//! the most important of which are the [`Error`] type
//! and the [`ErrorKind`] type. An example of generated code can be found in the
//! [example_generated](example_generated/index.html) module.
//!
//! ## Returning new errors
//!
//! Introducing new error chains, with a string message:
//!
//! ```
//! # #[macro_use] extern crate error_chain;
//! # fn main() {}
//! # error_chain! {}
//! fn foo() -> Result<()> {
//! Err("foo error!".into())
//! }
//! ```
//!
//! Introducing new error chains, with an [`ErrorKind`]:
//!
//! ```
//! # #[macro_use] extern crate error_chain;
//! # fn main() {}
//! error_chain! {
//! errors { FooError }
//! }
//!
//! fn foo() -> Result<()> {
//! Err(ErrorKind::FooError.into())
//! }
//! ```
//!
//! Note that the return type is the typedef [`Result`], which is
//! defined by the macro as `pub type Result<T> =
//! ::std::result::Result<T, Error>`. Note that in both cases
//! [`.into()`] is called to convert a type into the [`Error`] type; both
//! strings and [`ErrorKind`] have [`From`] conversions to turn them into
//! [`Error`].
//!
//! When the error is emitted behind the `?` operator, the explicit conversion
//! isn't needed; `Err(ErrorKind)` will automatically be converted to `Err(Error)`.
//! So the below is equivalent to the previous:
//!
//! ```
//! # #[macro_use] extern crate error_chain;
//! # fn main() {}
//! # error_chain! { errors { FooError } }
//! fn foo() -> Result<()> {
//! Ok(Err(ErrorKind::FooError)?)
//! }
//!
//! fn bar() -> Result<()> {
//! Ok(Err("bogus!")?)
//! }
//! ```
//!
//! ## The `bail!` macro
//!
//! The above method of introducing new errors works but is a little
//! verbose. Instead, we can use the [`bail!`] macro, which performs an early return
//! with conversions done automatically.
//!
//! With [`bail!`] the previous examples look like:
//!
//! ```
//! # #[macro_use] extern crate error_chain;
//! # fn main() {}
//! # error_chain! { errors { FooError } }
//! fn foo() -> Result<()> {
//! if true {
//! bail!(ErrorKind::FooError);
//! } else {
//! Ok(())
//! }
//! }
//!
//! fn bar() -> Result<()> {
//! if true {
//! bail!("bogus!");
//! } else {
//! Ok(())
//! }
//! }
//! ```
//!
//! ## Chaining errors
//! error-chain supports extending an error chain by appending new errors.
//! This can be done on a Result or on an existing Error.
//!
//! To extend the error chain:
//!
//! ```
//! # #[macro_use] extern crate error_chain;
//! # fn main() {}
//! # error_chain! {}
//! # fn do_something() -> Result<()> { unimplemented!() }
//! # fn test() -> Result<()> {
//! let res: Result<()> = do_something().chain_err(|| "something went wrong");
//! # Ok(())
//! # }
//! ```
//!
//! [`chain_err`] can be called on any [`Result`] type where the contained
//! error type implements [`std::error::Error`]` + `[`Send`]` + 'static`, as long as
//! the [`Result`] type's corresponding [`ResultExt`] trait is in scope. If
//! the [`Result`] is an `Err` then [`chain_err`] evaluates the closure,
//! which returns *some type that can be converted to [`ErrorKind`]*,
//! boxes the original error to store as the cause, then returns a new
//! error containing the original error.
//!
//! Calling [`chain_err`][Error_chain_err] on an existing [`Error`] instance has
//! the same signature and produces the same outcome as being called on a
//! [`Result`] matching the properties described above. This is most useful when
//! partially handling errors using the [`map_err`] function.
//!
//! To chain an error directly, use [`with_chain`]:
//!
//! ```
//! # #[macro_use] extern crate error_chain;
//! # fn main() {}
//! # error_chain! {}
//! # fn do_something() -> Result<()> { unimplemented!() }
//! # fn test() -> Result<()> {
//! let res: Result<()> =
//! do_something().map_err(|e| Error::with_chain(e, "something went wrong"));
//! # Ok(())
//! # }
//! ```
//!
//! ## Linking errors
//!
//! To convert an error from another error chain to this error chain:
//!
//! ```
//! # #[macro_use] extern crate error_chain;
//! # fn main() {}
//! # mod other { error_chain! {} }
//! error_chain! {
//! links {
//! OtherError(other::Error, other::ErrorKind);
//! }
//! }
//!
//! fn do_other_thing() -> other::Result<()> { unimplemented!() }
//!
//! # fn test() -> Result<()> {
//! let res: Result<()> = do_other_thing().map_err(|e| e.into());
//! # Ok(())
//! # }
//! ```
//!
//! The [`Error`] and [`ErrorKind`] types implements [`From`] for the corresponding
//! types of all linked error chains. Linked errors do not introduce a new
//! cause to the error chain.
//!
//! ## Matching errors
//!
//! error-chain error variants are matched with simple patterns.
//! [`Error`] is a tuple struct and its first field is the [`ErrorKind`],
//! making dispatching on error kinds relatively compact:
//!
//! ```
//! # #[macro_use] extern crate error_chain;
//! # fn main() {
//! error_chain! {
//! errors {
//! InvalidToolchainName(t: String) {
//! description("invalid toolchain name")
//! display("invalid toolchain name: '{}'", t)
//! }
//! }
//! }
//!
//! match Error::from("error!") {
//! Error(ErrorKind::InvalidToolchainName(_), _) => { }
//! Error(ErrorKind::Msg(_), _) => { }
//! _ => { }
//! }
//! # }
//! ```
//!
//! Chained errors are also matched with (relatively) compact syntax
//!
//! ```
//! # #[macro_use] extern crate error_chain;
//! mod utils {
//! error_chain! {
//! errors {
//! BadStuff {
//! description("bad stuff")
//! }
//! }
//! }
//! }
//!
//! mod app {
//! error_chain! {
//! links {
//! Utils(::utils::Error, ::utils::ErrorKind);
//! }
//! }
//! }
//!
//!
//! # fn main() {
//! match app::Error::from("error!") {
//! app::Error(app::ErrorKind::Utils(utils::ErrorKind::BadStuff), _) => { }
//! _ => { }
//! }
//! # }
//! ```
//!
//! ## Inspecting errors
//!
//! An error-chain error contains information about the error itself, a backtrace, and the chain
//! of causing errors. For reporting purposes, this information can be accessed as follows.
//!
//! ```
//! # #[macro_use] extern crate error_chain;
//! use error_chain::ChainedError; // for e.display_chain()
//!
//! error_chain! {
//! errors {
//! InvalidToolchainName(t: String) {
//! description("invalid toolchain name")
//! display("invalid toolchain name: '{}'", t)
//! }
//! }
//! }
//!
//! # fn main() {
//! // Generate an example error to inspect:
//! let e = "xyzzy".parse::<i32>()
//! .chain_err(|| ErrorKind::InvalidToolchainName("xyzzy".to_string()))
//! .unwrap_err();
//!
//! // Get the brief description of the error:
//! assert_eq!(e.description(), "invalid toolchain name");
//!
//! // Get the display version of the error:
//! assert_eq!(e.to_string(), "invalid toolchain name: 'xyzzy'");
//!
//! // Get the full cause and backtrace:
//! println!("{}", e.display_chain().to_string());
//! // Error: invalid toolchain name: 'xyzzy'
//! // Caused by: invalid digit found in string
//! // stack backtrace:
//! // 0: 0x7fa9f684fc94 - backtrace::backtrace::libunwind::trace
//! // at src/backtrace/libunwind.rs:53
//! // - backtrace::backtrace::trace<closure>
//! // at src/backtrace/mod.rs:42
//! // 1: 0x7fa9f6850b0e - backtrace::capture::{{impl}}::new
//! // at out/capture.rs:79
//! // [..]
//! # }
//! ```
//!
//! The [`Error`] and [`ErrorKind`] types also allow programmatic access to these elements.
//!
//! ## Foreign links
//!
//! Errors that do not conform to the same conventions as this library
//! can still be included in the error chain. They are considered "foreign
//! errors", and are declared using the `foreign_links` block of the
//! [`error_chain!`] macro. [`Error`]s are automatically created from
//! foreign errors by the `?` operator.
//!
//! Foreign links and regular links have one crucial difference:
//! [`From`] conversions for regular links *do not introduce a new error
//! into the error chain*, while conversions for foreign links *always
//! introduce a new error into the error chain*. So for the example
//! above all errors deriving from the [`std::fmt::Error`] type will be
//! presented to the user as a new [`ErrorKind`] variant, and the
//! cause will be the original [`std::fmt::Error`] error. In contrast, when
//! `other_error::Error` is converted to `Error` the two `ErrorKind`s
//! are converted between each other to create a new `Error` but the
//! old error is discarded; there is no "cause" created from the
//! original error.
//!
//! ## Backtraces
//!
//! If the `RUST_BACKTRACE` environment variable is set to anything
//! but ``0``, the earliest non-foreign error to be generated creates
//! a single backtrace, which is passed through all [`From`] conversions
//! and [`chain_err`] invocations of compatible types. To read the
//! backtrace just call the [`backtrace`] method.
//!
//! Backtrace generation can be disabled by turning off the `backtrace` feature.
//!
//! The Backtrace contains a Vec of [`BacktraceFrame`]s that can be operated
//! on directly. For example, to only see the files and line numbers of code
//! within your own project.
//!
//! ```
//! # #[macro_use]
//! # extern crate error_chain;
//! # mod errors {
//! # error_chain! {
//! # foreign_links {
//! # Io(::std::io::Error);
//! # }
//! # }
//! # }
//! # use errors::*;
//! # #[cfg(feature="backtrace")]
//! # fn main() {
//! if let Err(ref e) = open_file() {
//! if let Some(backtrace) = e.backtrace() {
//! let frames = backtrace.frames();
//! for frame in frames.iter() {
//! for symbol in frame.symbols().iter() {
//! if let (Some(file), Some(lineno)) = (symbol.filename(), symbol.lineno()) {
//! if file.display().to_string()[0..3] == "src".to_string(){
//! println!("{}:{}", file.display().to_string(), lineno);
//! }
//! }
//! }
//! }
//! }
//! };
//! # }
//! # #[cfg(not(feature="backtrace"))]
//! # fn main() { }
//!
//! fn open_file() -> Result<()> {
//! std::fs::File::open("does_not_exist")?;
//! Ok(())
//! }
//! ```
//!
//! ## Iteration
//!
//! The [`iter`] method returns an iterator over the chain of error boxes.
//!
//! [error-type]: https://github.com/DanielKeep/rust-error-type
//! [quick-error]: https://github.com/tailhook/quick-error
//! [`display_chain`]: trait.ChainedError.html#method.display_chain
//! [`error_chain!`]: macro.error_chain.html
//! [`bail!`]: macro.bail.html
//! [`Backtrace`]: struct.Backtrace.html
//! [`Error`]: example_generated/struct.Error.html
//! [`with_chain`]: example_generated/struct.Error.html#method.with_chain
//! [Error_chain_err]: example_generated/struct.Error.html#method.chain_err
//! [`cause`]: example_generated/struct.Error.html#method.cause
//! [`backtrace`]: example_generated/struct.Error.html#method.backtrace
//! [`iter`]: example_generated/struct.Error.html#method.iter
//! [`ErrorKind`]: example_generated/enum.ErrorKind.html
//! [`description`]: example_generated/enum.ErrorKind.html#method.description
//! [`Result`]: example_generated/type.Result.html
//! [`ResultExt`]: example_generated/trait.ResultExt.html
//! [`chain_err`]: example_generated/trait.ResultExt.html#tymethod.chain_err
//! [`std::error::Error`]: https://doc.rust-lang.org/std/error/trait.Error.html
//! [`Send`]: https://doc.rust-lang.org/std/marker/trait.Send.html
//! [`Into`]: https://doc.rust-lang.org/std/convert/trait.Into.html
//! [`From`]: https://doc.rust-lang.org/std/convert/trait.From.html
//! [`PartialEq`]: https://doc.rust-lang.org/std/cmp/trait.PartialEq.html
//! [`std::fmt::Error`]: https://doc.rust-lang.org/std/fmt/struct.Error.html
//! [`.into()`]: https://doc.rust-lang.org/std/convert/trait.Into.html#tymethod.into
//! [`map_err`]: https://doc.rust-lang.org/std/result/enum.Result.html#method.map_err
//! [`BacktraceFrame`]: https://docs.rs/backtrace/0.3.2/backtrace/struct.BacktraceFrame.html
use std::error;
use std::fmt;
use std::iter::Iterator;
#[macro_use]
mod impl_error_chain_kind;
#[macro_use]
mod error_chain;
#[macro_use]
mod quick_main;
pub use quick_main::ExitCode;
mod backtrace;
#[cfg(feature = "example_generated")]
pub mod example_generated;
pub use backtrace::Backtrace;
#[doc(hidden)]
pub use backtrace::InternalBacktrace;
#[derive(Debug)]
#[allow(unknown_lints, bare_trait_objects)]
/// Iterator over the error chain using the `Error::cause()` method.
pub struct Iter<'a>(Option<&'a error::Error>);
impl<'a> Iter<'a> {
/// Returns a new iterator over the error chain using `Error::cause()`.
#[allow(unknown_lints, bare_trait_objects)]
pub fn new(err: Option<&'a error::Error>) -> Iter<'a> {
Iter(err)
}
}
#[allow(unknown_lints, bare_trait_objects)]
impl<'a> Iterator for Iter<'a> {
type Item = &'a error::Error;
fn next<'b>(&'b mut self) -> Option<&'a error::Error> {
match self.0.take() {
Some(e) => {
self.0 = match () {
#[cfg(not(has_error_source))]
() => e.cause(),
#[cfg(has_error_source)]
() => e.source(),
};
Some(e)
}
None => None,
}
}
}
/// This trait is implemented on all the errors generated by the `error_chain`
/// macro.
pub trait ChainedError: error::Error + Send + 'static {
/// Associated kind type.
type ErrorKind;
/// Constructs an error from a kind, and generates a backtrace.
fn from_kind(kind: Self::ErrorKind) -> Self
where
Self: Sized;
/// Constructs a chained error from another error and a kind, and generates a backtrace.
fn with_chain<E, K>(error: E, kind: K) -> Self
where
Self: Sized,
E: ::std::error::Error + Send + 'static,
K: Into<Self::ErrorKind>;
/// Returns the kind of the error.
fn kind(&self) -> &Self::ErrorKind;
/// Iterates over the error chain.
fn iter(&self) -> Iter;
/// Returns the backtrace associated with this error.
fn backtrace(&self) -> Option<&Backtrace>;
/// Returns an object which implements `Display` for printing the full
/// context of this error.
///
/// The full cause chain and backtrace, if present, will be printed.
fn display_chain<'a>(&'a self) -> DisplayChain<'a, Self> {
DisplayChain(self)
}
/// Extends the error chain with a new entry.
fn chain_err<F, EK>(self, error: F) -> Self
where
F: FnOnce() -> EK,
EK: Into<Self::ErrorKind>;
/// Creates an error from its parts.
#[doc(hidden)]
fn new(kind: Self::ErrorKind, state: State) -> Self
where
Self: Sized;
/// Returns the first known backtrace, either from its State or from one
/// of the errors from `foreign_links`.
#[doc(hidden)]
#[allow(unknown_lints, bare_trait_objects)]
fn extract_backtrace(e: &(error::Error + Send + 'static)) -> Option<InternalBacktrace>
where
Self: Sized;
}
/// A struct which formats an error for output.
#[derive(Debug)]
pub struct DisplayChain<'a, T: 'a + ?Sized>(&'a T);
impl<'a, T> fmt::Display for DisplayChain<'a, T>
where
T: ChainedError,
{
fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
writeln!(fmt, "Error: {}", self.0)?;
for e in self.0.iter().skip(1) {
writeln!(fmt, "Caused by: {}", e)?;
}
if let Some(backtrace) = ChainedError::backtrace(self.0) {
writeln!(fmt, "{:?}", backtrace)?;
}
Ok(())
}
}
/// Common state between errors.
#[derive(Debug)]
#[doc(hidden)]
#[allow(unknown_lints, bare_trait_objects)]
pub struct State {
/// Next error in the error chain.
pub next_error: Option<Box<error::Error + Send>>,
/// Backtrace for the current error.
pub backtrace: InternalBacktrace,
}
impl Default for State {
fn default() -> State {
State {
next_error: None,
backtrace: InternalBacktrace::new(),
}
}
}
impl State {
/// Creates a new State type
#[allow(unknown_lints, bare_trait_objects)]
pub fn new<CE: ChainedError>(e: Box<error::Error + Send>) -> State {
let backtrace = CE::extract_backtrace(&*e).unwrap_or_else(InternalBacktrace::new);
State {
next_error: Some(e),
backtrace: backtrace,
}
}
/// Returns the inner backtrace if present.
pub fn backtrace(&self) -> Option<&Backtrace> {
self.backtrace.as_backtrace()
}
}
/// Exits a function early with an error
///
/// The `bail!` macro provides an easy way to exit a function.
/// `bail!(expr)` is equivalent to writing.
///
/// ```
/// # #[macro_use] extern crate error_chain;
/// # error_chain! { }
/// # fn main() { }
/// # fn foo() -> Result<()> {
/// # let expr = "";
/// return Err(expr.into());
/// # }
/// ```
///
/// And as shorthand it takes a formatting string a la `println!`:
///
/// ```
/// # #[macro_use] extern crate error_chain;
/// # error_chain! { }
/// # fn main() { }
/// # fn foo() -> Result<()> {
/// # let n = 0;
/// bail!("bad number: {}", n);
/// # }
/// ```
///
/// # Examples
///
/// Bailing on a custom error:
///
/// ```
/// # #[macro_use] extern crate error_chain;
/// # fn main() {}
/// error_chain! {
/// errors { FooError }
/// }
///
/// fn foo() -> Result<()> {
/// if bad_condition() {
/// bail!(ErrorKind::FooError);
/// }
///
/// Ok(())
/// }
///
/// # fn bad_condition() -> bool { true }
/// ```
///
/// Bailing on a formatted string:
///
/// ```
/// # #[macro_use] extern crate error_chain;
/// # fn main() {}
/// error_chain! { }
///
/// fn foo() -> Result<()> {
/// if let Some(bad_num) = bad_condition() {
/// bail!("so bad: {}", bad_num);
/// }
///
/// Ok(())
/// }
///
/// # fn bad_condition() -> Option<i8> { None }
/// ```
#[macro_export]
macro_rules! bail {
($e:expr) => {
return Err($e.into());
};
($fmt:expr, $($arg:tt)+) => {
return Err(format!($fmt, $($arg)+).into());
};
}
/// Exits a function early with an error if the condition is not satisfied
///
/// The `ensure!` macro is a convenience helper that provides a way to exit
/// a function with an error if the given condition fails.
///
/// As an example, `ensure!(condition, "error code: {}", errcode)` is equivalent to
///
/// ```
/// # #[macro_use] extern crate error_chain;
/// # error_chain! { }
/// # fn main() { }
/// # fn foo() -> Result<()> {
/// # let errcode = 0u8;
/// # let condition = true;
/// if !condition {
/// bail!("error code: {}", errcode);
/// }
/// # Ok(())
/// # }
/// ```
///
/// See documentation for `bail!` macro for further details.
#[macro_export(local_inner_macros)]
macro_rules! ensure {
($cond:expr, $e:expr) => {
if !($cond) {
bail!($e);
}
};
($cond:expr, $fmt:expr, $($arg:tt)+) => {
if !($cond) {
bail!($fmt, $($arg)+);
}
};
}
#[doc(hidden)]
pub mod mock {
error_chain! {}
}
