Tcl Library Source Code

Documentation
Login
Bounty program for improvements to Tcl and certain Tcl packages.


[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]

NAME

report - Create and manipulate report objects

Table Of Contents

SYNOPSIS

package require Tcl 8.5
package require report ?0.4?

::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.

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:

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:

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 Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

When proposing code changes, please provide unified diffs, i.e the output of diff -u.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar.

KEYWORDS

matrix, report, table

CATEGORY

Data structures

COPYRIGHT

Copyright © 2002-2014,2022 Andreas Kupries