report(n) Matrix reports report(n)
NAME
report - Create and manipulate report objects
SYNOPSIS
package require TTccll 88..22
package require rreeppoorrtt ??00..33..11??
::::rreeppoorrtt::::rreeppoorrtt reportName columns ?ssttyyllee style arg...?
rreeppoorrttNNaammee option ?arg arg ...?
::::rreeppoorrtt::::ddeeffssttyyllee styleName arguments script
::::rreeppoorrtt::::rrmmssttyyllee styleName
::::rreeppoorrtt::::ssttyylleeaarrgguummeennttss styleName
::::rreeppoorrtt::::ssttyylleebbooddyy styleName
::::rreeppoorrtt::::ssttyylleess
reportName ddeessttrrooyy
reportName templatecode ddiissaabbllee|eennaabbllee
reportName templatecode eennaabblleedd
reportName templatecode ggeett
reportName templatecode sseett templatedata
reportName ttccaappttiioonn ?size?
reportName bbccaappttiioonn size
reportName ssiizzee column ?number|ddyynn?
reportName ssiizzeess ?size-list?
reportName ppaadd column ?lleefftt|rriigghhtt|bbootthh ?padstring??
reportName jjuussttiiffyy column ?lleefftt|rriigghhtt|cceenntteerr?
reportName pprriinnttmmaattrriixx matrix
reportName pprriinnttmmaattrriixx22cchhaannnneell matrix chan
reportName ccoolluummnnss
DESCRIPTION
This package provides report objects which can be used by the format-
ting 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 RREEGGIIOONNSS and ten classes of lines (various sepa-
rator- and data-lines). See the following section for more detailed
explanations.
::::rreeppoorrtt::::rreeppoorrtt reportName columns ?ssttyyllee style arg...?
Creates a new report object for a report having columns columns
with an associated global Tcl command whose name is reportName.
This command may be used to invoke various configuration opera-
tions on the report. It has the following general form:
rreeppoorrttNNaammee option ?arg arg ...?
Option and the args determine the exact behavior of the
command. See section RREEPPOORRTT MMEETTHHOODDSS for more explana-
tions. If no ssttyyllee is specified the report will use the
builtin style ppllaaiinn as its default configuration.
::::rreeppoorrtt::::ddeeffssttyyllee styleName arguments script
Defines the new style styleName. See section SSTTYYLLEESS for more
information.
::::rreeppoorrtt::::rrmmssttyyllee styleName
Deletes the style styleName. Trying to delete an unknown or
builtin style will result in an error. Beware, this command will
not check that there are no other styles depending on the
deleted one. Deleting a style which is still used by another
style FOO will result in a runtime error when FOO is applied to
a newly instantiated report.
::::rreeppoorrtt::::ssttyylleeaarrgguummeennttss styleName
This introspection command returns the list of arguments associ-
ated with the style styleName.
::::rreeppoorrtt::::ssttyylleebbooddyy styleName
This introspection command returns the script associated with
the style styleName.
::::rreeppoorrtt::::ssttyylleess
This introspection command returns a list containing the names
of all styles known to the package at the time of the call. The
order of the names in the list reflects the order in which the
styles were created. In other words, the first item is the pre-
defined style ppllaaiinn, followed by the first style defined by the
user, and so on.
RREEGGIIOONNSS
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.
LLIINNEESS
TTEEMMPPLLAATTEESS 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:
ttoopp The topmost line of a report. Separates the report from anything
which came before it. The user can enable the usage of this line
at will.
ttooppddaattaasseepp
This line is used to separate the data rows in the top caption
region, if it contains more than one row and the user enabled
its usage.
ttooppccaappsseepp
This line is used to separate the top caption and data regions,
if the top caption is not empty and the user enabled its usage.
ddaattaasseepp
This line is used to separate the data rows in the data region,
if it contains more than one row and the user enabled its usage.
bboottccaappsseepp
This line is used to separate the data and bottom caption
regions, if the bottom caption is not empty and the user enabled
its usage.
bboottddaattaasseepp
This line is used to separate the data rows in the bottom cap-
tion region, if it contains more than one row and the user
enabled its usage.
bboottttoomm The bottommost line of a report. Separates the report from any-
thing which comes after it. The user can enable the usage of
this line at will.
ttooppddaattaa
This line defines the format of data lines in the top caption
region of the report.
ddaattaa This line defines the format of data lines in the data region of
the report.
bboottddaattaa
This line defines the format of data lines in the bottom caption
region of the report.
TTEEMMPPLLAATTEESS
Each template is a list of strings used to format the line it is asso-
ciated with. For a report containing nn columns a template for a data
line has to contain "nn+1" items and a template for a separator line
"2*nn+1" items.
The items in a data template specify the strings used to separate the
column information. Together with the corresponding items in the sepa-
rator 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 kk ("1",...,"nn-2") separates
the information in the columns "kk-1" and "kk".
The items in a separator template having an even-numbered index
("0","2",...) specify the column separators. The item at index "2*kk"
("0","2",...,"2*nn") corresponds to the items at index "kk" 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*kk+1" ("1","3",...,"2*nn+1")
corresponds to column "kk". 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.
SSTTYYLLEESS
Styles are a way for the user of this package to define common configu-
rations 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 configura-
tion.
The command to define styles is ::::rreeppoorrtt::::ddeeffssttyyllee. Its last argument
is the tcl ssccrriipptt 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 aarrgguummeennttss
declared here are available in the ssccrriipptt as variables. When calling
the command of a previously declared style all the arguments expected
by it have to be defined in the call.
RREEPPOORRTT MMEETTHHOODDSS
The following commands are possible for report objects:
reportName ddeessttrrooyy
Destroys the report, including its storage space and associated
command.
reportName templatecode ddiissaabbllee|eennaabbllee
Enables or disables the usage of the template addressed by the
templatecode. Only the codes for separator lines are allowed
here. It is not possible to enable or disable data lines.
Enabling a template causes the report to check all used tem-
plates for inconsistencies in the definition of the vertical
lines (See section TTEEMMPPLLAATTEESS).
reportName templatecode eennaabblleedd
Returns the whether the template addressed by the templatecode
is currently enabled or not.
reportName templatecode ggeett
Returns the template currently associated with the kind of line
addressed by the templatecode. All known templatecodes are
allowed here.
reportName templatecode sseett templatedata
Sets the template associated with the kind of line addressed by
the templatecode to the new value in templatedata. See section
TTEEMMPPLLAATTEESS for constraints on the length of templates.
reportName ttccaappttiioonn ?size?
Specifies the size of the top caption region as the number rows
it occupies in the matrix to be formatted. Only numbers greater
than or equal to zero are allowed. If no size is specified the
command will return the current size instead.
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 TTEEMMPPLLAATTEESS).
reportName bbccaappttiioonn size
Specifies the size of the bottom caption region as the number
rows it occupies in the matrix to be formatted. Only numbers
greater than or equal to zero are allowed. If no size is speci-
fied the command will return the current size instead.
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 TTEEMMPPLLAATTEESS).
reportName ssiizzee column ?number|ddyynn?
Specifies the size of the column in the output. The value ddyynn
means that the columnwidth returned by the matrix to be format-
ted for the specified column shall be used. The formatting of
the column is dynamic. If a fixed number is used instead of ddyynn
it means that the column has a width of that many characters
(padding excluded). Only numbers greater than zero are allowed
here.
If no size specification is given the command will return the
current size of the column instead.
reportName ssiizzeess ?size-list?
This method allows the user to specify the sizes of all columns
in one call. Its argument is a list containing the sizes to as-
sociate with the columns. The first item is associated with col-
umn 0, the next with column 1, and so on.
If no size-list is specified the command will return a list con-
taining the currently set sizes instead.
reportName ppaadd column ?lleefftt|rriigghhtt|bbootthh ?padstring??
This method allows the user to specify padding on the left,
right or both sides of a column. If the padstring is not speci-
fied it defaults to a single space character. Note: An alterna-
tive way of specifying the padding is to use vertical separator
strings longer than one character in the templates (See section
TTEEMMPPLLAATTEESS).
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.
reportName jjuussttiiffyy column ?lleefftt|rriigghhtt|cceenntteerr?
Declares how the cell values for a column are filled into the
report given the specified size of a column in the report.
For lleefftt and rriigghhtt 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 cceenntteerr 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 lleefftt justification that the
tail (i.e. the rriigghhtt part) of the value is made visible in the
output. For cceenntteerr 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.
reportName pprriinnttmmaattrriixx matrix
Formats the matrix according to the configuration of the report
and returns the resulting string. The matrix has to have the
same number of columns as the report. The matrix also has to
have enough rows so that the top and bottom caption regions do
not overlap. The data region is allowed to be empty.
reportName pprriinnttmmaattrriixx22cchhaannnneell matrix chan
Formats the matrix according to the configuration of the report
and writes the result into the channel chan. The matrix has to
have the same number of columns as the report. The matrix also
has to have enough rows so that the top and bottom caption
regions do not overlap. The data region is allowed to be empty.
reportName ccoolluummnnss
Returns the number of columns in the report.
The methods ssiizzee, ppaadd and jjuussttiiffyy 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 lliinnddeexx command. The allowed range for indices is
"0,...,[rreeppoorrttNNaammee columns]-1".
EEXXAAMMPPLLEESS
Our examples define some generally useful report styles.
A simple table with lines surrounding all information and vertical sep-
arators, but without internal horizontal separators.
::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 ssiimmpplleettaabbllee, 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 con-
tains 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
KKEEYYWWOORRDDSS
matrix, report, table
COPYRIGHT Copyright (c) 2002 Andreas Kupries
report 0.3.1 report(n)