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

API Docs

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
• Drop in replacement for [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 aquire data")?;

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

  // wrap with help information createdir().wraphelp(|| "project directory already exists", "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 it can be easily implemented for any type.

• 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_help( || CliError::Config, "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); } ```

  

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.