.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Log::Contextual::Role::Router 3pm"
.TH Log::Contextual::Role::Router 3pm "2016-04-18" "perl v5.22.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Log::Contextual::Role::Router \- Abstract interface between loggers and logging code blocks
.SH "VERSION"
.IX Header "VERSION"
version 0.007000
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  package MyApp::Log::Router;
\&
\&  use Moo;
\&  use Log::Contextual::SimpleLogger;
\&
\&  with \*(AqLog::Contextual::Role::Router\*(Aq;
\&
\&  has logger => (is => \*(Aqlazy\*(Aq);
\&
\&  sub _build_logger {
\&     return Log::Contextual::SimpleLogger\->new({ levels_upto => \*(Aqdebug\*(Aq });
\&  }
\&
\&  sub before_import {
\&     my ($self, %export_info) = @_;
\&     my $exporter = $export_info{exporter};
\&     my $target = $export_info{target};
\&     print STDERR "Package \*(Aq$target\*(Aq will import from \*(Aq$exporter\*(Aq\en";
\&  }
\&
\&  sub after_import {
\&     my ($self, %export_info) = @_;
\&     my $exporter = $export_info{exporter};
\&     my $target = $export_info{target};
\&     print STDERR "Package \*(Aq$target\*(Aq has imported from \*(Aq$exporter\*(Aq\en";
\&  }
\&
\&  sub handle_log_request {
\&     my ($self, %message_info) = @_;
\&     my $log_code_block = $message_info{message_sub};
\&     my $args = $message_info{message_args};
\&     my $log_level_name = $message_info{message_level};
\&     my $logger = $self\->logger;
\&     my $is_active = $logger\->can("is_${log_level_name}");
\&
\&     return unless defined $is_active && $logger\->$is_active;
\&     my $log_message = $log_code_block\->(@$args);
\&     $logger\->$log_level_name($log_message);
\&  }
\&
\&  package MyApp::Log::Contextual;
\&
\&  use Moo;
\&  use MyApp::Log::Router;
\&
\&  extends \*(AqLog::Contextual\*(Aq;
\&
\&  #This example router is a singleton
\&  sub router {
\&     our $Router ||= MyApp::Log::Router\->new
\&  }
\&
\&  package main;
\&
\&  use strict;
\&  use warnings;
\&  use MyApp::Log::Contextual qw(:log);
\&
\&  log_info { "Hello there" };
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Log::Contextual has three parts
.IP "Export manager and logging method generator" 4
.IX Item "Export manager and logging method generator"
These tasks are handled by the \f(CW\*(C`Log::Contextual\*(C'\fR package.
.IP "Logger selection and invocation" 4
.IX Item "Logger selection and invocation"
The logging functions generated and exported by Log::Contextual call a method
on an instance of a log router object which is responsible for invoking any loggers
that should get an opportunity to receive the log message. The \f(CW\*(C`Log::Contextual::Router\*(C'\fR
class implements the \fIset_logger()\fR and \fIwith_logger()\fR functions as well as uses the
arg_ prefixed functions to configure itself and provide the standard \f(CW\*(C`Log::Contextual\*(C'\fR
logger selection \s-1API.\s0
.IP "Log message formatting and output" 4
.IX Item "Log message formatting and output"
The logger objects themselves accept or reject a log message at a certain log
level with a guard method per level. If the logger is going to accept the
log message the router is then responsible for executing the log message code
block and passing the generated message to the logging object's log method.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "before_import($self, %import_info)" 4
.el .IP "before_import($self, \f(CW%import_info\fR)" 4
.IX Item "before_import($self, %import_info)"
.PD 0
.ie n .IP "after_import($self,  %import_info)" 4
.el .IP "after_import($self,  \f(CW%import_info\fR)" 4
.IX Item "after_import($self, %import_info)"
.PD
These two required methods are called with identical arguments at two different places
during the import process. The \fIbefore_import()\fR method is invoked prior to the logging
subroutines being exported into the target package and \fIafter_import()\fR is called when the
export is completed but before control returns to the package that imported the \s-1API.\s0
.Sp
The arguments are passed as a hash with the following keys:
.RS 4
.IP "exporter" 4
.IX Item "exporter"
This is the name of the package that has been imported. It can also be 'Log::Contextual' itself. In
the case of the synopsis the value for exporter would be 'MyApp::Log::Contextual'.
.IP "target" 4
.IX Item "target"
This is the package name that is importing the logging \s-1API.\s0 In the case of the synopsis the
value would be 'main'.
.IP "arguments" 4
.IX Item "arguments"
This is a hash reference containing the configuration values that were provided for the import.
The key is the name of the configuration item that was specified without the leading hyphen ('\-').
For instance if the logging \s-1API\s0 is imported as follows
.Sp
.Vb 1
\&  use Log::Contextual qw( :log ), \-logger => Custom::Logger\->new({ levels => [qw( debug )] });
.Ve
.Sp
then \f(CW$import_info\fR{arguments}\->{logger} would contain that instance of Custom::Logger.
.RE
.RS 4
.RE
.ie n .IP "handle_log_request($self, %message_info)" 4
.el .IP "handle_log_request($self, \f(CW%message_info\fR)" 4
.IX Item "handle_log_request($self, %message_info)"
This method is called by \f(CW\*(C`Log::Contextual\*(C'\fR when a log event happens. The arguments are passed
as a hash with the following keys
.RS 4
.IP "exporter" 4
.IX Item "exporter"
This is the name of the package that created the logging methods used to generate the log event.
.IP "caller_package" 4
.IX Item "caller_package"
This is the name of the package that the log event has happened inside of.
.IP "caller_level" 4
.IX Item "caller_level"
This is an integer that contains the value to pass to \fIcaller()\fR that will provide
information about the location the log event was created at.
.IP "log_level" 4
.IX Item "log_level"
This is the name of the log level associated with the log event.
.IP "message_sub" 4
.IX Item "message_sub"
This is the message generating code block associated with the log event passed as a subref. If
the logger accepts the log request the router should execute the subref to create
the log message and then pass the message as a string to the logger.
.IP "message_args" 4
.IX Item "message_args"
This is an array reference that contains the arguments given to the message generating code block.
When invoking the message generator it will almost certainly be expecting these argument values
as well.
.RE
.RS 4
.RE
.SH "AUTHOR"
.IX Header "AUTHOR"
Arthur Axel \*(L"fREW\*(R" Schmidt <frioux+cpan@gmail.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2016 by Arthur Axel \*(L"fREW\*(R" Schmidt.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.