The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Data-UNLreport-1.07
River stage zero No dependents
++
/ Data::UNLreport

NAME

Data::UNLreport

ABSTRACT

Formats column-oriented data into uniform column sizes

SYNOPSIS

The UNLreport provides the following methods:

  use Data::UNLreport;
  my $report = Data::UNLreport->new ([in_delim  => '|'],
                                     [out_delim => '|'],
                                     [out_file  => "<file path>"]
                                     [mode      => ">" | ">>" ]
                                    );
  The defaults will be familiar enough to the Informix user:

  • in_delim defaults to the vertical bar ("pipe").

  • out_delim defaults the same way.

  • Output file defailts to STDOUT, which is ill advised if parsing multiple files.

  • Mode defaults to > - to overwrite the target file.

  $report->in_delim([char]);    # Sets/returns input column separator

  $report->out_delim([char]);   # Sets/returns output column separator

  $report->out_file([file_path, [mode]] );  # Sets/returns output file
                                # Also sets the output mode - Overwrite
                                # or append

  $report->fdesc();             # Returns reference to file descriptor

  $report->has_end_delim(flag); # 1 for delimiter at end of each line,
                                # 0 to omit end-of-line delimiter
                                # Default: 0
  $lines_so_far = $report + $a_line; # Splits and adds this line to the
                                     # UNLreport object.
  $lines_so_far = $report + @values;# Adds this array - a line already
                                     # split - to the UNLreport object.
                                     # NOTE: Pass an array REFERENCE
                                     # Returns line tally so far.
  $report->print();             # Sends the data to the output file,
                                # with columns uniformly sized

DESCRIPTION

A detailed description of the module and methods follows.

All parameters to new() are optional. They can be completely omitted or set later.

The default value for in_delim is the vertical bar (AKA pipe), the standard delimiter for files created with the Informix-SQL "unload" command. You may substitute any other character eg. comma, colon, period etc. If you wish to specify a blank separator, use the lower-case letter 'b' as your parameter. Other than that b, we obviously do not recommend using an alphanumeric character as a field delimiter. There is [currently] no method for specifying a pattern.

The default value for out_delim is copied from in_delim, whether using the default in_delim or set in the new() method. Or you can set it using the out_delim() method. As with in_delim, do not use an alphanumeric delimiter if you want your output to be readable. Also, the letter b will be interpreted as a space (blank)

For methods in_delim(), out_delim(), and out_file(), supplying a parameter sets the indicated attribute; omitting it returns the value (Ye Olde accessor-mutator) of that attribute. Thus, you can omit the delimter parametes from the new() method and set them later.

Note that you can dynamically change the input column separator. If your data input is from different sources that use different column separators e.g. one comma-separated file and one colon-separated file, you can switch how the UNLreport object splits the line to follow the change.

On the other hand, the assumption is that all output is to be delimited the same way. Similarly, all output [from one UNLreport object] is targeted to the same output file. The UNLreport object does not really care about the output column separator or the output file until it is ready to generate the output. Hence, it is permissible but futile to call out_delim() (or out_file()) to set these attributes more than once; only the final call before output will have the intended effect, overwriting the work of any previous call.

The default output file is, of course, STDOUT. You can specify a path here. The default mode is '>' - to write the output as a new file, overwriting any existing file by name name. If that is not your intention, use mode => ">>" to append to an existing file.

You send a line to the report by using the overloaded + operator. You may send it a line with the delimiters intact - as from an UNLOAD command. Or you can send it a REFERENCE to an array, as you would have if you are doing SQL-FETCH commmands and want a neat report on the data.

EXPORT

No functions or variables are exported from this module at this time.

HISTORY

Original version; created by h2xs release 1.23 with options: -XAC -n UNLreport

BACKGROUND

This module is the next stage of a script that started life as a shell script, beautify-unl.sh. Its purpose was to straighten out the zig-zag columns produces by the Informix SQL command UNLOAD. Hence, the default columns separator is the | character, both for splitting the input columns as well as formatting the output lines. The first Perl attempt was UNLreport.pm, which works was not CPAN-worthy.

SEE ALSO

The original shell script, which still works very well, can be found at this URL: http://www.iiug.org/software/archive/beautify-unl.shar

You may need to be a member of the IIUG to download this.

AUTHOR

Jacob Salomon, jakesalomon@yahoo.com

COPYRIGHT AND LICENSE

Copyright (C) 2011 by Jacob Salomon

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.