NAME

Text::CSV::Track - module to work with .csv file that stores some value(s) per identificator

VERSION

This documentation refers to version 0.3.

SYNOPSIS

        use Text::CSV::Track;
        
        #create object
        my $access_time = Text::CSV::Track->new({ file_name => $file_name, ignore_missing_file => 1 });
        
        #set single value
        $access_time->value_of($login, $access_time);

        #fetch single value
        print $access_time->value_of($login);

        #set multiple values
        $access_time->value_of($login, $access_time);
        
        #fetch multiple values
        my @fields = $access_time->value_of($login);
        
        #save changes
        $access_time->store();
        
        #print out all the identificators we have
        foreach my $login (sort $access_time->ident_list()) {
                print "$login\n";
        }

        #getting muticolumn by hash
        $track_object = Text::CSV::Track->new({
                file_name    => $file_name
                , hash_names => [ qw{ col coool } ]
        });
        my %hash = %{$track_object->hash_of('ident')};
        print "second column is: ", $hash{'coool'}, "\n";

DESCRIPTION

The module manipulates csv file:

"identificator","value1" ...

It is designet to work when multiple processes access the same file at the same time. It uses lazy initialization. That mean that the file is read only when it is needed. There are three scenarios:

1. Only reading of values is needed. In this case first ->value_of() also activates the reading of file. File is read while holding shared flock. Then the lock is released.

2. Only setting of values is needed. In this case ->value_of($ident,$val) calls just saves the values to the hash. Then when ->store() is called it activates the reading of file. File is read while holding exclusive flock. The identifications that were stored in the hash are replaced, the rest is kept.

3. Both reading and setting values is needed. In this case 'full_time_lock' flag is needed. The exclusive lock will be held from the first read until the object is destroied. While the lock is there no other process that uses flock can read or write to this file.

When setting and getting only single value value_of($ident) will return scalar. If setting/getting multiple columns then an array.

METHODS

new()

        new({
                file_name             => 'filename.csv',
                ignore_missing_file   => 1,
                full_time_lock        => 1,
                auto_store            => 1,
                ignore_badly_formated => 1,
                header_lines          => 3,
                hash_names            => [ qw{ column1 column2 }  ],
                single_column         => 1,

                #L<Text::CSV> paramteres
                sep_char              => q{,},
                escape_char           => q{\\},
                quote_char            => q{"},
                always_quote          => 0,
                binary                => 0,
                type                  => undef,
        })
        

All flags are optional.

'file_name' is used to read old results and then store the updated ones

If 'ignore_missing_file' is set then the lib will just warn that it can not read the file. store() will use this name to store the results.

If 'full_time_lock' is set the exclusive lock will be held until the object is not destroyed. use it when you need both reading the values and changing the values. If you need just read OR change then you don't need to set this flag. See description about lazy initialization.

If 'auto_store' is on then the store() is called when object is destroied

If 'ignore_badly_formated_lines' in on badly formated lines from input are ignored. Otherwise the modules calls croak.

'header_lines' specifies how many lines of csv are the header lines. They will be skipped during the reading of the file and rewritten during the storing to the file.

'hash_names' specifies hash names fro hash_of() function.

'single_column' files that store just the identificator for line. In this case during the read 1 is set as the second column. During store that one is dropped so single column will be stored back.

See Text::CSV for 'sep_char', 'escape_char', 'quote_char', 'always_quote', 'binary, type'

value_of()

Is used to both store or retrieve the value. if called with one argument then it is a read. if called with two arguments then it will update the value. The update will be done ONLY if the supplied value is bigger.

hash_of()

Returns hash of values. Names for the hash values are taken from hash_names parameter.

store()

when this one is called it will write the changes back to file.

ident_list()

will return the array of identificators

csv_line_of($ident)

Returns one line of csv for given identificator.

TODO

        - mention Track::Max and Track::Min
        - ident_list() should return number of non undef rows in scalar context
        - strategy for Track ->new({ strategy => sub { $a > $b } })
        - then rewrite max/min to use it this way
        - different column as the first one as identiffier column
        - hash_of set functionality
        - constraints for columns

SEE ALSO

Text::CSV::Trac::Max, Text::CSV::Trac::Min, SVN repository - http://svn.cle.sk/svn/pub/cpan/Text-CSV-Track/

AUTHOR

Jozef Kutej <jozef.kutej@hp.com>