NAME
Log::Shiras::Telephone - Send messages with Log::Shiras
SYNOPSIS
package MyCoolPackage;
use Moose;
use lib 'lib', '../lib',;
use Log::Shiras::Telephone;
sub make_a_noise{
my( $self, $message ) = @_;
my $phone = Log::Shiras::Telephone->new(
name_space => 'TellMeAbout::make_a_noise',
fail_over => 1,
report => 'spy',
);
$phone->talk( level => 'debug',
message => "Arrived at make_a_noise with the message: $message" );
print '!!!!!!!! ' . uc( $message ) . " !!!!!!!!!\n";
$phone->talk( level => 'info',
message => "Finished printing message" );
}
package main;
use Modern::Perl;
use Log::Shiras::Switchboard;
use Log::Shiras::Report::Stdout;
use MyCoolPackage;
$| = 1;
my $agitation = MyCoolPackage->new;
$agitation->make_a_noise( 'Hello World 1' );#
my $operator = Log::Shiras::Switchboard->get_operator(
name_space_bounds =>{
TellMeAbout =>{
make_a_noise =>{
UNBLOCK =>{
# UNBLOCKing the report (destinations)
# at the 'TellMeAbout::make_a_noise' caller name_space and deeper
spy => 'info',# for info and more urgent messages
},
},
},
},
);
$agitation->make_a_noise( 'Hello World 2' );#
$operator->add_reports(
spy =>[ Print::Log->new, ],
);
$agitation->make_a_noise( 'Hello World 3' );#
#######################################################################################
# Synopsis Screen Output
# 01: !!!!!!!! HELLO WORLD 1 !!!!!!!!!
# 02: !!!!!!!! HELLO WORLD 2 !!!!!!!!!
# 03: This message sent to the report -spy- was approved but found no destination objects to use at log_shiras_telephone.pl line 16, <DATA> line 1.
# 04: MyCoolPackage::make_a_noise(MyCoolPackage=HASH(0x58df970), "Hello World 2") called at log_shiras_telephone.pl line 67
# 05: Finished printing message
# 06: !!!!!!!! HELLO WORLD 3 !!!!!!!!!
# 07: | level - info | name_space - TellMeAbout::make_a_noise
# 08: | line - 0016 | file_name - log_shiras_telephone.pl
# 09: :( Finished printing message ):
#######################################################################################SYNOPSIS EXPLANATION
Output explanation
01: This is the result of
$agitation->make_a_noise( 'Hello World 1' );Where the output is processed by the make_a_noise method of the package MyCoolPackage
02: Same as line 01
03-05: The switchboard actually turned on permissions for some logging from MyCoolPackage prior to the output from line 02 but there was no report destination available so the 'fail_over' attribute kicked in and printed the message out with a warning.
06: Same as line 01
07-09: This time before the output for line 06 was sent an actual report object was registered in the switchboard against the 'spy' report name that MyCoolPackage was sending logging messages to. These lines are the result of that report object Log::Shiras::Report::Stdout with the note that line 09: and line 05: have the same content but ~::Report::Stdout leverages some of the meta-data in the message to create a more informative output set.
DESCRIPTION
This is a convenience wrapper for the Switchboard method master_talk. It also provides some additional function not provided in the leaner and stricter master_talk method. First, the input is more flexible allowing for several ways to compose the message. Second, most of the Attributes of a phone are sent as the key parts of a message ref for to the Switchboard. Each of these attributes has a default allowing for them to be ommited from the phone talk method call. Third, the phone has and additional attribute fail_over which can be used to trigger printing the message when it is cleared by the switchboard but a report object isn't built yet. This will allow for development work on writing messages without having to predefine the full output destination. Finally, built into 'talk' is the ability to request input with the 'ask' key. This is done without accessing the Switchboard. This creates a range of uses for the 'talk' command. It is possible to call 'talk' with no arguments and only collect the metadata for that script point to be sent to a destination log. Another possiblity is to call talk with some of the attribute settings changed for that 'talk' command only. When a 'talk' command receives values to replace the attributes they are in force for that call of the 'talk' method only. Updating the default $phone attributes are done with the attribute methods.
Please note the effect of calling level => 'fatal' documented in "logging_levels" in Log::Shiras::Switchboard
Please also note that the switchboard will add some meta data to the message before it passes the message on to the report. See the documentation in "master_talk( $args_ref )" in Log::Shiras::Switchboard
This module is meant to work with Log::Shiras::Switchboard at run time. When collecting output from the phone the switchboard must be activated to enable desired messages to get through. For an overview of the package see Log::Shiras.
Attributes
Data passed to ->new when creating an instance. For modification of these attributes after the instance is created see the attribute methods.
name_space
Definition: This is meant to represent the 'from' designation of a Telephone call. This attribute stores the specific point in a hierarchical name-space used by the instance of this class. The name-space position called does not have to be unique. The name-space is identified in a string where levels of the name-space in the string are marked with '::'. If this attribute receives an array ref then it joins the elements of the array ref with '::'.
Default: If no name-space is passed then this attribute defaults to the value returned by
(caller( 2 ))[3]which is driven by the location where the ->new command is called.
Range: "NameSpace" in Log::Shiras::Types
attribute methods
set_name_space
Description used to set the attribute
get_name_space
Description used to return the current attribute value
report
Definition: This is meant to represent the 'to' nature of a Telephone call. This attribute stores the specific destination name in a flat name-space for this instance of this class.
Default: 'log_file'
Range: a string
attribute methods
set_report
Description used to set the attribute
get_report
Description used to return the current attribute value
level
Definition: This represents the urgency for which the message is sent. A message level of fatal will kill the script if the Switchboard permissions are set to allow it through.
Default: 11 = 'eleven' or the very highest setting (urgency)
Range: "ElevenInt" in Log::Shiras::Types or "logging_levels" in Log::Shiras::Switchboard
attribute methods
set_level
Description used to set the attribute
get_level
Description used to return the current attribute value
message
Definition: This is a message ref that will be sent to the report.
Default: [ '' ]
Range: an ArrayRef or a string (which will be used as [ $string ] ) If you wish to send a $hashref send it as [ $hashref ].
attribute methods
set_shared_message
Description used to set the attribute
get_shared_message
Description used to return the current attribute value
carp_stack
Definition: This is a flag used to append the message with a Carp - longmess
Default: 0 = No appended longmess
Range: 1 or 0
attribute methods
set_carp_stack
Description used to set the attribute
should_carp_longmess
Description used to return the current attribute value
fail_over
Definition: This attribute stores a boolean value that acts as a switch to turn off or on an outlet to messages sent via ->talk that are approved based on name_space and urgency but do not find any report objects to interact with. If fail_over is on then the 'message' elements are printed to STDOUT. (joined by "\n\t",) This is a helpfull feature when writing code containing the Telephone but you don't want to set up a report to see what is going on. You can managage a whole script by having a $fail_over variable at the top that is used to set each of the fail_over attributes for new telephones. That way you can turn this on or off for the whole script at once if you want.
Default: 0 = off -> unreported succesfull messages die silently
Range: a boolean 1 or 0
attribute methods
set_fail_over
Description used to set the attribute
should_fail_over
Description used to return the current attribute value
Methods
new( %args )
Definition: This creates a new instance of the Telephone class. It is used to talk to reports through the switchboard.
Range: This is a Moose class and new is managed by Moose. It will accept any or none of the Attributes
Returns: A phone instance that can be used to 'talk' to reports.
talk( %args )
Definition: This is the method to place a call to a reports name. The talk command accepts any of the attributes as arguments as well as an 'ask' key. The ask key set to 1 will cause the telephone to pause for input and append that input to the 'message'. Any passed key that matches an attribute will locally implement the passed value without overwriting the default value. The passed %args with attribute keys can either be a Hash or a HashRef. If the passed content does not show either a message key, an ask key, or a level key set to fatal then it is assumed to be the message and 'talk' will re-wrap it with a message key into a hashref. If you want the message to be a HashRef then it has to reside inside of an ArrayRef. ex.
[ { ~ my message hash ~ } ],When the message has been coerced into a format that the Switchboard will consume the {ask} key is tested and implemented. After the ask key processing is complete the message is sent to "master_talk( $args_ref )" in Log::Shiras::Switchboard. The return value from that call is then evaluated against the attribute fail_over. If needed the message is output at that time. It should be noted that the results of the 'master_talk' can fall in the following range.
-3 = The call was not allowed by name_space permissions set in the switchboard
-2 = The message was buffered rather than sent to a report
-1 = You should never get this from a Telephone talk call
0 = The call had permissions but found no report implementations to connect with
1(and greater) = This indicates how many report instances received the messagefail_over is only implemented on a '0' return. Read the name_space_bounds documentation to understand how the switchboard handles message filtering. Note: the switchboard will set the urgency level of a call to 0 if a level name is sent but it does not match the available log level list for the destination report held by the Switchboard.
Returns: The number of times the message was sent to a report object with 'add_line'
GLOBAL VARIABLES
- $ENV{hide_warn}
-
The module will warn if debug lines are 'Uhide'n. In the case where the you don't want this notification set this environmental variable to true.
SUPPORT
TODO
1. Nothing currently
AUTHOR
COPYRIGHT
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.