Dist::Zilla::Role::ErrorLogger - Have error logging capabilities in your Dist::Zilla plugin
Version v0.9.0, released on 2015-10-26 21:04 UTC.
Dist-Zilla-Role-ErrorLogger is a Dist::Zilla role. It provides log_error, abort, and abort_if_errors methods to consuming plugins.
Dist-Zilla-Role-ErrorLogger
Dist::Zilla
log_error
abort
abort_if_errors
This is Dist::Zilla::Role::ErrorLogger role documentation. Read this if you want to have error logging capabilities in your Dist::Zilla plugin.
Dist::Zilla::Role::ErrorLogger
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 ( $cond ) { $self->log_error( 'error message' ); }; do_something or $self->log_error( 'another error message' ); while ( $cond ) { do_something_else or $self->log_error( 'error message' ) and next; ...; }; $self->log_errors_in_file( $file, 1 => 'error message', # Error at file line 1. 5 => 'another error message', # Error at file line 5. ); $self->abort_if_errors( 'errors found' ); }; __PACKAGE__->meta->make_immutable; 1;
The role extends standard Dist::Zilla logging capabilities with few methods a bit more convenient for reporting (multiple) errors than brutal log_fatal. See "WHY?" for more details.
log_fatal
The role requires log method in the consumer.
log
$int = $self->error_count;
Int, read-only. Number of logged errors (i. e. number of made log_error calls).
Int
$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:
error_count
while ( ... ) { do_something or $self->log_error( 'message' ) and next; ... };
$self->abort( @items ); $self->abort( \%args, @items );
This is an attempt to workaround log_fatal drawback: in contrast to log_fatal, abort guarantees the message (which can be quite long) appears on the screen only once.
The method log the message (via log), then flush STDOUT, then throws an exception of Dist::Zilla::Role::ErrorLogger::Exception::Abort class (which being stringified gives short message "Aborting...\n").
STDOUT
Dist::Zilla::Role::ErrorLogger::Exception::Abort
"Aborting...\n"
$self->abort_if_errors( @items ); $self->abort_if_errors( \%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.
abort_if_error is an alias for abort_if_errors.
abort_if_error
The method intended to report errors against a file. It prints file name (and colon after it), then prints line-numbered file content annotated by error messages. The method does not print entire file content, but only error lines with surrounding context (2 lines above and below each error line).
$self->log_errors_in_file( $file, $linenum1 => $message1, $linenum2 => $message2, $linenum3 => [ $message3a, $message3b, ... ], ... );
$file should be a Dist::Zilla file (e. g. Dist::Zilla::File::OnDisk, Dist::Zilla::File::InMemory, or does role Dist::Zilla::Role::File).
$file
Dist::Zilla::File::OnDisk
Dist::Zilla::File::InMemory
Dist::Zilla::Role::File
Errors are specified by pairs $linenum => $message, where $linenum is a number of problem line (one-based), and $message is an error message (Str) or array of messages (ArrayRef[Str]). Order of errors does not matter usually. However, if errors are associated with the same line (the same line number may appear multiple times), they will be printed in order of appearance.
$linenum => $message
$linenum
$message
Str
ArrayRef[Str]
Zero or negative line numbers, or line numbers beyond the last line are invalid. Messages associated with invalid line numbers are reported in unspecified way.
Normally, the method prints all the information by calling log_error method and returns a positive integer. However, If any invalid line numbers are specified, the method returns negative integer. If no errors are specified, the method prints "No errors found at file." by calling log (not log_error!) and returns zero.
TODO: Example.
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:
log_debug
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 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_errors();
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.:
Log::Dispatchouli
String::Flogger
$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.
Van de Bugger <van.de.bugger@gmail.com>
Copyright (C) 2015 Van de Bugger
License GPLv3+: The GNU General Public License version 3 or later <http://www.gnu.org/licenses/gpl-3.0.txt>.
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.
To install Dist::Zilla::Role::ErrorLogger, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Dist::Zilla::Role::ErrorLogger
CPAN shell
perl -MCPAN -e shell install Dist::Zilla::Role::ErrorLogger
For more information on module installation, please visit the detailed CPAN module installation guide.