Reporter v1.0: PERL-ish Reporter class

David C.Lambert <dcl@.panix.com>
September, 1997

DESCRIPTION:

This module defines the Reporter class, a report formatter that uses
PERL-ish formats as specifiers for headers, footers and records.

If you have PERL installed, 'man perlform' will give you instructions
that are pretty close to correct - just remove the $ signs from your
variable names, and send the multi-line formats to the Reporter object
as strings.

Otherwise [borrowing liberally from the perlform man page]:
Formats are multi-line strings that consist of a sequence of lines
that may be of two types:

1.  A "picture" line giving the format for one output line.

2.  An argument line supplying values to plug into the
    previous picture line.

Picture lines are printed exactly as they look, except for certain
fields that substitute values into the line.  Each field in a picture
line starts with either '@' (at) or '^' (caret).

The at field is the normal kind of field; the other kind, caret
fields, are used to do rudimentary multi-line text block filling.  The
length of the field is supplied by padding out the field with multiple
"<", ">", or "|" characters to specify, respectively, left
justification, right justification, or centering.  If the variable
would exceed the width specified, it is truncated.

As an alternate form of right justification, you may also use "#"
characters (with an optional ".") to specify a numeric field.  This
way you can line up the decimal points.  Finally, the special field
"@*" can be used for printing multi-line, non-truncated values; it
should appear by itself on a line.

The values are specified on the following line in the same order as
the picture fields.  The expressions providing the values should be
separated by commas.

The write() method of the Reporter class takes a dictionary that it
uses as a namespace for an eval() call when it evaluates the
expressions for values in the formats.  This is typically locals(),
globals(), or a union of the two.

KNOWN BUGS:

[These are really differences from the PERL behavior, more
 than bugs, but...]

Left-justified fields are padded with spaces to the length of the
field on the right.  PERL doesn't seem to do this (at least, not at
the end of a line).

Comment lines (lines with initial hash marks ['#']) within formats
are not supported, and neither are tildes ['~'] or ellipses ['...'].

Newlines in fields do not cause the field to be truncated - the
field is passed unchanged to the output.

Finally, while carets ['^'] are supported at the beginning of '#'
fields, they have no special meaning.

CREDITS:

Thanks to Hadar Pedhazur at UBS Securities for whom this class was
written, and who graciously permitted its release.

COPYRIGHT:

This code is in the public domain.  Do with it as you wish.

WARRANTY:

THE CODE IS PROVIDED "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 CODE IS
WITH YOU.  SHOULD THE CODE PROVE DEFECTIVE, YOU ASSUME THE COST OF
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

IN NO EVENT WILL THE AUTHOR, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE CODE AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE CODE
(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 CODE TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER
OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.