Crate bare_err_tree

Crate bare_err_tree 

Source
Expand description

bare_err_tree is a no_std and no alloc library to print an Error with a tree of sources.

Support for the extra information prints does not change the type or public API (besides a hidden field or deref). It is added via macro or manual implementation of the AsErrTree trait. End users can then use ErrTreeDisplay or tree_unwrap to get better error output, or store as JSON for later reconstruction.

If none of the tracking feature flags are enabled, the metadata is set to the unit type to take zero space. If the print methods are never called, and none of the tracking features are enabled, this library incurs zero runtime cost. Usage of the err_tree macro incurs a compliation time cost.

§Feature Flags

  • derive: Enabled by default, provides err_tree via proc macro.
  • json: Allows for storage to/reconstruction from JSON.
  • heap_buffer: Uses heap to store so state that FRONT_MAX (x3 if tracing is enabled) bytes of the stack aren’t statically allocated for this purpose.
  • boxed: Boxes the error package. Addresses ballooning from large tracking features. Boxing the error itself is likely more efficient, when available.
  • unix_color: Outputs UNIX console codes for emphasis.
  • anyhow: Adds implementation for [anyhow::Error].
  • eyre: Adds implementation for [eyre::Report].
§Tracking Feature Flags
  • source_line: Tracks the source line of tree errors.
  • tracing: Produces a tracing backtrace with [tracing_error].

§Adding ErrTree Support (Library or Bin)

Both libraries and binaries can add type support for ErrTree prints. The err_tree macro is recommended, but ErrTree allows for a manual implementation.

§Feature Flags in Libraries

Libraries should NOT enable any of the tracking feature flags by default. Those are tunable for a particular binary’s environment and needs. ErrTreeDisplay/tree_unwrap should be used sparingly within the library, ideally with a small FRONT_MAX to minimize out of stack memory errors.

§Using AsErrTree Implementors (Bin)

Specify desired tracking features by importing bare_err_tree in Cargo.toml. (e.g. bare_err_tree = { version = "*", features = ["source_line"] })

Call tree_unwrap on the Result or ErrTreeDisplay on the Error with FRONT_MAX set to 6 * (maximum tree depth). Note that unless heap_buffer is enabled, FRONT_MAX (x3 if tracing is enabled) bytes will be occupied on stack for the duration of a print call. Make sure this falls within platform stack size, and single stack frame size, limits.

§Credit

The formatting is borrowed from from error-stack. Please see the contributors page for appropriate credit.

§Licensing and Contributing

All code is licensed under MPL 2.0. See the FAQ for license questions. The license is non-viral copyleft and does not block this library from being used in closed-source codebases. If you are using this library for a commercial purpose, consider reaching out to dansecob.dev@gmail.com to make a financial contribution.

Contributions are welcome at https://github.com/Bennett-Petzold/bare_err_tree.

Re-exports§

pub use flex::*;

Modules§

flex

Macros§

tree
Boilerplate reducer for manual ErrTree.

Structs§

ErrTree
Intermediate struct for printing created by AsErrTree.
ErrTreeDisplay
Produces ErrTree formatted output for an error.
ErrTreePkg
Captures extra information for ErrTree automatically.
InnerErrTreePkg

Traits§

AsErrTree
Defines an Error’s temporary view as an ErrTree for printing.

Functions§

tree_unwrap
Alternative to Result::unwrap that formats the error as a tree.

Attribute Macros§

err_treederive
Implements a type as an error tree.