Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Log::Contextual::Role:UsertContributed Perl DoLog::Contextual::Role::Router(3)

NAME
       Log::Contextual::Role::Router - Abstract	interface between loggers and
       logging code blocks

VERSION
       version 0.007000

SYNOPSIS
	 package MyApp::Log::Router;

	 use Moo;
	 use Log::Contextual::SimpleLogger;

	 with 'Log::Contextual::Role::Router';

	 has logger => (is => 'lazy');

	 sub _build_logger {
	    return Log::Contextual::SimpleLogger->new({	levels_upto => 'debug' });
	 }

	 sub before_import {
	    my ($self, %export_info) = @_;
	    my $exporter = $export_info{exporter};
	    my $target = $export_info{target};
	    print STDERR "Package '$target' will import	from '$exporter'\n";
	 }

	 sub after_import {
	    my ($self, %export_info) = @_;
	    my $exporter = $export_info{exporter};
	    my $target = $export_info{target};
	    print STDERR "Package '$target' has	imported from '$exporter'\n";
	 }

	 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 'Log::Contextual';

	 #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" };

DESCRIPTION
       Log::Contextual has three parts

       Export manager and logging method generator
	   These tasks are handled by the "Log::Contextual" package.

       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 "Log::Contextual::Router" class
	   implements the set_logger() and with_logger() functions as well as
	   uses	the arg_ prefixed functions to configure itself	and provide
	   the standard	"Log::Contextual" logger selection API.

       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.

METHODS
       before_import($self, %import_info)
       after_import($self,  %import_info)
	   These two required methods are called with identical	arguments at
	   two different places	during the import process. The before_import()
	   method is invoked prior to the logging subroutines being exported
	   into	the target package and after_import() is called	when the
	   export is completed but before control returns to the package that
	   imported the	API.

	   The arguments are passed as a hash with the following keys:

	   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'.

	   target
	       This is the package name	that is	importing the logging API. In
	       the case	of the synopsis	the value would	be 'main'.

	   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 API is imported as
	       follows

		 use Log::Contextual qw( :log ), -logger => Custom::Logger->new({ levels => [qw( debug )] });

	       then $import_info{arguments}->{logger} would contain that
	       instance	of Custom::Logger.

       handle_log_request($self, %message_info)
	   This	method is called by "Log::Contextual" when a log event
	   happens. The	arguments are passed as	a hash with the	following keys

	   exporter
	       This is the name	of the package that created the	logging
	       methods used to generate	the log	event.

	   caller_package
	       This is the name	of the package that the	log event has happened
	       inside of.

	   caller_level
	       This is an integer that contains	the value to pass to caller()
	       that will provide information about the location	the log	event
	       was created at.

	   log_level
	       This is the name	of the log level associated with the log
	       event.

	   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.

	   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.

AUTHOR
       Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2016 by Arthur Axel "fREW" Schmidt.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

perl v5.32.1			  2016-04-12  Log::Contextual::Role::Router(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Log::Contextual::Role::Router&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help