|
ActiveTcl User Guide
|
|
|
[ Main table Of Contents | Tcllib Table Of Contents | Tcllib Index ]
report(n) 0.3.1 "Matrix reports"
report - Create and manipulate report objects
TABLE OF
CONTENTS
SYNOPSIS
DESCRIPTION
REGIONS
LINES
TEMPLATES
STYLES
REPORT
METHODS
EXAMPLES
KEYWORDS
COPYRIGHT
package require Tcl 8.2
package require report ?0.3.1?
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.
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:
- 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.
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:
- 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".
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
|
matrix , report , table
Copyright © 2002 Andreas Kupries
<andreas_kupries@users.sourceforge.net>