sonro/narrate

Rust CLI utility library. Error handling, status reporting, and exit codes.

narrate's Issues

Custom types implementing ExitCode are being ignored

Problem

Current ExitCode behaviour does not produce custom exit codes. Unless the underlying error is an Error or CliError, any calls to ExitCode::exit_code() will just produce the default 70.

Proposed Solution

Replace the ExitCode trait with assigning exitcodes to an Error.

Integration test all API surfaces

Upgrade integration tests to check the entirity of the public API

Re-export Color enum

colored::Color enum should not be exposed to end users.

Tune up readme

Rewrite readme to be more in line with how this particular library should be used. At the moment it is missing several parts of the API

Relevant examples

• Integration with anyhow
• Reporting statuses
• Reporting errors
• Standalone error library
• ExitCode implementation
• CliError usage

Feature flags

• report
• error
• cli-error
• default: report, error, cli-error

Separate wrapping from adding help messages

BREAKING CHANGE

Simplify ErrorWrap API to sometthing more akin to:

possible_error()
    .wrap(|| "error message")
    .set_help("help message")?;

Seal `ErrorWrap` trait

BREAKING CHANGE

Stop ErrorWrap from being implemented outside of the crate.

Streamline report functions

The isatty function only needs to be called once.

Add crate root rustdoc

Add a library introduction and API overview in rustdoc to the crate root

Error debug formatting

Change the Error debug format to be more in line with anyhow.

Move anyhow integration behind a feature flag

BREAKING CHANGE

Hide Error::downcast and Error::from_anyhow behind an "anyhow" feature flag. These are currently the only public APIs using anyhow types. Moreover only publicly re-export anyhow crate behind the feature flag.

This allows the default API to keep the implementation separate from the user and the "anyhow" feature-set to allow conversion between the two types.

Add anyhow macros

anyhow! and bail! transparent macros

Compile error when using `narrate::{bail, error_from}` without specifying `anyhow` as dependency

Bug Report

Using narrate::{bail, error_from} in a project that doesn't specify anyhow as a dependency separately (regardless of if the anyhow feature of narrate is used) unconditionally triggers a compile error. (AFAIK this is a bug, as documentation doesn't specify that anyhow must also be a dependency.)

Example

Cargo.toml

[package]
name = "example"
version = "0.1.0"
edition = "2021"

[dependencies]
narrate = { version = "0.4.1", features = ["anyhow"] }
# The above line could also have simply been:
# narrate = "0.4.1"

src/main.rs

fn main() -> narrate::Result<()> {
    narrate::bail!("this should compile");
}

cargo build

See the triggered compiler error:

error[E0433]: failed to resolve: use of undeclared crate or module `anyhow`
 --> src/main.rs:2:5
  |
2 |     narrate::bail!("this should compile");
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ use of undeclared crate or module `anyhow`
  |
  = note: this error originates in the macro `$crate::error_from` which comes from the expansion of the macro `narrate::bail` (in Nightly builds, run with -Z macro-backtrace for more info)

For more information about this error, try `rustc --explain E0433`.
error: could not compile `main` (bin "main") due to previous error

Cause

It seems that this issue stems from narrate not unconditionally requiring anyhow as a non-optional dependency. My best guess is that this was introduced in bdba927. This seems related to #4.

Remedy

In the meantime while awaiting a fix, adding anyhow as a dependency in Cargo.toml prevents the compile error.

Notes

Otherwise, narrate is a great library that does exactly what I was looking for!

Report status macros

Format report messages to standard colors.

• success!: green
• info!: blue
• warning!: orange

4 varients:

varient	output	note
success!("hello")	"success: hello"
info!("{}", msg)	"info: msg string"
warning!("title", "hello")	"title: hello"	'title' would be orange
success!("title", "{}", msg")	"title: msg string"	'title' would be green

Add public API docs

Basic documentation on all public interfaces

Fix public API typos

• Change route_cause to root_cause