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

AUTHOR

Jed Lund
jandrew@cpan.org

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