report - Create and manipulate report objects
SYNOPSIS
package require Tcl 8.2
package require report ?0.3?
|
This package provides report objects which can be used by the formatting methods of matrix objects to generate tabular reports of the matrix in various forms. The report objects defined here break each report down into three REGIONS and ten classes of lines (various separator- and data-lines). See the following section for more detailed explanations.
The three regions are the top caption,
data area and bottom caption. These are,
roughly speaking, the title, the values to report and a title at the
bottom. The size of the caption regions can be specified by the user
as the number of rows they occupy in the matrix to format. The size of
the data area is specified implicitly.
TEMPLATES are associated with each of the ten line classes,
defining the formatting for this kind of line. The user is able to
enable and disable the separator lines at will, but not the data
lines. Their usage is solely determined by the number of rows
contained in the three regions. Data lines and all enabled separators
must have a template associated with them.
Note that the data-lines in a report and the rows in the matrix the
report was generated from are not in a 1:1 relationship if
any row in the matrix has a height greater than one.
The different kinds of lines and the codes used by the report methods
to address them are:
Each template is a list of strings used to format the line it is
associated with. For a report containing n columns a template
for a data line has to contain "n+1" items and a template for a
separator line "2*n+1" items.
The items in a data template specify the strings used to separate the
column information. Together with the corresponding items in the
separator templates they form the vertical lines in the report.
Note that the corresponding items in all defined templates
have to be of equal length. This will be checked by the report
object. The first item defines the leftmost vertical line and the last
item defines the rightmost vertical line. The item at index k
("1",...,"n-2") separates the information in the columns
"k-1" and "k".
The items in a separator template having an even-numbered index
("0","2",...) specify the column separators. The item at index
"2*k" ("0","2",...,"2*n") corresponds to the items at
index "k" in the data templates.
The items in a separator template having an odd-numbered index
("1","3",...) specify the strings used to form the horizontal lines in
the separator lines. The item at index "2*k+1"
("1","3",...,"2*n+1") corresponds to column "k". When
generating the horizontal lines the items are replicated to be at
least as long as the size of their column and then cut to the exact
size.
Styles are a way for the user of this package to define common
configurations for report objects and then use them later during the
actual instantiation of report objects. They are defined as tcl
scripts which when executed configure the report object into the
requested configuration.
The command to define styles is ::report::defstyle. Its last
argument is the tcl script performing the actual
reconfiguration of the report object to obtain the requested style.
In this script the names of all previously defined styles are
available as commands, as are all commands found in a safe interpreter
and the configuration methods of report objects. The latter implicitly
operate on the object currently executing the style script. The
arguments declared here are available in the script as
variables. When calling the command of a previously declared style all
the arguments expected by it have to be defined in the call.
The following commands are possible for report objects:
The methods size, pad and justify all take
a column index as their first argument. This index is allowed to use
all the forms of an index as accepted by the lindex command. The
allowed range for indices is
"0,...,[reportName columns]-1".
Our examples define some generally useful report styles.
A simple table with lines surrounding all information and vertical
separators, but without internal horizontal separators.
LINES
TEMPLATES
STYLES
REPORT METHODS
Enabling a template causes the report to check all used templates for
inconsistencies in the definition of the vertical lines (See section
TEMPLATES).
Setting the size of the top caption to a value greater than zero
enables the corresponding data template and causes the report to check
all used templates for inconsistencies in the definition of the
vertical lines (See section TEMPLATES).
Setting the size of the bottom caption to a value greater than zero
enables the corresponding data template and causes the report to check
all used templates for inconsistencies in the definition of the
vertical lines (See section TEMPLATES).
If no size specification is given the command will return the current
size of the column instead.
If no size-list is specified the command will return a list
containing the currently set sizes instead.
If no pad specification is given at all the command will return the
current state of padding for the column instead. This will be a list
containing two elements, the first element the left padding, the
second describing the right padding.
For left and right justification a cell value
shorter than the width of the column is bound with its named edge to
the same edge of the column. The other side is filled with spaces. In
the case of center the spaces are placed to both sides of the
value and the left number of spaces is at most one higher than the
right number of spaces.
For a value longer than the width of the column the value is cut at
the named edge. This means for left justification that the
tail (i.e. the right part) of the value is made
visible in the output. For center the value is cut at both
sides to fit into the column and the number of characters cut at the
left side of the value is at most one less than the number of
characters cut from the right side.
If no justification was specified the command will return the current
justification for the column instead.
EXAMPLES
::report::defstyle simpletable {} { data set [split "[string repeat "| " [columns]]|"] top set [split "[string repeat "+ - " [columns]]+"] bottom set [top get] top enable bottom enable } |
An extension of a simpletable, see above, with a title area.
::report::defstyle captionedtable {{n 1}} { simpletable topdata set [data get] topcapsep set [top get] topcapsep enable tcaption $n } |
Given the definitions above now an example which actually formats a matrix into a tabular report. It assumes that the matrix actually contains useful data.
% ::struct::matrix m % # ... fill m with data, assume 5 columns % ::report::report r 5 style captionedtable 1 % r printmatrix m +---+-------------------+-------+-------+--------+ |000|VERSIONS: |2:8.4a3|1:8.4a3|1:8.4a3%| +---+-------------------+-------+-------+--------+ |001|CATCH return ok |7 |13 |53.85 | |002|CATCH return error |68 |91 |74.73 | |003|CATCH no catch used|7 |14 |50.00 | |004|IF if true numeric |12 |33 |36.36 | |005|IF elseif |15 |47 |31.91 | | |true numeric | | | | +---+-------------------+-------+-------+--------+ % % # alternate way of doing the above % m format 2string r |