NAME

Chandra::Error - Error handling with stack traces for Chandra

SYNOPSIS

use Chandra::Error;

# Register an error handler
Chandra::Error->on_error(sub {
    my ($err) = @_;
    warn Chandra::Error->format_text($err);
});

# Capture an error (typically used internally)
eval { die "something broke" };
my $err = Chandra::Error->capture($@, context => 'MyModule');

# Format for display
my $text = Chandra::Error->format_text($err);
my $js   = Chandra::Error->format_js_console($err);

DESCRIPTION

Chandra::Error provides centralised error handling with stack traces for the Chandra framework. When an error is captured it is recorded with its originating context and a stack trace, then all registered handlers are notified.

Chandra::Bind uses this module automatically so that callback errors are surfaced to DevTools and any custom on_error handlers.

CLASS METHODS

on_error($coderef)

Register a callback invoked whenever capture() records an error. The callback receives a single hashref argument.

clear_handlers()

Remove all registered error handlers.

handlers()

Return an arrayref of currently registered handlers.

capture($error, %opts)

Capture an error. Options:

context - descriptive label, e.g. 'call(greet)'

skip - stack frames to skip (default 2)

Returns a hashref: { message, context, trace, time }.

format_text($err)

Render a captured error as a multi-line string with stack trace.

format_js_console($err)

Return a JavaScript console.error(...) statement for the error.

stack_trace($skip)

Build a stack trace starting $skip frames above the caller. Returns an arrayref of { package, file, line, sub } hashrefs.

SEE ALSO

Chandra::App, Chandra::Bind, Chandra::DevTools