/ 
PostScript-Report-0.13
River stage zero No dependents
/ PostScript::Report

NAME

PostScript::Report - Produce formatted reports in PostScript

VERSION

This document describes version 0.13 of PostScript::Report, released November 30, 2013 as part of PostScript-Report version 0.13.

SYNOPSIS

use PostScript::Report ();

my $rpt = PostScript::Report->build(\%report_description);

# Run the report and save PostScript to a file:
$rpt->run(\%data, \@rows)->output("filename.ps");

# Or, if you want PDF output instead of PostScript:
use PostScript::Convert;
psconvert($rpt->run(\%data, \@rows), "filename.pdf");

$rpt->clear;    # If you want to save this object and run it again

DESCRIPTION

PostScript::Report helps you generate nicely formatted reports using PostScript. You do not need any knowledge of PostScript to use this package (unless you want to create new Component types).

You probably won't create a PostScript::Report object directly using new. Instead, you'll pass a report description to the "build" method, which uses PostScript::Report::Builder to construct the appropriate objects.

All measurements in a report are given in points (PostScript's native measurement unit). There are 72 points in one inch (1 pt is about 0.3528 mm).

If you want to save the report as PDF, you can pass a report object (after calling run) to "psconvert" in PostScript::Convert.

ATTRIBUTES

Report Sections

Each section may be any Component, but is usually a Container. All sections are optional (but printing a report with no sections will produce a blank sheet of paper, so you probably want at least one section).

report_header

This is printed at the top of the first page.

page_header

This is printed at the top of every page (and below the report_header on the first page).

detail

This is printed once for each row of @rows. See "run".

page_footer

This is printed at the end of every page (and above the report_footer on the last page). Also see "first_footer" and "footer_align".

This is printed at the end of the last page. Also see "first_footer" and "footer_align".

Report Formatting

These attributes affect the PostScript::File object, or control the formatting of the report as a whole. All dimensions are in points.

bottom_margin

This is the bottom margin (default 72, or one inch).

detail_background

This is a code reference that is called before the detail section is drawn. It receives two parameters: the row number and the row number on this page (both 0-based). It returns the background color for the detail section, or undef (which means to use the same color as last time).

This may be either page or report, and controls the order of the footers on the last page. The default is page, which puts the page footer above the report footer.

This may be either top, bottom, or split. If it's bottom (the default), the footers are placed at the very bottom of the page, touching the bottom margin. If it's top, then the footers are placed immediately after the last detail row. If it's split, then the first footer is placed using top, and the second footer is placed using bottom. (Do not use split unless you have defined both footers.)

landscape

If set to a true value, the report will be printed in landscape mode. The default is false.

left_margin

This is the left margin (default 72, or one inch).

paper_size

This the paper size (default Letter). See "paper" in PostScript::File.

ps_parameters

This is a hashref of additional parameters to pass to PostScript::File's constructor. These values will override the parameters that PostScript::Report generates itself (but you should reserve this for things that can't be controlled through other PostScript::Report attributes).

right_margin

This is the right margin (default 72, or one inch).

title

This is the report's title, which is used only to set the corresponding PostScript comment in the document. The default is Report.

top_margin

This is the top margin (default 72, or one inch).

Component Formatting

These attributes do not affect the report directly, but are simply inherited by components that don't have an explicit value for them. All dimensions are in points.

align

This is the default text alignment. It may be left, center, or right (default left).

border

This is the default border style. It may be 1 for a solid border (the default), or 0 for no border. In addition, you may specify any combination of the letters T, B, L, and R (meaning top, bottom, left, and right) to have a border only on the specified side(s).

The thickness of the border is controlled by "line_width".

(Note: The string you give will be converted into the canonical representation, which has the letters upper case and in the order TBLR.)

font

This is the default font. It defaults to Helvetica 9.

line_width

This is the default line width (0.5 by default). It's used mainly for component borders. A line width of 0 means "as thin as possible".

padding_bottom

This indicates the distance between the bottom of a component and the baseline of the text inside it (4 by default). If this is too small, then the descenders (on letters like "p" and "y") will be cut off. (The exact minimum necessary depends on the selected font and size.)

padding_side

This indicates the space between the side of a component and the text inside it (3 by default).

row_height

This is the default height of a row on the report (default 15).

Other Attributes

You will probably not need to use these attributes unless you are creating your own components or other advanced tasks.

extra_styles

