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

Features

• 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

Planned features

• Error chain output
• Status messages

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)

  help: 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(()) } ```

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.