1report(n) Matrix reports report(n)
2______________________________________________________________________________
6
8 report - Create and manipulate report objects
9
11 package require Tcl 8.2
12 package require report ?0.3.1?
14 ::report::report reportName columns ?style style arg...?
16 reportName option ?arg arg ...?
18 ::report::defstyle styleName arguments script
20 ::report::rmstyle styleName
22 ::report::stylearguments styleName
24 ::report::stylebody styleName
26 ::report::styles
28 reportName destroy
30 reportName templatecode disable|enable
32 reportName templatecode enabled
34 reportName templatecode get
36 reportName templatecode set templatedata
38 reportName tcaption ?size?
40 reportName bcaption size
42 reportName size column ?number|dyn?
44 reportName sizes ?size-list?
46 reportName pad column ?left|right|both ?padstring??
48 reportName justify column ?left|right|center?
50 reportName printmatrix matrix
52 reportName printmatrix2channel matrix chan
54 reportName columns
56_________________________________________________________________
58
60 This package provides report objects which can be used by the format‐
61 ting methods of matrix objects to generate tabular reports of the
62 matrix in various forms. The report objects defined here break each
63 report down into three REGIONS and ten classes of lines (various sepa‐
64 rator- and data-lines). See the following section for more detailed
65 explanations.
66 ::report::report reportName columns ?style style arg...?
68 Creates a new report object for a report having columns columns
69 with an associated global Tcl command whose name is reportName.
70 This command may be used to invoke various configuration opera‐
71 tions on the report. It has the following general form:
72 reportName option ?arg arg ...?
74 Option and the args determine the exact behavior of the
75 command. See section REPORT METHODS for more explana‐
76 tions. If no style is specified the report will use the
77 builtin style plain as its default configuration.
78 ::report::defstyle styleName arguments script
80 Defines the new style styleName. See section STYLES for more
81 information.
82 ::report::rmstyle styleName
84 Deletes the style styleName. Trying to delete an unknown or
85 builtin style will result in an error. Beware, this command will
86 not check that there are no other styles depending on the
87 deleted one. Deleting a style which is still used by another
88 style FOO will result in a runtime error when FOO is applied to
89 a newly instantiated report.
90 ::report::stylearguments styleName
92 This introspection command returns the list of arguments associ‐
93 ated with the style styleName.
94 ::report::stylebody styleName
96 This introspection command returns the script associated with
97 the style styleName.
98 ::report::styles
100 This introspection command returns a list containing the names
101 of all styles known to the package at the time of the call. The
102 order of the names in the list reflects the order in which the
103 styles were created. In other words, the first item is the pre‐
104 defined style plain, followed by the first style defined by the
105 user, and so on.
106
108 The three regions are the top caption, data area and bottom caption.
109 These are, roughly speaking, the title, the values to report and a
110 title at the bottom. The size of the caption regions can be specified
111 by the user as the number of rows they occupy in the matrix to format.
112 The size of the data area is specified implicitly.
113
115 TEMPLATES are associated with each of the ten line classes, defining
116 the formatting for this kind of line. The user is able to enable and
117 disable the separator lines at will, but not the data lines. Their
118 usage is solely determined by the number of rows contained in the three
119 regions. Data lines and all enabled separators must have a template
120 associated with them.
121 Note that the data-lines in a report and the rows in the matrix the
123 report was generated from are not in a 1:1 relationship if any row in
124 the matrix has a height greater than one.
125 The different kinds of lines and the codes used by the report methods
127 to address them are:
128 top The topmost line of a report. Separates the report from anything
130 which came before it. The user can enable the usage of this line
131 at will.
132 topdatasep
134 This line is used to separate the data rows in the top caption
135 region, if it contains more than one row and the user enabled
136 its usage.
137 topcapsep
139 This line is used to separate the top caption and data regions,
140 if the top caption is not empty and the user enabled its usage.
141 datasep
143 This line is used to separate the data rows in the data region,
144 if it contains more than one row and the user enabled its usage.
145 botcapsep
147 This line is used to separate the data and bottom caption
148 regions, if the bottom caption is not empty and the user enabled
149 its usage.
150 botdatasep
152 This line is used to separate the data rows in the bottom cap‐
153 tion region, if it contains more than one row and the user
154 enabled its usage.
155 bottom The bottommost line of a report. Separates the report from any‐
157 thing which comes after it. The user can enable the usage of
158 this line at will.
159 topdata
161 This line defines the format of data lines in the top caption
162 region of the report.
163 data This line defines the format of data lines in the data region of
165 the report.
166 botdata
168 This line defines the format of data lines in the bottom caption
169 region of the report.
170
172 Each template is a list of strings used to format the line it is asso‐
173 ciated with. For a report containing n columns a template for a data
174 line has to contain "n+1" items and a template for a separator line
175 "2*n+1" items.
176 The items in a data template specify the strings used to separate the
178 column information. Together with the corresponding items in the sepa‐
179 rator templates they form the vertical lines in the report.
180 Note that the corresponding items in all defined templates have to be
182 of equal length. This will be checked by the report object. The first
183 item defines the leftmost vertical line and the last item defines the
184 rightmost vertical line. The item at index k ("1",...,"n-2") separates
185 the information in the columns "k-1" and "k".
186 The items in a separator template having an even-numbered index
188 ("0","2",...) specify the column separators. The item at index "2*k"
189 ("0","2",...,"2*n") corresponds to the items at index "k" in the data
190 templates.
191 The items in a separator template having an odd-numbered index
193 ("1","3",...) specify the strings used to form the horizontal lines in
194 the separator lines. The item at index "2*k+1" ("1","3",...,"2*n+1")
195 corresponds to column "k". When generating the horizontal lines the
196 items are replicated to be at least as long as the size of their column
197 and then cut to the exact size.
198
200 Styles are a way for the user of this package to define common configu‐
201 rations for report objects and then use them later during the actual
202 instantiation of report objects. They are defined as tcl scripts which
203 when executed configure the report object into the requested configura‐
204 tion.
205 The command to define styles is ::report::defstyle. Its last argument
207 is the tcl script performing the actual reconfiguration of the report
208 object to obtain the requested style.
209 In this script the names of all previously defined styles are available
211 as commands, as are all commands found in a safe interpreter and the
212 configuration methods of report objects. The latter implicitly operate
213 on the object currently executing the style script. The arguments
214 declared here are available in the script as variables. When calling
215 the command of a previously declared style all the arguments expected
216 by it have to be defined in the call.
217
219 The following commands are possible for report objects:
220 reportName destroy
222 Destroys the report, including its storage space and associated
223 command.
224 reportName templatecode disable|enable
226 Enables or disables the usage of the template addressed by the
227 templatecode. Only the codes for separator lines are allowed
228 here. It is not possible to enable or disable data lines.
229 Enabling a template causes the report to check all used tem‐
231 plates for inconsistencies in the definition of the vertical
232 lines (See section TEMPLATES).
233 reportName templatecode enabled
235 Returns the whether the template addressed by the templatecode
236 is currently enabled or not.
237 reportName templatecode get
239 Returns the template currently associated with the kind of line
240 addressed by the templatecode. All known templatecodes are
241 allowed here.
242 reportName templatecode set templatedata
244 Sets the template associated with the kind of line addressed by
245 the templatecode to the new value in templatedata. See section
246 TEMPLATES for constraints on the length of templates.
247 reportName tcaption ?size?
249 Specifies the size of the top caption region as the number rows
250 it occupies in the matrix to be formatted. Only numbers greater
251 than or equal to zero are allowed. If no size is specified the
252 command will return the current size instead.
253 Setting the size of the top caption to a value greater than zero
255 enables the corresponding data template and causes the report to
256 check all used templates for inconsistencies in the definition
257 of the vertical lines (See section TEMPLATES).
258 reportName bcaption size
260 Specifies the size of the bottom caption region as the number
261 rows it occupies in the matrix to be formatted. Only numbers
262 greater than or equal to zero are allowed. If no size is speci‐
263 fied the command will return the current size instead.
264 Setting the size of the bottom caption to a value greater than
266 zero enables the corresponding data template and causes the
267 report to check all used templates for inconsistencies in the
268 definition of the vertical lines (See section TEMPLATES).
269 reportName size column ?number|dyn?
271 Specifies the size of the column in the output. The value dyn
272 means that the columnwidth returned by the matrix to be format‐
273 ted for the specified column shall be used. The formatting of
274 the column is dynamic. If a fixed number is used instead of dyn
275 it means that the column has a width of that many characters
276 (padding excluded). Only numbers greater than zero are allowed
277 here.
278 If no size specification is given the command will return the
280 current size of the column instead.
281 reportName sizes ?size-list?
283 This method allows the user to specify the sizes of all columns
284 in one call. Its argument is a list containing the sizes to as‐
285 sociate with the columns. The first item is associated with col‐
286 umn 0, the next with column 1, and so on.
287 If no size-list is specified the command will return a list con‐
289 taining the currently set sizes instead.
290 reportName pad column ?left|right|both ?padstring??
292 This method allows the user to specify padding on the left,
293 right or both sides of a column. If the padstring is not speci‐
294 fied it defaults to a single space character. Note: An alterna‐
295 tive way of specifying the padding is to use vertical separator
296 strings longer than one character in the templates (See section
297 TEMPLATES).
298 If no pad specification is given at all the command will return
300 the current state of padding for the column instead. This will
301 be a list containing two elements, the first element the left
302 padding, the second describing the right padding.
303 reportName justify column ?left|right|center?
305 Declares how the cell values for a column are filled into the
306 report given the specified size of a column in the report.
307 For left and right justification a cell value shorter than the
309 width of the column is bound with its named edge to the same
310 edge of the column. The other side is filled with spaces. In the
311 case of center the spaces are placed to both sides of the value
312 and the left number of spaces is at most one higher than the
313 right number of spaces.
314 For a value longer than the width of the column the value is cut
316 at the named edge. This means for left justification that the
317 tail (i.e. the right part) of the value is made visible in the
318 output. For center the value is cut at both sides to fit into
319 the column and the number of characters cut at the left side of
320 the value is at most one less than the number of characters cut
321 from the right side.
322 If no justification was specified the command will return the
324 current justification for the column instead.
325 reportName printmatrix matrix
327 Formats the matrix according to the configuration of the report
328 and returns the resulting string. The matrix has to have the
329 same number of columns as the report. The matrix also has to
330 have enough rows so that the top and bottom caption regions do
331 not overlap. The data region is allowed to be empty.
332 reportName printmatrix2channel matrix chan
334 Formats the matrix according to the configuration of the report
335 and writes the result into the channel chan. The matrix has to
336 have the same number of columns as the report. The matrix also
337 has to have enough rows so that the top and bottom caption
338 regions do not overlap. The data region is allowed to be empty.
339 reportName columns
341 Returns the number of columns in the report.
342 The methods size, pad and justify all take a column index as their
344 first argument. This index is allowed to use all the forms of an index
345 as accepted by the lindex command. The allowed range for indices is
346 "0,...,[reportName columns]-1".
347
349 Our examples define some generally useful report styles.
350 A simple table with lines surrounding all information and vertical sep‐
352 arators, but without internal horizontal separators.
353 ::report::defstyle simpletable {} {
355 data set [split "[string repeat "| " [columns]]|"]
356 top set [split "[string repeat "+ - " [columns]]+"]
357 bottom set [top get]
358 top enable
359 bottom enable
360 }
361 An extension of a simpletable, see above, with a title area.
364 ::report::defstyle captionedtable {{n 1}} {
366 simpletable
367 topdata set [data get]
368 topcapsep set [top get]
369 topcapsep enable
370 tcaption $n
371 }
372 Given the definitions above now an example which actually formats a
375 matrix into a tabular report. It assumes that the matrix actually con‐
376 tains useful data.
377 % ::struct::matrix m
379 % # ... fill m with data, assume 5 columns
380 % ::report::report r 5 style captionedtable 1
381 % r printmatrix m
382 +---+-------------------+-------+-------+--------+
383 |000|VERSIONS: |2:8.4a3|1:8.4a3|1:8.4a3%|
384 +---+-------------------+-------+-------+--------+
385 |001|CATCH return ok |7 |13 |53.85 |
386 |002|CATCH return error |68 |91 |74.73 |
387 |003|CATCH no catch used|7 |14 |50.00 |
388 |004|IF if true numeric |12 |33 |36.36 |
389 |005|IF elseif |15 |47 |31.91 |
390 | |true numeric | | | |
391 +---+-------------------+-------+-------+--------+
392 %
393 % # alternate way of doing the above
394 % m format 2string r
395
398 This document, and the package it describes, will undoubtedly contain
399 bugs and other problems. Please report such in the category report of
400 the Tcllib SF Trackers [http://source‐
401 forge.net/tracker/?group_id=12883]. Please also report any ideas for
402 enhancements you may have for either package and/or documentation.
403
405 matrix, report, table
406
408 Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net>
409report 0.3.1 report(n)