# NAME CSV::HistoryPlayer - Plays scattered CSV files with historic data # VERSION 0.02 # STATUS # SYNOPSYS use CSV::HistoryPlayer; my $player = CSV::HistoryPlayer->(root_dir => 'path/to/directory'); while (my $data = $player->poll) { my ($file, $row) = @$data; print "event occured at ", $row->[0], "\n"; } # DESCRIPTION Let's assume you have many of CSV-files, each one has some events written in it (in the **first** column in form of unix timestamp) and filenames also have encoded date of the events within, i.e. ├── income │   ├── 2015-02-10.csv │   └── 2015-02-12.csv └── outcome ├── 2015-02-11.csv └── 2015-02-12.csv Let's assume, that the files have content like: income/2015-02-10.csv: 1455106611, 10, "got pocket money from Mom" income/2015-02-12.csv: 1455301001, 15, "got pocket money from Dad" outcome/2015-02-11.csv: 1455203801, 10, "bought Immortal CD (black metal)" outcome/2015-02-12.csv: 1455307400, 10, "bought Obsidian Gate CD (black metal)" Now, you would to replay all transactions. That's easy use CSV::HistoryPlayer; my $player = CSV::HistoryPlayer->(root_dir => 'path/to/directory'); while (my $data = $player->poll) { my ($file, $row) = @$data; my ($when, $how_much, $description) = @$row; my $sign = $file =~ /income/ ? '+' : '-'; print $sign, " ", $how_much, '$: ', $description, "\n"; } # +10$: got pocket money from Mom # -10$: bought Immortal CD (black metal) # +15$: got pocket money from Dad # -10$: bought Obsidian Gate CD (black metal) I.e. the [CSV::HistoryPlayer](https://metacpan.org/pod/CSV::HistoryPlayer) virtually unites scattered CSV files, and allows to read evens from them in historically correct order. # ATTRIBUTES - `root_dir` The root directory, where the csv files should be searched from. This attribute is **mandatory**. - `dir_filter` The closure, which allows to filter out unneeded directories, in the file scan phase to do not include csv-files within my $player = CSV::HistoryPlayer->( ..., # if returns true, than dir will be scanned for csv-files dir_filter => sub { $_[0] =~ /income/ }, ); By default, all found directories are allowed to be scanned for CSV-files. - `files_mapper` The closure, which allows to do custom sort and filtering of found CSV-files in historical order. By default CSV-files are lexically sorted and not filtered. For example, if there are files `3-Jan-16.csv`, `4-Jan-16.csv`, ..., they can be sorted with [Date::Utility](https://metacpan.org/pod/Date::Utility) files_maper => sub { my $orig_files = shift; my @files = map { $_->{file} } sort { $a->{epoch} <=> $b->{epoch} } map { my $date = /(.*\/)(.+)/ ? $2 : die("wrong filename in $_"); { file => $_, epoch => Date::Utility->new($date)->epoch, } } @$orig_files; return \@files; } - `files` Returns historically sorted list of found CSV-files; each item in the list is [Path::Tiny](https://metacpan.org/pod/Path::Tiny) instance. # METHODS - `peek` Returns the reference to the current pointer in the i<virtual> CSV-file and the actual file. Initially it points to the earliest row of the historically first file. If there are many concurrent files, than the earliest row of them is returned. If end of i<virtual> CSV-file is reached, then `undef` is returned my $data = $player->peak; if ($data) { my ($file, $row) = @$data; } - `poll` The same as `peak` method, but after return of the current row in the i<virtual> CSV-file, it moves the pointer to the next row. Designed to serve as iterator, while (my $data = $player->poll) { my ($file, $row) = @$data; } # ASSUMPTIONS - Same filenames for the same timeframe CSV-files aggregate events on some time-frame (i.e. one day, one hour, one week etc.). The [CSV::HistoryPlayer](https://metacpan.org/pod/CSV::HistoryPlayer) does not sort content of files due to performance reasons. Than means, if you have files, organized like: event-a/date_1.csv event-b/date_2.csv and `date_1` and `date_2` intersects, then they should have exactly the same name, e.g.: event-a/3-Jan-16.csv event-b/3-Jan-16.csv to be replayed correctly. - unix timestamp is the first column in CSV-files - CSV-files are opened with the defaults of [Text::CSV](https://metacpan.org/pod/Text::CSV) # SEE ALSO [Text::CSV](https://metacpan.org/pod/Text::CSV), [Higher-Order Perl](http://hop.perl.plover.com) # SOURCE CODE [GitHub](https://github.com/binary-com/perl-CSV-HistoryPlayer) # AUTHOR binary.com, `` # BUGS Please report any bugs or feature requests to [https://github.com/binary-com/perl-CSV-HistoryPlayer/issues](https://github.com/binary-com/perl-CSV-HistoryPlayer/issues). # LICENSE AND COPYRIGHT Copyright (C) 2016 binary.com This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at: [http://www.perlfoundation.org/artistic\_license\_2\_0](http://www.perlfoundation.org/artistic_license_2_0) Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license. If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license. This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder. This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed. Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.