view release on metacpan or  search on metacpan

lib/Data/Presenter.pm  view on Meta::CPAN

=back

The complete call to C<writeformat_plus_header> looks like this:

    @columns_selected = ('lastname', 'firstname', 'datebirth', 'cno');
    $sorted_data = $dp1->sort_by_column(\@columns_selected);

    $dp1->writeformat_plus_header(
        sorted      => $sorted_data,
        columns     => \@columns_selected,
        file        => $outputfile,
        title       => $title,
    );

and will produce a header and formatted data like this:

    Hospital Census Report

                                          Date       Date of
    Unit   Ward Last Name      First Name of Birth   Admission  C No.
    ------------------------------------------------------------------
    LAVER  0105 VASQUEZ        JORGE      1956-01-13 1986-01-17 456787
    LAVER  0107 VASQUEZ        LEONARDO   1970-15-23 1990-08-23 456788
    SAMSON 0209 VASQUEZ        JOAQUIN    1970-03-25 1990-11-14 456789

The wording of the column headers is governed by choices made by the
administrator within the configuration file (here, within
F<fields.census.data>).  If a particular word in a column header is too long
to fit in the space allocated, it will be truncated.

=head3 C<writeformat_with_reprocessing()>

C<writeformat_with_reprocessing()> is an
advanced application of Data::Presenter and the reader may wish to skip this
section until other parts of the module have been mastered.

C<writeformat_with_reprocessing()> permits a sophisticated administrator to
activate ''last minute'' substitutions in the strings printed out from the
format accumulator variable C<$^A>.  Suppose, for example, that a school
administrator faced the problem of scheduling classes in different classrooms
and in various time slots.  Suppose further that, for ease of programming or
data entry, the time slots were identified by chronologically sequential
numbers and that instructors were identified by a unique ID built up from
their first and last names.  Applying an ordinary C<writeformat()> to such
data might show output like this

    11 Arithmetic                   Jones        4044 4044_11
    11 Language Studies             WilsonT      4054 4054_11
    12 Bible Study                  Eliade       4068 4068_12
    12 Introduction to Computers    Knuth        4086 4086_12
    13 Psychology                   Adler        4077 4077_13
    13 Social Science               JonesT       4044 4044_13
    51 World History                Wells        4052 4052_51
    51 Music Appreciation           WilsonW      4044 4044_51

where C<11> mapped to 'Monday, 9:00 am', C<12> to 'Monday, 10:00 am', C<51>
to 'Friday, 9:00 am' and so forth and where the fields underlying this output
were 'timeslot', 'classname', 'instructor', 'room' and 'sessionID'.  While
this presentation is useful, a client might wish to have the time slots and
instructor IDs decoded for more readable output:

    Monday, 9:00     Arithmetic                 E Jones        4044 4044_11
    Monday, 9:00     Language Studies           T Wilson       4054 4054_11
    Monday, 10:00    Bible Study                M Eliade       4068 4068_12
    Monday, 10:00    Introduction to Computers  D Knuth        4086 4086_12
    Monday, 11:00    Psychology                 A Adler        4077 4077_13
    Monday, 11:00    Social Science             T Jones        4044 4044_13
    Friday, 9:00     World History              H Wells        4052 4052_51
    Friday, 9:00     Music Appreciation         W Wilson       4044 4044_51

Time slots coded with chronologically sequential numbers can be ordered to
sort numerically in the C<%parameters> established in the
F<fields.[package1].data> file corresponding to a particular
Data::Presenter::[package1].  Their human-language equivalents, however, will
I<not> sort properly, as, for example, 'Friday' comes before 'Monday' in an
alphabetical or ASCII-betical sort.  Clearly, it would be desirable to
establish the sorting order by relying on the chronologically sequential time
slots and yet have the printed output reflect more human-readable days of the
week and times.  Analogously, for the instructor we might wish to display the
first initial and last name in our printed output rather than his/her ID
code.

The order in which data records appear in output is determined by
C<sort_by_column()> I<before> C<writeformat()> is called.  How can we preserve
this order in the final output?

Answer:  After we have stored a given formed line in C<$^A>, we I<reprocess>
that line by calling an internal subroutine defined in the invoking class,
C<Data::Presenter::[package1]::_reprocessor()>, which tells Perl to splice out
certain portions of the formed line and substitute more human-readable copy.
The information needed to make C<_reprocessor()> work comes from two places.

First, from a hash passed by reference as an argument to
C<writeformat_with_reprocessing()>.  C<writeformat_with_reprocessing()> takes
a list of four key-value pairs, the first three of which are the same as those
passed to C<writeformat()>.  The fourth key-value pair to
C<writeformat_with_reprocessing()> is a reference to a hash whose keys are
the names of the fields in the data records where we wish to make
substitutions and whose corresponding values are the number of characters
the field will be allocated I<after> substitution.  The call to
C<writeformat_with_reprocessing()> would therefore look like this:

    %reprocessing_info = (
        timeslot    => 17,
        instructor  => 15,
    );

    $dp1->writeformat_with_reprocessing(
        sorted      => $sorted_data,
        columns     => \@columns_selected,
        file        => $outputfile,
        reprocess   => \%reprocessing_info,
    );

Second, C<writeformat_with_reprocessing()> takes advantage of the fact that
Data::Presenter's package global hash C<%reserved> contains four keys --
C<fields>, C<parameters>, C<index> and C<options> -- only the first
three of which are used in Data::Presenter's constructor or sorting methods.
Early in the development of Data::Presenter the keyword C<options> was
deliberately left unused so as to be available for future use.