List::RewriteElements 0.09

List::RewriteElements is a Perl module that can create a new list by rewriting elements of a first list.

SYNOPSIS

use List::RewriteElements;

Constructor

Simplest case: Input from array, output to STDOUT.

$lre = List::RewriteElements->new( {
list => @source,
body_rule => sub {
my $record = shift;
$record .= q{additional field};
},
} );
Input from file, output to STDOUT:
$lre = List::RewriteElements->new( {
file => "/path/to/source/file",
body_rule => sub {
my $record = shift;
$record .= q{,additional field};
},
} );
Provide a different rule for the first element in the list:
$lre = List::RewriteElements->new( {
file => "/path/to/source/file",
header_rule => sub {
my $record = shift;
$record .= q{,ADDITIONAL HEADER};
},
body_rule => sub {
my $record = shift;
$record .= q{,additional field};
},
} );
Input from file, output to file:
$lre = List::RewriteElements->new( {
file => "/path/to/source/file",
body_rule => sub {
my $record = shift;
$record .= q{additional field};
},
output_file => "/path/to/output/file",
} );
To name output file, just provide a suffix to filename:
$lre = List::RewriteElements->new( {
file => "/path/to/source/file",
body_rule => sub {
my $record = shift;
$record .= q{additional field};
},
output_suffix => .out,
} );
Provide criteria to suppress output of header or individual record.
$lre = List::RewriteElements->new( {
file => "/path/to/source/file",
header_suppress => sub {
my $record = shift;
return if $record =~ /$somepattern/;
},
body_suppress => sub {
my $record = shift;
return if $record ne somestring;
},
body_rule => sub {
my $record = shift;
$record .= q{additional field};
},
} );

Generate Output

$lre->generate_output();

Report Output Information

$path_to_output_file = $lre->get_output_path();

$output_file_basename = $lre->get_output_basename();

$output_row_count = $lre->get_total_rows();

$output_record_count = $lre->get_total_records();

$records_changed = $lre->get_records_changed();

$records_unchanged = $lre->get_records_unchanged();

$records_deleted = $lre->get_records_deleted();

$header_status = $lre->get_header_status();

It is common in many situations for you to receive a flat data file from someone else and have to generate a new file in which each row or record in the incoming file must either (a) be transformed according to some rule before being printing to the new file; or (b) if it meets certain criteria, not output to the new file at all.

List::RewriteElements enables you to write such rules and criteria, generate the file of transformed data records, and get back some basic statistics about the transformation.

List::RewriteElements is useful when the number of records in the incoming file may be large and you do not want to hold the entire list in memory. Similarly, the newly generated records are not held in memory but are immediately printed to STDOUT or to file.

On the other hand, if for some reason you already have an array of records in memory, you can use List::RewriteElements to apply rules and criteria to each element of the array and then print the transformed records (again, without holding the output in memory).