/ 
Dist-Zilla-Role-ErrorLogger-0.005
River stage one • 7 direct dependents • 7 total dependents
/ Dist::Zilla::Role::ErrorLogger

NAME

Dist::Zilla::Role::ErrorLogger - Have error logging capabilities in your Dist::Zilla plugin

VERSION

Version 0.005, released on 2015-07-14 19:16 UTC.

WHAT?

Dist-Zilla-Role-ErrorLogger is a Dist::Zilla role. It provides log_error, abort, and abort_if_error methods to consuming plugin.

This is Dist::Zilla::Role::ErrorLogger role documentation. Read this if you want to have error logging capabilities in your Dist::Zilla plugin.

SYNOPSIS

package Dist::Zilla::Plugin::YourPlugin;
use Moose;
use namespace::autoclean;
with 'Dist::Zilla::Role::Plugin';
with 'Dist::Zilla::Role::ErrorLogger';

sub method {
    my $self = shift( @_ );
    …
    if ( … ) { $self->log_error( 'error message' ); };
    do_something or $self->log_error( 'another error message' );
    …
    while ( … ) {
        do_something_else or $self->log_error( 'error message' ) and next;
    };
    …
    $self->abort_if_error( 'errors found' );
};

__PACKAGE__->meta->make_immutable;
1;

DESCRIPTION

TODO

The role requires log and log_fatal methods in the consumer.

OBJECT ATTRIBUTES

error_count

$int = $self->error_count;

Int, read-only. Number of logged errors (i. e. number of made log_error calls).

OBJECT METHODS

log_error

$self->log_error( @items );
$self->log_error( \%args, @items );

This method calls log method, passing all the arguments, and increments value of error_count attribute. The method returns true value, so can be used in following constructs:

while ( … ) {
    do_something or $self->log_error( 'message' ) and next;
};

abort

$self->abort( @items );
$self->abort( \%args, @items );

This method logs all the arguments and aborts Dist::Zilla. Does it look similar to log_fatal? Yep. This is attempt to workaround log_fatal drawback. In contrast to log_fatal, abort guarantees the message appears on the screen only once.

TODO: Describe exception.

abort_if_error

$self->abort_if_error( @items );
$self->abort_if_error( \%args, @items );

If there was any errors (i. e. error_count is greater than zero), the logs all the arguments and aborts execution. Both actions (logging and aborting) are implemented by calling abort.

NOTES

All the methods defined in the role log items through the log method. Dist::Zilla takes this method from Log::Dispatchouli, the latter uses String::Flogger to process the messages. It means you can use String::Flogger tricks, e. g.:

$self->log_error( [ 'oops at %s line %d', $file, $line ] );
    #   [] are shorter than sprintf.

Also note how Log::Dispatchouli describes the log method:

$logger->log( @messages );

and says:

Each message is flogged individually, then joined with spaces.

So beware. A call

$self->log_error( 'error 1', 'error 2' );

logs one message "error 1 error 2", not two messages "error 1" and "error 2", and bumps error_count by 1, not 2.

WHY?

Dist::Zilla limits logging capabilities with 3 logging levels available in plugins through log_debug, log, and log_fatal methods. Debug level messages are turned off by default, the first fatal message terminates Dist::Zilla. This is simple, but sometimes you may want to report all the errors, instead of stopping at the first found one. In such a case log_fatal cannot be used, obviously. There are few alternatives:

Collect error messages in an array, then report all the errors with single log_fatal call:

my @errors;
…
push( @errors, … );
…
if ( @errors ) {
    $self->log_fatal( join( "\n", @errors ) );
};

This works, but current implementation of log_fatal has a disadvantage: it prints the message twice, so output will looks ugly. (See message handling in log_fatal is suboptimal.)

Another approach is reporting each error immediately with log, counting number of reported errors, and calling log_fatal once at the end:

my $error_count = 0;
…
$self->log( 'error' );
++ $error_count;
…
if ( $error_count ) {
    $self->log_fatal( 'Aborting...' );
};

This works, but incrementing the counter after each log call is boring and error-prone. Dist-Zilla-Role-ErrorLogger role automates it, making plugin code shorter and more readable:

with 'Dist-Zilla-Role-ErrorLogger';
…
$self->log_error( 'error' );
…
$self->abort_if_error();

SEE ALSO

Dist::Zilla Dist::Zilla::Role Dist::Zilla::Plugin Log::Dispatchouli String::Flogger

AUTHOR

Van de Bugger <van.de.bugger@gmail.com>

COPYRIGHT AND LICENSE

Copyright © 2015 Van de Bugger

This file is part of perl-Dist-Zilla-Role-ErrorLogger.

perl-Dist-Zilla-Role-ErrorLogger is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

perl-Dist-Zilla-Role-ErrorLogger is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with perl-Dist-Zilla-Role-ErrorLogger. If not, see <http://www.gnu.org/licenses/>.