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.2?
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  ma‐
62       trix  in  various forms. The report objects defined here break each re‐
63       port down into three REGIONS and ten classes of lines (various  separa‐
64       tor-  and  data-lines). See the following section for more detailed ex‐
65       planations.
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 in‐
81              formation.
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  ti‐
110       tle  at the bottom. The size of the caption regions can be specified by
111       the user as the number of rows they occupy in the matrix to format. The
112       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 us‐
118       age is solely determined by the number of rows contained in  the  three
119       regions. Data lines and all enabled separators must have a template as‐
120       sociated with them.
121
122       Note that the data-lines in a report and the rows in the matrix the re‐
123       port was generated from are not in a 1:1 relationship if any row in the
124       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 re‐
148              gions, 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  en‐
154              abled 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  de‐
214       clared  here are available in the script as variables. When calling the
215       command of a previously declared style all the arguments expected by it
216       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  al‐
241              lowed 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 re‐
267              port to check all used templates for inconsistencies in the def‐
268              inition 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  re‐
338              gions 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 ma‐
375       trix 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  Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please
401       also report any ideas for enhancements you may have for either  package
402       and/or documentation.
403
404       When proposing code changes, please provide unified diffs, i.e the out‐
405       put of diff -u.
406
407       Note further that  attachments  are  strongly  preferred  over  inlined
408       patches.  Attachments  can  be  made  by  going to the Edit form of the
409       ticket immediately after its creation, and  then  using  the  left-most
410       button in the secondary navigation bar.
411

KEYWORDS

413       matrix, report, table
414

CATEGORY

416       Data structures
417
419       Copyright (c) 2002-2014 Andreas Kupries <andreas_kupries@users.sourceforge.net>
420
421
422
423
424tcllib                               0.3.2                           report(n)
Impressum