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, provideserr_tree
via proc macro.json
: Allows for storage to/reconstruction from JSON.heap_buffer
: Uses heap to store so state thatFRONT_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 foranyhow::Error
.eyre
: Adds implementation foreyre::Report
.
§Tracking Feature Flags
source_line
: Tracks the source line of tree errors.tracing
: Produces atracing
backtrace withtracing_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§
Macros§
Structs§
- ErrTree
- Intermediate struct for printing created by
AsErrTree
. - ErrTree
Display - Produces
ErrTree
formatted output for an error. - ErrTree
Json json
- Produces JSON to store
ErrTree
formatted output. - ErrTree
Pkg - Captures extra information for
ErrTree
automatically. - Inner
ErrTree Pkg
Traits§
Functions§
- reconstruct_
output json
- Reconstructs
ErrTree
formatted output from JSON. - tree_
unwrap - Alternative to
Result::unwrap
that formats the error as a tree.
Attribute Macros§
- err_
tree derive
- Implements a type as an error tree.