NAME

DBIx::Squirrel::Errors - report the DBI's errors at the caller's line

SYNOPSIS

use DBIx::Squirrel::Errors qw(at_caller);

my $sth = at_caller { $self->SUPER::prepare($statement) };

DESCRIPTION

Under RaiseError, the DBI reports an error at the line that called it. Inside DBIx::Squirrel, that's a line of DBIx::Squirrel's own, which is no help to its user. This module moves the error to the user's line. It does the same for the DBI's warnings, under PrintError. Nothing is exported by default.

VARIABLES

@INTERNAL

our @CARP_NOT = @DBIx::Squirrel::Errors::INTERNAL;

The packages Carp looks past to report an error at the line that called DBIx::Squirrel: the DBI's, DBIx::Squirrel's, and Ekorn::Pipeline's, which runs its stages. A module of stages, or of functions that take stages, sets its @CARP_NOT to it. Then what it croaks while a stage runs is reported at the line that asked for the result, not inside DBIx::Squirrel.

FUNCTIONS

at_caller

@values = at_caller { ... };

Runs the block, which calls the DBI, and returns what it returns, in the same context. The block may die with a string located at the block's own file. Then the location is removed, and the message is raised again with "croak" in Carp. That reports it at the first line outside the DBI and DBIx::Squirrel. The DBI's message itself, such as DBD::SQLite::db prepare failed: ..., is unchanged. Any other error, such as an object, or a string from a HandleError callback, is raised again unchanged.

A warning given while the block runs, as the DBI gives one under PrintError, is moved the same way, if it's located at a line of a file at_caller has been called from. It's passed on to the __WARN__ handler there was before, or warned if there was none.

croakf

croakf 'Expected a value for each placeholder (none for %s)', $names;

Croaks with a message made by sprintf from a format and its arguments. It reports it at the same line as "croak" in Carp would.

The format is a literal, written in the code. Values go in as arguments, through %s and the like, never as the format. A format made from data does whatever its % directives say. %999999999s, for example, makes a string of a gigabyte.

failed

croak failed($dbh, 'prepare');

Returns the message the DBI raises under RaiseError when a handle's method fails, such as DBD::SQLite::db prepare failed: .... It's for an error DBIx::Squirrel raises itself.

in_method

return in_method($dbh, 'do', sub { ... });

Runs the code as one method of a database handle, and returns what it returns. The DBI may raise an error for a method the code calls, such as DBD::SQLite::st execute failed: .... It's raised again as the DBI raises one for the handle's method, DBD::SQLite::db do failed: ..., as plain DBI does. Any other error is raised again unchanged.

A warning the DBI gives for a method the code calls, as it does under PrintError, names the handle's method too. It's passed on to the __WARN__ handler there was before, or warned if there was none. When in_method runs inside itself, the outer call's method is the one named.

SEE ALSO

DBIx::Squirrel, "RaiseError" in DBI

AUTHOR

Iain Campbell <cpanic@cpan.org>

LICENSE

Copyright (c) 2024-2026 by Iain Campbell.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.