1report(n)                       Matrix reports                       report(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       report - Create and manipulate report objects
9

SYNOPSIS

11       package require Tcl  8.2
12
13       package require report  ?0.3.1?
14
15       ::report::report reportName columns ?style style arg...?
16
17       reportName option ?arg arg ...?
18
19       ::report::defstyle styleName arguments script
20
21       ::report::rmstyle styleName
22
23       ::report::stylearguments styleName
24
25       ::report::stylebody styleName
26
27       ::report::styles
28
29       reportName destroy
30
31       reportName templatecode disable|enable
32
33       reportName templatecode enabled
34
35       reportName templatecode get
36
37       reportName templatecode set templatedata
38
39       reportName tcaption ?size?
40
41       reportName bcaption size
42
43       reportName size column ?number|dyn?
44
45       reportName sizes ?size-list?
46
47       reportName pad column ?left|right|both ?padstring??
48
49       reportName justify column ?left|right|center?
50
51       reportName printmatrix matrix
52
53       reportName printmatrix2channel matrix chan
54
55       reportName columns
56
57_________________________________________________________________
58

DESCRIPTION

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
67       ::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
73              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
79       ::report::defstyle styleName arguments script
80              Defines the new style styleName. See  section  STYLES  for  more
81              information.
82
83       ::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
91       ::report::stylearguments styleName
92              This introspection command returns the list of arguments associ‐
93              ated with the style styleName.
94
95       ::report::stylebody styleName
96              This  introspection  command  returns the script associated with
97              the style styleName.
98
99       ::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

REGIONS

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

LINES

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
122       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
126       The different kinds of lines and the codes used by the  report  methods
127       to address them are:
128
129       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
133       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
138       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
142       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
146       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
151       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
156       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
160       topdata
161              This  line  defines  the format of data lines in the top caption
162              region of the report.
163
164       data   This line defines the format of data lines in the data region of
165              the report.
166
167       botdata
168              This line defines the format of data lines in the bottom caption
169              region of the report.
170

TEMPLATES

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
177       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
181       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
187       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
192       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

STYLES

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
206       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
210       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

REPORT METHODS

219       The following commands are possible for report objects:
220
221       reportName destroy
222              Destroys  the report, including its storage space and associated
223              command.
224
225       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
230              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
234       reportName templatecode enabled
235              Returns the whether the template addressed by  the  templatecode
236              is currently enabled or not.
237
238       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
243       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
248       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
254              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
259       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
265              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
270       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
279              If  no  size  specification is given the command will return the
280              current size of the column instead.
281
282       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
288              If no size-list is specified the command will return a list con‐
289              taining the currently set sizes instead.
290
291       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
299              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
304       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
308              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
315              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
323              If no justification was specified the command  will  return  the
324              current justification for the column instead.
325
326       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
333       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
340       reportName columns
341              Returns the number of columns in the report.
342
343       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

EXAMPLES

349       Our examples define some generally useful report styles.
350
351       A simple table with lines surrounding all information and vertical sep‐
352       arators, but without internal horizontal separators.
353
354           ::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
362
363       An extension of a simpletable, see above, with a title area.
364
365           ::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
373
374       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
378           % ::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
396

BUGS, IDEAS, FEEDBACK

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

KEYWORDS

405       matrix, report, table
406
408       Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net>
409
410
411
412
413report                               0.3.1                           report(n)
Impressum