Allow indirect usage

[PvdBerg1998]

Currently, the crate can only be used as the only, global, panic handler. It would be great if the formatter could be used separately, on a custom writer.

In my case, this prevents me from being able to use this, since I require some custom logic in my panic hook. It'd be awesome if I could make use of this beautiful formatting though!

[athre0z]

The create_panic_handler function can be used to create a panic handler without automatically registering it globally. This allows you to compose color_backtrace's panic handler with your own one.

[PvdBerg1998]

I see, but that still prints directly to stderr. In my case I want to control this myself for multiple reasons (eg writing some things to a file, maybe not having stderr available), and this does not allow that. Having for example a Display impl for a coloured panic formatter would be great there, since I could use it in every way possible, it'd be the most flexible.

[PvdBerg1998]

In other words: while plug-and-play is probably great for 90% of the use cases, it would be great if some other functionality would be available as public functions aswell (filtering the backtrace for example).

[yaahc]

To add to this, I'd love to be able to use this with backtraces produced by failure::Error. Something like

pub fn handle_script_result(ret: Result<(), Error>) {
    let ret = match &ret {
        Ok(_) => 0,
        Err(e) => {
            if backtrace.is_empty() {
                info!("{}", "note: Run with `RUST_BACKTRACE=1` for a backtrace.");
            } else {
                info!("{:#?}", e.find_root_cause());
                color_backtrace::print(e.backtrace());
            };

            error!("{}", e);
            1
        }
    };

    std::process::exit(ret);
}

to just manage nicely printing the backtrace that I already have. If I try to replace this handler with an unwrap on the Result it KINDA works, but it prints the backtrace I care about as the message and produces a new backtrace that is nicely formatted where I unwrap the result.

[athre0z]

Exposing more of the currently internal API is certainly something we can do. The main reason for the current API to be extremely minimal is to give me some room for brutal refactorings without breakage while the crate is still very new. I'd suggest we wait a few weeks until most major issues surfaced, then we can take a look at exposing more stuff publicly!

Supporting failure::Error backtraces is something I'm interested in as well -- I think this might even deserve it's own issue.

[PvdBerg1998]

Imo breaking changes are not an issue, that's what semantic versioning is for, right 😃

[arcnmx]

Perhaps a trade-off at the expense of more maintenance burden: pull out the internals into a separate crate with the expectation of a lot of api churn and aggressive semantic version bumps there, and keep color-backtrace the minimal user-facing crate so that the internals, output printing, etc. can be changed across minor/patch updates?

[athre0z]

I now refactored things into a design that I'm happy with for now and exposed the printing functions as print_backtrace (printing just a backtrace-rs backtrace) and print_panic_info (doing the entire panic info printing as well as capturing and printing a stack-trace). The output stream can be configured via Settings::output_stream. Just implementing Display would not have worked because on some platforms (Windows), colors aren't controlled via escape sequences in the output text but via syscalls instead.

@yaahallo: in order to be able to use this with the failure crate, we'll have to ask them to expose access to the actual backtrace-rs Backtrace when it is available. Right now, they just expose a wrapper object that implements Display as well as a few more traits, but, as far as I can see, no way to actually access the trace that we would need. Do you want to create an issue over at their repo for this?

I'll wrap these changes into a new release once we concluded on how to proceed with #2.