narrate

This library provides CLI application error and status reporting utilities. The coloured output formatting aims to be similar to [Cargo]. Error type is a wrapper around [anyhow], with optional help messages.

Features

• User facing status messages and error reporting
• Wrap any error with additional context
• Optional help messages for errors
• Set of standard CLI errors with exit codes conforming to [sysexits.h]
• Convenience Result type
• Replace/integrate with [anyhow]

How to use

• Use narrate::Result<T> as a return type of any fallible function.

  Within the function, use ? to propagate any error that implements the std::error::Error trait. Same as anyhow::Result<T>.

  ```rust use narrate::Result;

  fn getuser() -> Result { let json = std::fs::readtostring("user.json")?; let user: User = serdejson::from_str(&json)?; Ok(user) } ```

• Wrap an error with more context by importing the narrate::ErrorWrap trait. Similar to anyhow::Context, this can give your users more information as to why an error happened.

  ```rust use narrate::{CliError, ErrorWrap, Result};

  fn run() -> Result<()> { ... // wrap with contextual information data.acquire().wrap("unable to acquire data")?;

  // wrap with another error config.load().wrap(CliError::Config)?;

  // wrap with lazily evaulated string or error config.load().wrap_with(|| format!("cannot load {}", path))?;

  // wrap with help information createdir() .wrap("project directory already exists") .addhelp("Try using cargo init")?; ... } ```

  ```console error: project directory already exists cause: Is a directory (os error 20)

  Try using cargo init ```

• Use the narrate::ExitCode trait to get the [sysexits.h] conforming exit code from a narrate::Error. By default this is just 70 (software error), but using an apropriate CliError will change this.

• narrate::CliError collection of typical command line errors. Use them to add context to deeper application errors. Use their exit_code to conform to [sysexits.h].

  ```rust use narrate::{CliError, ErrorWrap, ExitCode, Result};

  fn main() { let res = run();

  if let Err(ref err) = res { std::process::exit(err.exit_code()); } }

  fn run() -> Result<()> { will_error().wrap(CliError::OsErr)? Ok(()) } ```

• Report errors to the command line with either report::err or report::err_full for the complete error chain.

  ```rust use narrate::{CliError, Error, report};

  fn main() { let res = run();

  if let Err(ref err) = res { report::errfull(&err); std::process::exit(err.exitcode()); } }

  fn run() -> Result<()> { ... let config: Config = serdejson::fromstr(&json) .wrap("bad config file /app/config.toml") .wrap(CliError::Config) .add_help("see https://docs.example.rs/config for more help")?; ... } ```

  

• Report application status to the command line with report::status. Modeled on the output from [Cargo].

  ```rust use colored::Color; use narrate::report;

  fn main() { report::status("Created", "new project spacetime", Color::Green); } ```

  

Please view the API Docs and examples for more information.

FAQ

Should I use narrate instead of [anyhow] or [eyre]?

Anyhow is a great tool for handling errors in your CLI app, but it doesn't come with its own reporting, common set of errors, or the ability to add separate help messages.

Eyre and its companion crates offer fine-grained error reporting and is far more customizable than narrate - which is opinionated in copying Cargo's style. If you don't need that much control, narrate provides a simpler alternative. Plus the added benefit of reporting statuses, not just errors.

Can I just pretty print my [anyhow] errors?

If you just use the report Cargo feature flag, you can access the report module and thus the anyhow_err and anyhow_err_full functions.

```toml

Cargo.toml

[dependencies] narrate = { version = "0.4.0", default-features = false, features = ["report"] } ```

```rust // main.rs use narrate::report;

fn main() { if let Err(err) => run() { report::anyhowerrfull(err);
} }

fn run() -> anyhow::Result<()> { ... } ```

Contributing

Thank you very much for considering to contribute to this project!

We welcome any form of contribution:

• New issues (feature requests, bug reports, questions, ideas, ...)
• Pull requests (documentation improvements, code improvements, new features, ...)

Note: Before you take the time to open a pull request, please open an issue first.

See CONTRIBUTING.md for details.

License

narrate is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE and LICENSE-MIT for details.