|
|
Эта страница руководства для версии 10.9 Mac OS XЕсли Вы выполняете различную версию Mac OS X, просматриваете документацию локально:
Читать страницы руководстваСтраницы руководства предназначаются как справочник для людей, уже понимающих технологию.
|
report(n) Matrix reports report(n)
____________________________________________________________________________________________________________
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 run-time runtime
time 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 speci-fied specified
fied 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 con-taining containing
taining n columns a template for a data line has to contain "n+1" items and a template for a separa-tor separator
tor 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 com-mands commands
mands found in a safe interpreter and the configuration methods of report objects. The latter implic-itly implicitly
itly 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 speci-fied specified
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 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 alterna-tive alternative
tive way of specifying the padding is to use vertical separator strings longer than one char-acter character
acter 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://source -
forge.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>
report 0.3.1 report(n)
|
Сообщение о проблемах
Способ сообщить о проблеме с этой страницей руководства зависит от типа проблемы:
- Ошибки содержания
- Ошибки отчета в содержании этой документации со ссылками на отзыв ниже.
- Отчеты об ошибках
- Сообщите об ошибках в функциональности описанного инструмента или API через Генератор отчетов Ошибки.
- Форматирование проблем
- Отчет, форматирующий ошибки в интерактивной версии этих страниц со ссылками на отзыв ниже.