NAME
::report::report - Create and manipulate report objects
SYNOPSIS
package require report ?1.0?
::report::report reportName columns ?style style arg...?
::report::defstyle styleName arguments script
::report::rmstyle styleName
::report::stylearguments styleName
::report::stylebody styleName
::report::styles
_________________________________________________________________
DESCRIPTION
This package provides report objects which can be used by
the formatting methods of matrix objects to generate tabu
lar 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.
::report::report reportName columns ?style 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: reportName option ?arg arg ...?
Option and the args determine the exact behavior of
the command. See section REPORT METHODS for more
explanations. If no style is specified the report
will use the builtin style plain as its default
configuration.
::report::defstyle styleName arguments script
Defines the new style styleName. See section STYLES
for more information.
::report::rmstyle 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.
style FOO will result in a runtime error when FOO
is applied to a newly instantiated report.
::report::stylearguments styleName
This introspection command returns the list of
arguments associated with the style styleName.
::report::stylebody styleName
This introspection command returns the script asso
ciated with the style styleName.
::report::styles
This introspection command returns a list contain
ing 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 plain, followed by the first style
defined by the user, and so on.
REGIONS
The three regions are the top caption, data area and bot
tom 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.
LINES
Each of the ten line classes can have a template (see sec
tion below) associated with it 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 separa
tors 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:
top 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.
topdatasep
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.
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.
datasep
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.
botcapsep
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.
botdatasep
This line is used to separate the data rows in the
bottom caption region, if it contains more than one
row and the user enabled its usage.
bottom The bottommost line of a report. Separates the
report from anything which comes after it. The user
can enable the usage of this line at will.
topdata
This line defines the format of data lines in the
top caption region of the report.
data This line defines the format of data lines in the
data region of the report.
botdata
This line defines the format of data lines in the
bottom caption region of the report.
TEMPLATES
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 corre
sponding 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 verti
cal 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
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 repli
cated to be at least as long as the size of their column
and then cut to the exact size.
STYLES
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 con
figure 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 cur
rently executing the style script. The arguments declared
here are available in the script as variables. When call
ing the command of a previously declared style all the
arguments expected by it have to be defined in the call.
REPORT METHODS
The following commands are possible for report objects:
reportName destroy
Destroys the report, including its storage space
and associated command.
reportName templatecode disable|enable
Enables or disables the usage of the template
addressed by the templatecode. Only the codes for
separator lines are allowed here. It is not possi
ble to enable or disable data lines.
Enabling a template causes the report to check all
used templates for inconsistencies in the defini
tion of the vertical lines (See section TEMPLATES).
reportName templatecode enabled
Returns the whether the template addressed by the
templatecode is currently enabled or not.
Returns the template currently associated with the
kind of line addressed by the templatecode. All
known templatecodes are allowed here.
reportName templatecode set templatedata
Sets the template associated with the kind of line
addressed by the templatecode to the new value in
templatedata. See section TEMPLATES for constraints
on the length of templates.
reportName tcaption ?size?
Specifies the size of the top caption region as the
number rows it occupies in the matrix to be format
ted. 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 TEMPLATES).
reportName bcaption 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 specified the com
mand 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 TEMPLATES).
reportName size column ?number|dyn?
Specifies the size of the column in the output. The
value dyn means that the columnwidth returned by
the matrix to be formatted for the specified column
shall be used. The formatting of the column is
"dynamic". If a fixed number is used instead of dyn
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 sizes ?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 associate with the columns.
next with column 1, and so on.
If no size-list is specified the command will
return a list containing the currently set sizes
instead.
reportName pad column ?left|right|both ?padstring??
This method allows the user to specify padding on
the left, right or both sides of a column. If the
padstring is not specified it defaults to a single
space character. Note: An alternative way of speci
fying the padding is to use vertical separator
strings longer than one character in the templates
(See section TEMPLATES).
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 justify column ?left|right|center?
Declares how the cell values for a column are
filled into the report given the specified size of
a column in the report.
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.
reportName printmatrix 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
reportName printmatrix2channel matrix chan
Formats the matrix according to the configuration
of the report and writes the result into the chan
nel 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 columns
Returns the number of columns in the report.
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".
EXAMPLES
Our examples define some generally useful report styles.
A simple table with lines surrounding all information and
vertical separators, but without internal horizontal sepa
rators.
::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
topcapsep set [top get]
topcapsep enable
tcaption $n
}
KEYWORDS
matrix, report, table
Man(1) output converted with
man2html