NAME
Log::Shiras::Report::CSVFile - A report base for csv files
SYNOPSIS
use Modern::Perl;
#~ use Log::Shiras::Unhide qw( :InternalReporTCSV );
use Log::Shiras::Switchboard;
use Log::Shiras::Telephone;
use Log::Shiras::Report;
use Log::Shiras::Report::CSVFile;
use Log::Shiras::Report::Stdout;
$ENV{hide_warn} = 1;
$| = 1;
my $operator = Log::Shiras::Switchboard->get_operator(
name_space_bounds =>{
UNBLOCK =>{
to_file => 'info',# for info and more urgent messages
},
},
reports =>{
to_file =>[{
superclasses =>[ 'Log::Shiras::Report::CSVFile' ],
roles =>[ 'Log::Shiras::Report' ],# checks inputs and class requirements
file => 'test.csv',
}],
}
);
my $telephone = Log::Shiras::Telephone->new( report => 'to_file' );
$telephone->talk( level => 'info', message => 'A new line' );
$telephone->talk( level => 'trace', message => 'A second line' );
$telephone->talk( level => 'warn', message =>[ {
header_0 => 'A third line',
new_header => 'new header starts here' } ] );
#######################################################################################
# Synopsis file (test.csv) output
# 01: header_0
# 02: "A new line"
# 03: "A third line"
#######################################################################################
#######################################################################################
# Synopsis file (test.csv) output with line 24 commented out
# 01: header_0,new_header
# 02: "A third line","new header starts here"
#######################################################################################
DESCRIPTION
This is a report module that can act as a destination in the "reports" in Log::Shiras::Switchboard name-space. It is meant to be fairly flexible and will have most of the needed elements in the class without added roles. An instance of the class can be built either with ->new or using the implied MooseX::ShortCut::BuildInstance helpers. (See lines 18 - 20 in the example) When the report is set up any call to that report namespace will then implement the add_line method of this class.
As implied in the Synopsis one of the features of this class is the fact that it will try to reconcile the headers to inbound data and header requests. This class will attempt to reconcile any deviation between the first passed row and the header. Subsequent added rows using a passed array ref will add all values without warning whether the count matches the header count or not. Subsequent added rows using a passed hashref will only used the headers in the fixed header list but will warn for any passed headers not matching the header list.
This class will attempt to obtain an exclusive lock on the file. If the file is previously locked it will wait. That will allow you to attach more than one report script to the same file name and not overwrite lines. On the other hand this does have the potential to create scripts that appear to be hung.
Warning
This class will always use the header list when adding new hash values. As a consequence there can be no duplicates in the header list after it is coereced to this files requirements. Since the class allows for mixed passing of array refs and hash refs it also has the no duplicate header requirement with array ref handling too.
Attributes
Data passed to ->new when creating an instance. For modification of these attributes after the instance is created see the attribute methods.
file
Definition: This is the file name to be used by the .csv file. This should include the full file path. If the file does not exist then the file will be created.
Default: None
Required: Yes
Range: it must have a .csv extention and can be opened
attribute methods
set_file_name( $file_name )
Description used to set the attribute
get_file_name
Description used to return the current attribute value
headers
Definition: This an array ref of the requested headers in the file. Each of the headers must match header string requirements. The header strings will be coerced as needed buy forcing then lower case and removing any newlines.
Default: None
Required: No
Range: An array ref of strings starting with a lower case letter and containing letters, underscores, and numbers
attribute methods
set_headers( $array_ref )
Description used to set all the attribute at once
get_headers
Description used to return all the attribute at once
has_headers
Description predicate for the whole attribute
number_of_headers
Description Returns the complete header count list
reconcile_headers
Definition: It may be that when you open a file the file already has headers. This attribute determines if the action or requested headers are merged with the file headers. In the merge the file headers are given order precedence so new requested headers wind up at the end even when that means the requested headers are added out of order to the original request!
Default: 1 = the headers will be reconciled
Range: Boolean
attribute methods
set_reconcile_headers( $bool )
Description used to set the attribute
should_reconcile_headers
Description used to return the current attribute value
test_first_row
Definition: It may be that when you send the first row after instance instantiation that the row and the headers don't agree. This will update the requested headers ( and maybe the file headers) with any variation between the two. In the case of a passed array ref no header change is implemented but a warning is emitted when the passed list and the header list don't have the same count. For passed hash refs new headers are added to the end of the requested headers. After the first line no warning is emitted for passed array refs that don't match and new hash keys (and their values) that don't match the header will just be left off the report. New hash keys for the first row will be added in a random order.
Default: 1 = the first row will attempt reconciliation
Range: Boolean
attribute methods
should_test_first_row
Description used to return the current attribute value
Methods
new( %args )
Definition: This creates a new instance of the CSVFile report class.
Range: It will accept any or none of the Attributes
Returns: A report class to be stored in the switchboard.
add_line( $message_ref )
Definition: This is the method called by the switchboard to add lines to the report. It will expect a message compatible with "master_talk( $args_ref )" in Log::Shiras::Switchboard. There is some flexibility in the consumption of the value within the 'message' key. This package will check if there is more than one item and handle it like an elements list. If there is only one item and it is a hash ref it will attempt to consume the hashref as having keys matching the columns. Other single elements will be consumed as sub-elements of an element list.
Returns: 1 (or dies)
GLOBAL VARIABLES
- $ENV{hide_warn}
-
The module will warn when debug lines are 'Unhide'n. In the case where the you don't want these notifications 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.
DEPENDENCIES
File::Copy - copy
Carp - confess cluck
Fcntl - :flock LOCK_EX LOCK_UN SEEK_END