Fabrice Gabolde avatar Fabrice Gabolde committed 2594687

Logger base class documentation.

Comments (0)

Files changed (1)

lib/Floop/Logger.pm

     method log_access;
 
 }
+
+=pod
+
+=head1 NAME
+
+Floop::Logger -- Base abstract class for all loggers in Floop
+
+=head1 SYNOPSIS
+
+  use Floop::Logger::Unicorn;
+  # replace the default Console logger with something a little more
+  # fluffy
+  my $floop = Floop->new(logger =>
+      Floop::Logger::Unicorn->new(log_level => 3),
+      ...);
+  $floop->debug('debug messages are level 5 so they will not show');
+  $floop->info('info messages are level 3 so they will not show');
+  $floop->warning('warning messages are level 3 so they will show');
+  $floop->error('error messages are level 2 so they will show');
+  $floop->fatal('fatal messages are level 1 so they will show,
+                 especially when demonstrating apps to the client');
+
+  $floop->core('core level (6) should be reserved for when debugging Floop itself, or plugins');
+  $floop->log('KOWABUNGA', 'this is a custom log label, it does not have a level');
+
+  # loggers can choose to redirect this someplace else
+  $floop->log_access($request);
+
+=head1 DESCRIPTION
+
+This abstract class provides a common interface to be implemented by
+subclasses.  L<Floop> provides two such (simple) subclasses,
+L<Floop::Logger::Console> and L<Floop::Logger::File>.
+
+=head1 ATTRIBUTES
+
+=head2 log_level
+
+(read-write positive integer)
+
+C<log_level> controls how much of your log statements should be
+printed (or drawn on crystal white beaches by a unicorn's hoof,
+whatever your logger subclass does).  Levels 6 through 1 map to
+C<CORE>, C<DEBUG>, C<INFO>, C<WARNING>, C<ERROR> and C<FATAL>,
+respectively.
+
+=head1 METHODS
+
+=head2 log (abstract)
+
+  $logger->log('DANGER', 'WILL ROBINSON!');
+
+The C<log> method's first argument is the log level (as a string) of
+the statement being logged.  The rest are usually a single string that
+describes the message being logged, but the base class imposes no
+restrictions on this.  L<Floop> itself, however, already logs strings,
+so new logger classes are expected to be able to handle a single
+string somehow.
+
+=head2 log_access
+
+  $logger->log_access($plack_request);
+
+Application developers are not expected to call this method; it is
+used to log requests separately from debug or error logs.  If you
+write a logger subclass, however, you are expected to provide an
+implementation for this method.
+
+This method takes a L<Plack::Request> as its argument.
+
+=head2 core
+
+=head2 debug
+
+=head2 info
+
+=head2 warning
+
+=head2 error
+
+=head2 fatal
+
+These all curry their respective log level (as a string) to the C<log>
+method.  They will do nothing if C<log_level> is not high enough.
+
+=head1 SEE ALSO
+
+L<Floop>
+
+=head1 AUTHOR
+
+Fabrice Gabolde <fabrice.gabolde@gmail.com>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright (C) 2014 Fabrice Gabolde
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself, either Perl version 5.10.0 or,
+at your option, any later version of Perl 5 you may have available.
+
+=cut
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.