PostScript::Report - Produce formatted reports in PostScript
This document describes version 0.10 of PostScript::Report, released April 4, 2012 as part of PostScript-Report version 0.10.
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
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.
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).
This is printed at the top of the first page.
This is printed at the top of every page (and below the
report_header on the first page).
This is printed once for each row of
@rows. See "run".
These attributes affect the PostScript::File object, or control the formatting of the report as a whole. All dimensions are in points.
This is the bottom margin (default 72, or one inch).
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
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
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.)
If set to a true value, the report will be printed in landscape mode. The default is false.
This is the left margin (default 72, or one inch).
This the paper size (default
Letter). See "paper" in PostScript::File.
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).
This is the right margin (default 72, or one inch).
This is the report's title, which is used only to set the corresponding PostScript comment in the document. The default is
This is the top margin (default 72, or one inch).
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.
This is the default text alignment. It may be
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.)
This is the default font. It defaults to Helvetica 9.
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".
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.)
This indicates the space between the side of a component and the text inside it (3 by default).
This is the default height of a row on the report (default 15).
You will probably not need to use these attributes unless you are creating your own components or other advanced tasks.
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.
This contains the number of pages in the report. It's only valid after "run" has been called.
This contains the number of the page currently being generated. It's only valid while the "run" method is processing.
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.
$rpt = PostScript::Report->build(\%description)
This is the usual method for constructing a PostScript::Report. It passes the
%description to PostScript::Report::Builder.
%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.)
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.
$rpt, so you can chain the method calls:
If you omit either
@rows (or pass
undef), an empty hash or array will be substituted.
$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.
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.
$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.)
Child Components call this method to get the inherited value of any non-standard style attribute.
$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 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.
An entry in the
%data passed to "run". A warning will be issued if the key does not exist in
If the result would be
undef, the empty string is returned instead. (No warning is issued for this.)
$height = $rpt->height;
This returns the height of the report (the paper height minus the margins).
$width = $rpt->width;
This returns the width of the report (the paper width minus the margins).
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
width values after calling "run".
PostScript::Report requires no configuration files or environment variables.
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.
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 http://github.com/madsen/postscript-report.
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.
This software is copyright (c) 2012 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.
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.