NAME¶
report - Create and manipulate report objects
SYNOPSIS¶
package require
Tcl 8.2
package require
report ?0.3.1?
::report::report reportName columns ?
style style
arg...?
reportName option ?
arg arg ...?
::report::defstyle styleName arguments script
::report::rmstyle styleName
::report::stylearguments styleName
::report::stylebody styleName
::report::styles
reportName destroy
reportName templatecode disable|
enable
reportName templatecode enabled
reportName templatecode get
reportName templatecode set templatedata
reportName tcaption ?
size?
reportName bcaption size
reportName size column ?
number|
dyn?
reportName sizes ?
size-list?
reportName pad column ?
left|
right|
both
?
padstring??
reportName justify column
?
left|
right|
center?
reportName printmatrix matrix
reportName printmatrix2channel matrix chan
reportName columns
DESCRIPTION¶
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.
- ::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 operations 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. 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.
- ::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 associated
with the style styleName.
- ::report::styles
- 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 predefined 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
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.
LINES¶
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:
- 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.
- topcapsep
- 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 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¶
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.
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 possible to enable or disable data lines.
Enabling a template causes the report to check all used templates for
inconsistencies in the definition of the vertical lines (See section
TEMPLATES).
- reportName templatecode enabled
- Returns the whether the template addressed by the
templatecode is currently enabled or not.
- reportName templatecode get
- 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 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 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 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 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. The first item is associated with column 0,
the 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 specifying 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 overlap. The data
region is allowed to be empty.
- reportName printmatrix2channel 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 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 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
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
BUGS, IDEAS, FEEDBACK¶
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category
report of the
Tcllib SF Trackers [
http://sourceforge.net/tracker/?group_id=12883].
Please also report any ideas for enhancements you may have for either package
and/or documentation.
KEYWORDS¶
matrix, report, table
CATEGORY¶
Data structures
COPYRIGHT¶
Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net>