This is a hash of additional attributes that can be inherited by child Components. You wouldn't normally set this directly, because PostScript::Report::Builder will automatically move any unknown attributes into this hash.

page_count

This contains the number of pages in the report. It's only valid after "run" has been called.

page_number

This contains the number of the page currently being generated. It's only valid while the "run" method is processing.

ps

This is the PostScript::File object containing the report. It's constructed by the "run" method, and can be freed by calling the "clear" method.

ps_functions

This is a hashref of PostScript code blocks that should be added to the PostScript::File object. The key should begin with the package inserting the code. If a package adds more than one such block, the package name should be followed by a hyphen and the block name. Blocks are added in ASCIIbetical order. A component's init method may add an entry here.

METHODS

build

$rpt = PostScript::Report->build(\%description)

This is the usual method for constructing a PostScript::Report. It passes the %description to PostScript::Report::Builder.

If %description does not define report_class, then it is set to the class on which you called build. (This matters only if you have subclassed PostScript::Report.)

run

$rpt->run(\%data, \@rows)

This method runs the report on the specified data. %data is a hash containing values for the report. @rows is an array of arrayrefs of strings. The "detail" section is printed once for each arrayref.

After running the report, you should call "output" to store the results. run returns $rpt, so you can chain the method calls:

$rpt->run(\%data, \@rows)->output($filename);

If you omit either %data or @rows (or pass undef), an empty hash or array will be substituted.

output

$rpt->output($filename [, $dir]) # save to file
$rpt->output()                   # return as string

This method takes the same parameters as "output" in PostScript::File. You can pass a filename (and optional directory name) to store the report in a file. (No extension will be added to $filename, so it should normally end in ".ps".)

If you don't pass a filename, then the PostScript code is returned as a string.

If you want to reuse the report object, you can call clear afterwards to free up memory.

clear

$rpt->clear()

This releases the PostScript::File object created by running the report. You never need to call this method, but it will free up memory if you want to save the report object and run the report again later.

get_font

$font_object = $rpt->get_font($font_name, $font_size)

Because a report needs to know what fonts will be used in it, you must use this method to construct PostScript::Report::Font objects. If the specified font has already been used in this report, the same $font_object will be returned. (Normally, fonts are constructed by PostScript::Report::Builder.)

get_style

$rpt->get_style($attribute)

Child Components call this method to get the inherited value of any non-standard style attribute.

get_value

$field_content = $rpt->get_value($value_source)

When a Component needs to fetch the content it should display, it calls get_value with its RptValue. This can be one of three things:

a non-negative integer

A 0-based column in the current row (normally used only in the detail section). A warning will be issued if the current row does not have that many columns.

a string

An entry in the %data passed to "run". A warning will be issued if the key does not exist in %data.

an object

This returns $value_source->get_value($rpt).

If the result would be undef, the empty string is returned instead. (No warning is issued for this.)

height

$height = $rpt->height;

This returns the height of the report (the paper height minus the margins).

width

$width = $rpt->width;

This returns the width of the report (the paper width minus the margins).

dump

$rpt->dump;

This method (for debugging purposes only) prints a representation of the report to the currently selected filehandle. (Inherited values are not shown.) Note that layout calculations are not done until the report is run, so you will normally see additional height and width values after calling "run".

CONFIGURATION AND ENVIRONMENT

PostScript::Report requires no configuration files or environment variables.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

PostScript::Report does not support characters outside of Windows code page 1252 (aka WinLatin1), which is a superset of the printable characters in ISO-8859-1 (aka Latin1). Unfortunately, supporting Unicode in PostScript is non-trivial.

There is a conflict between versions of MooseX::Types 0.32 and greater with Moose versions before 2.0800. PostScript::Report's type library will trigger that bug. Either upgrade Moose to 2.0800 or greater, or downgrade MooseX::Types to 0.31 or below.

AUTHOR

Christopher J. Madsen <perl AT cjmweb.net>

Please report any bugs or feature requests to <bug-PostScript-Report AT rt.cpan.org> or through the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=PostScript-Report.

You can follow or contribute to PostScript-Report's development at https://github.com/madsen/postscript-report.

ACKNOWLEDGMENTS

I'd like to thank Micro Technology Services, Inc. http://www.mitsi.com, who sponsored development of PostScript-Report, and fREW Schmidt, who recommended me for the job. It wouldn't have happened without them.

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Christopher J. Madsen.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.