File Coverage

blib/lib/Mojolicious/Plugin/Logf.pm

Criterion	Covered	Total	%
statement	22	31	70.9
branch	7	12	58.3
condition	3	4	75.0
subroutine	5	8	62.5
pod	3	3	100.0
total	40	58	68.9

package Mojolicious::Plugin::Logf;

=head1 NAME

Mojolicious::Plugin::Logf - Plugin for logging datastructures using sprintf

=head1 VERSION

0.07

=head1 DESCRIPTION

L is a plugin which will log complex datastructures
and avoid "unitialized" warnings. This plugin use L or whatever
L is set to, to do the actual logging.

=head1 SYNOPSIS

  use Mojolicious::Lite;
  plugin "Logf";

  get "/" => sub {
    my $self = shift;

    $self->logf(info => 'request: %s', $self->req->params->to_hash);
  };

=head1 COPY/PASTE CODE

If you think it's a waste to depend on this module, you can copy paste the
code below to get the same functionality as the L helper:

  helper logf => sub {
    my ($c, $level, $format) = (shift, shift, shift);
    my $log = $c->app->log;
    return $c unless $log->${ \ "is_$level" };
    my @args = map {ref $_ eq 'CODE' ? $_->() : $_} @_;
    local $Data::Dumper::Indent = 0;
    local $Data::Dumper::Maxdepth = $Data::Dumper::Maxdepth || 2;
    local $Data::Dumper::Sortkeys = 1;
    local $Data::Dumper::Terse = 1;
    for (@args) {
      $_ = !defined($_) ? "__UNDEF__" : overload::Method($_, q("")) ? "$_" : ref($_) ? Data::Dumper::Dumper($_) : $_;
    }
    $log->$level(sprintf $format, @args);
    return $c;
  };

Note: The code above is generated and tested from the original source code,
but it will more difficult to get updates and bug fixes.

=cut

use Mojo::Base 'Mojolicious::Plugin';
use Data::Dumper ();
use overload ();
use constant UNDEF => $ENV{MOJO_LOGF_UNDEF} || '__UNDEF__';

our $VERSION = '0.07';

=head1 HELPERS

=head2 logf

  $self = $c->logf;
  $c = $c->logf($level => $format, @args);

Logs a string formatted by the usual C conventions of the C library
function C. C<$level> need to be a valid L level.
C<@args> will be converted using L.

Calling this method without any arguments will return C<$self>
(an instance of this plugin), allowing you to call L:

  @args_as_strings = $c->logf->flatten(@args);

=cut

sub logf {
  my ($self, $c, $level, $format, @args) = @_;
  my $log = $c->app->log;

  $log->$level(sprintf $format, $self->flatten(@args)) if $log->${ \ "is_$level" };
  $c;
}

=head1 METHODS

=head2 flatten

  @args_as_strings = $self->flatten(@args);

Used to convert input C<@args> using these rules:

=over 4

=item * Scalar

No rule applied.

=item * Code ref

A code ref will be called, and the list of return values will be flattened.
The code below will not calculate the request params, unless the log level
is "debug":

  $c->logf(debug => 'request: %s', sub {$c->req->params->to_hash});

=item * Object with string overloading

Will be coverted to a string using the string overloading function.

=item * Data structure or object

Will be serialized using L with these settings:

  $Data::Dumper::Indent = 0;
  $Data::Dumper::Maxdepth = $Data::Dumper::Maxdepth || 2;
  $Data::Dumper::Sortkeys = 1;
  $Data::Dumper::Terse = 1;

NOTE! These settings might change, but will always do its best to
serialize the object into one line. C<$Data::Dumper::Maxdepth> is
used to avoid dumping large nested objects. Set this variable
if you need deeper logging. Example:

  local $Data::Dumper::Maxdepth = 1000;
  $c->logf(info => 'Deep structure: %s', $some_object);

=item * Undefined value

Will be logged as "__UNDEF__". This value can be changed by setting
the global environment variable C before loading this
plugin.

=back

=cut

sub flatten {
  my $self = shift;
  my @args = map {ref $_ eq 'CODE' ? $_->() : $_} @_;

  local $Data::Dumper::Indent = 0;
  local $Data::Dumper::Maxdepth = $Data::Dumper::Maxdepth || 2;
  local $Data::Dumper::Sortkeys = 1;
  local $Data::Dumper::Terse = 1;

  for (@args) {
    $_ = !defined($_) ? UNDEF : overload::Method($_, q("")) ? "$_" : ref($_) ? Data::Dumper::Dumper($_) : $_;
  }

  return @args;
}

=head2 register

Will register the L helper in the application

=cut

sub register {
  my ($self, $app, $config) = @_;

  $app->helper(logf => sub {
    return $self if @_ == 1;
    return $self->logf(@_);
  });
}

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2014, Jan Henning Thorsen

This program is free software, you can redistribute it and/or modify it under
the terms of the Artistic License version 2.0.

=head1 AUTHOR

Jan Henning Thorsen - C

=cut

1;