view release on metacpan or  search on metacpan

lib/List/RewriteElements.pm  view on Meta::CPAN

    $lre->generate_output();

=head2 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();

=head1 DESCRIPTION

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 C<print>ed 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).

=head1 SUBROUTINES

=head2 C<new()>

B<Purpose:>  List::RewriteElements constructor.

B<Arguments:>  Reference to a hash holding the following keys:

=over 4

=item * C<file> or C<list>

The hash must hold either a C<file> element or a C<list> element -- but not
both!  The value for the C<file> key must be an absolute path to an input
file.  The value for C<list> must be a reference to an array in memory.

=item * C<body_rule>

The hash must have a C<body_rule> element whose value is a reference to a
subroutine providing a formula for the transformation of an individual record
in the incoming file to a record in the outgoing file.  The first argument
passed to this subroutine must be the record from the incoming file.  The
return value from this subroutine should be a string immediately ready for
printing to the output file (though the string should not end in a newline, as
printing will be handled by C<generate_output()>).

=item * C<body_suppress>

Optionally, you may provide a C<body_suppress> element whose value is a
reference to a subroutine providing a criterion according to which an
individual record in the incoming file should be output to the outgoing file
or not output, I<i.e.>, omitted from the output entirely.  The first argument 
to this subroutine should be the record from the incoming file.  The 
subroutine should, at least implicitly, return a true value when the record 
I<should> be output.  The subroutine should simply C<return>, <i.e.>, 
return an implicit C<undef>, when the record should be omitted from the 
outgoing file.

=item * C<header_rule>

Frequently the first row in a flat data file is a header row containing, say,
the names of the columns in a data table, joined by a delimiter.  Because the
header row is different from all subsequent rows, you may optionally provide a
C<header_rule> element whose value is a reference to a
subroutine providing a formula for the transformation of the header row 
in the incoming file to the header in the outgoing file.  The first argument
passed to this subroutine must be the header row from the incoming file.  The
return value from this subroutine should be a string immediately ready for
printing to the output file (though the string should not end in a newline, as
printing will be handled by C<generate_output()>).

=item * C<header_suppress>

Optionally, if you have provided a C<header_rule> element, you may provide 
a C<header_suppress> element whose value is a
reference to a subroutine providing a criterion according to which an
the header row from the incoming file should be output to the outgoing file
or not output, I<i.e.>, omitted from the output entirely.  The first argument 
to this subroutine should be the header from the incoming file.  The 
subroutine should, at least implicitly, return a true value when the header 
I<should> be output.  The subroutine should simply C<return>, <i.e.>, 
return an implicit C<undef>, when the header should be omitted from the 
outgoing file.

=item * C<output_file> or C<output_suffix>

It is recommended that you supply either an C<output_file> or an
C<output_suffix> element to the constructor; otherwise, the new list generated
by application of the rules and criteria will simply C<print> to C<STDOUT>.
The value of an C<output_file> element should be a full path to the newly
created file.  If you wish to create a new file name without specifying a full
path but simply by tacking on a suffix to the name of the incoming file,
provide an C<output_suffix> element and the outgoing file will be created in
the directory which is the I<current working directory> as of the point where
C<generate_output()> is called.  An C<output_suffix> element will
be ignored if an C<output_file> element is provided.

=item * Note 1

If neither a C<header_rule> or C<header_suppress> element is provide to the
constructor, List::RewriteElements will treat the first row of the incoming
file the same as any other row, C<i.e.>, it will apply the C<body_rule>
transformation formula.

=item * Note 2

A C<body_suppress> or C<header_suppress> criterion, if present, will be 
logically applied I<before> any C<body_rule> or C<header_rule> formula.  We
don't apply the formula to transform a record if the record should not be
output at all.

=item * Note 3

=back

B<Return Value:>  List::RewriteElements object.

=head2 C<generate_output()>

B<Purpose:>  Generates the output specified by arguments to C<new()>, 
I<i.e.>, creates an output file or C<print>s to C<STDOUT> with records 
transformed as per those arguments.

B<Arguments:>  None. 

B<Return Value:>  Returns true value upon success.  In case of failure it will
C<croak> with some error message.

=head2 C<get_output_path()>

B<Purpose:>  Get the full path to the newly created output file. 

B<Arguments:>  None. 

B<Return Value:>  String holding path to newly created output file. 

B<Comment:>  Since use of the C<output_suffix> attribute means that the full
path to the output file will not be known until C<generate_output()> has been
called, C<get_output_path()> will only give a meaningful result once
C<generate_output()> has been called.  Otherwise, it will default to an empty
string.

=head2 C<get_output_basename()>

B<Purpose:>  Get only the basename of the newly created output file.

B<Arguments:>  None.

B<Return Value:>  String holding basename of newly created output file.

B<Comment:>  Since use of the C<output_suffix> attribute means that the full
path to the output file will not be known until C<generate_output()> has been
called, C<get_output_basename()> will only give a meaningful result once
C<generate_output()> has been called.  Otherwise, it will default to an empty
string.

=head2 C<get_total_rows()>

B<Purpose:>  Get the total number of rows in the newly created output file.
This will include any header row.

B<Arguments:>  None.

B<Return Value:>  Nonnegative integer.

=head2 C<get_total_records()>

B<Purpose:>  Get the total number of data records in the newly created output
file.  If a header row is present in that file, C<get_total_records()> will