1 2[//000000001]: # (report \- Matrix reports) 3[//000000002]: # (Generated from file 'report\.man' by tcllib/doctools with format 'markdown') 4[//000000003]: # (Copyright © 2002\-2014 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) 5[//000000004]: # (report\(n\) 0\.3\.2 tcllib "Matrix reports") 6 7<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a 8href="../../../toc.md">Table Of Contents</a> | <a 9href="../../../../index.md">Keyword Index</a> | <a 10href="../../../../toc0.md">Categories</a> | <a 11href="../../../../toc1.md">Modules</a> | <a 12href="../../../../toc2.md">Applications</a> ] <hr> 13 14# NAME 15 16report \- Create and manipulate report objects 17 18# <a name='toc'></a>Table Of Contents 19 20 - [Table Of Contents](#toc) 21 22 - [Synopsis](#synopsis) 23 24 - [Description](#section1) 25 26 - [REGIONS](#section2) 27 28 - [LINES](#section3) 29 30 - [TEMPLATES](#section4) 31 32 - [STYLES](#section5) 33 34 - [REPORT METHODS](#section6) 35 36 - [EXAMPLES](#section7) 37 38 - [Bugs, Ideas, Feedback](#section8) 39 40 - [Keywords](#keywords) 41 42 - [Category](#category) 43 44 - [Copyright](#copyright) 45 46# <a name='synopsis'></a>SYNOPSIS 47 48package require Tcl 8\.2 49package require report ?0\.3\.2? 50 51[__::report::report__ *reportName* *columns* ?__style__ *style arg\.\.\.*?](#1) 52[__reportName__ *option* ?*arg arg \.\.\.*?](#2) 53[__::report::defstyle__ *styleName arguments script*](#3) 54[__::report::rmstyle__ *styleName*](#4) 55[__::report::stylearguments__ *styleName*](#5) 56[__::report::stylebody__ *styleName*](#6) 57[__::report::styles__](#7) 58[*reportName* __destroy__](#8) 59[*reportName* *templatecode* __disable__|__enable__](#9) 60[*reportName* *templatecode* __enabled__](#10) 61[*reportName* *templatecode* __get__](#11) 62[*reportName* *templatecode* __set__ *templatedata*](#12) 63[*reportName* __tcaption__ ?*size*?](#13) 64[*reportName* __bcaption__ *size*](#14) 65[*reportName* __size__ *column* ?*number*|__dyn__?](#15) 66[*reportName* __sizes__ ?*size\-list*?](#16) 67[*reportName* __pad__ *column* ?__left__|__right__|__both__ ?*padstring*??](#17) 68[*reportName* __justify__ *column* ?__left__|__right__|__center__?](#18) 69[*reportName* __printmatrix__ *matrix*](#19) 70[*reportName* __printmatrix2channel__ *matrix chan*](#20) 71[*reportName* __[columns](\.\./\.\./\.\./\.\./index\.md\#columns)__](#21) 72 73# <a name='description'></a>DESCRIPTION 74 75This package provides report objects which can be used by the formatting methods 76of matrix objects to generate tabular reports of the matrix in various forms\. 77The report objects defined here break each report down into three 78[REGIONS](#section2) and ten classes of 79*[lines](\.\./\.\./\.\./\.\./index\.md\#lines)* \(various separator\- and data\-lines\)\. 80See the following section for more detailed explanations\. 81 82 - <a name='1'></a>__::report::report__ *reportName* *columns* ?__style__ *style arg\.\.\.*? 83 84 Creates a new report object for a report having *columns* columns with an 85 associated global Tcl command whose name is *reportName*\. This command may 86 be used to invoke various configuration operations on the report\. It has the 87 following general form: 88 89 * <a name='2'></a>__reportName__ *option* ?*arg arg \.\.\.*? 90 91 *Option* and the *arg*s determine the exact behavior of the command\. 92 See section [REPORT METHODS](#section6) for more explanations\. If 93 no __style__ is specified the report will use the builtin style 94 __plain__ as its default configuration\. 95 96 - <a name='3'></a>__::report::defstyle__ *styleName arguments script* 97 98 Defines the new style *styleName*\. See section [STYLES](#section5) 99 for more information\. 100 101 - <a name='4'></a>__::report::rmstyle__ *styleName* 102 103 Deletes the style *styleName*\. Trying to delete an unknown or builtin 104 style will result in an error\. Beware, this command will not check that 105 there are no other styles depending on the deleted one\. Deleting a style 106 which is still used by another style FOO will result in a runtime error when 107 FOO is applied to a newly instantiated report\. 108 109 - <a name='5'></a>__::report::stylearguments__ *styleName* 110 111 This introspection command returns the list of arguments associated with the 112 style *styleName*\. 113 114 - <a name='6'></a>__::report::stylebody__ *styleName* 115 116 This introspection command returns the script associated with the style 117 *styleName*\. 118 119 - <a name='7'></a>__::report::styles__ 120 121 This introspection command returns a list containing the names of all styles 122 known to the package at the time of the call\. The order of the names in the 123 list reflects the order in which the styles were created\. In other words, 124 the first item is the predefined style __plain__, followed by the first 125 style defined by the user, and so on\. 126 127# <a name='section2'></a>REGIONS 128 129The three regions are the *top caption*, *data area* and *bottom caption*\. 130These are, roughly speaking, the title, the values to report and a title at the 131bottom\. The size of the caption regions can be specified by the user as the 132number of rows they occupy in the matrix to format\. The size of the data area is 133specified implicitly\. 134 135# <a name='section3'></a>LINES 136 137[TEMPLATES](#section4) are associated with each of the ten line classes, 138defining the formatting for this kind of line\. The user is able to enable and 139disable the separator lines at will, but not the data lines\. Their usage is 140solely determined by the number of rows contained in the three regions\. Data 141lines and all enabled separators must have a template associated with them\. 142 143Note that the data\-lines in a report and the rows in the matrix the report was 144generated from are *not* in a 1:1 relationship if any row in the matrix has a 145height greater than one\. 146 147The different kinds of lines and the codes used by the report methods to address 148them are: 149 150 - __top__ 151 152 The topmost line of a report\. Separates the report from anything which came 153 before it\. The user can enable the usage of this line at will\. 154 155 - __topdatasep__ 156 157 This line is used to separate the data rows in the top caption region, if it 158 contains more than one row and the user enabled its usage\. 159 160 - __topcapsep__ 161 162 This line is used to separate the top caption and data regions, if the top 163 caption is not empty and the user enabled its usage\. 164 165 - __datasep__ 166 167 This line is used to separate the data rows in the data region, if it 168 contains more than one row and the user enabled its usage\. 169 170 - __botcapsep__ 171 172 This line is used to separate the data and bottom caption regions, if the 173 bottom caption is not empty and the user enabled its usage\. 174 175 - __botdatasep__ 176 177 This line is used to separate the data rows in the bottom caption region, if 178 it contains more than one row and the user enabled its usage\. 179 180 - __bottom__ 181 182 The bottommost line of a report\. Separates the report from anything which 183 comes after it\. The user can enable the usage of this line at will\. 184 185 - __topdata__ 186 187 This line defines the format of data lines in the top caption region of the 188 report\. 189 190 - __data__ 191 192 This line defines the format of data lines in the data region of the report\. 193 194 - __botdata__ 195 196 This line defines the format of data lines in the bottom caption region of 197 the report\. 198 199# <a name='section4'></a>TEMPLATES 200 201Each template is a list of strings used to format the line it is associated 202with\. For a report containing __n__ columns a template for a data line has 203to contain "__n__\+1" items and a template for a separator line 204"2\*__n__\+1" items\. 205 206The items in a data template specify the strings used to separate the column 207information\. Together with the corresponding items in the separator templates 208they form the vertical lines in the report\. 209 210*Note* that the corresponding items in all defined templates have to be of 211equal length\. This will be checked by the report object\. The first item defines 212the leftmost vertical line and the last item defines the rightmost vertical 213line\. The item at index __k__ \("1",\.\.\.,"__n__\-2"\) separates the 214information in the columns "__k__\-1" and "__k__"\. 215 216The items in a separator template having an even\-numbered index \("0","2",\.\.\.\) 217specify the column separators\. The item at index "2\*__k__" 218\("0","2",\.\.\.,"2\*__n__"\) corresponds to the items at index "__k__" in the 219data templates\. 220 221The items in a separator template having an odd\-numbered index \("1","3",\.\.\.\) 222specify the strings used to form the horizontal lines in the separator lines\. 223The item at index "2\*__k__\+1" \("1","3",\.\.\.,"2\*__n__\+1"\) corresponds to 224column "__k__"\. When generating the horizontal lines the items are 225replicated to be at least as long as the size of their column and then cut to 226the exact size\. 227 228# <a name='section5'></a>STYLES 229 230Styles are a way for the user of this package to define common configurations 231for report objects and then use them later during the actual instantiation of 232report objects\. They are defined as tcl scripts which when executed configure 233the report object into the requested configuration\. 234 235The command to define styles is __::report::defstyle__\. Its last argument is 236the tcl __script__ performing the actual reconfiguration of the report 237object to obtain the requested style\. 238 239In this script the names of all previously defined styles are available as 240commands, as are all commands found in a safe interpreter and the configuration 241methods of report objects\. The latter implicitly operate on the object currently 242executing the style script\. The __arguments__ declared here are available in 243the __script__ as variables\. When calling the command of a previously 244declared style all the arguments expected by it have to be defined in the call\. 245 246# <a name='section6'></a>REPORT METHODS 247 248The following commands are possible for report objects: 249 250 - <a name='8'></a>*reportName* __destroy__ 251 252 Destroys the report, including its storage space and associated command\. 253 254 - <a name='9'></a>*reportName* *templatecode* __disable__|__enable__ 255 256 Enables or disables the usage of the template addressed by the 257 *templatecode*\. Only the codes for separator lines are allowed here\. It is 258 not possible to enable or disable data lines\. 259 260 Enabling a template causes the report to check all used templates for 261 inconsistencies in the definition of the vertical lines \(See section 262 [TEMPLATES](#section4)\)\. 263 264 - <a name='10'></a>*reportName* *templatecode* __enabled__ 265 266 Returns the whether the template addressed by the *templatecode* is 267 currently enabled or not\. 268 269 - <a name='11'></a>*reportName* *templatecode* __get__ 270 271 Returns the template currently associated with the kind of line addressed by 272 the *templatecode*\. All known templatecodes are allowed here\. 273 274 - <a name='12'></a>*reportName* *templatecode* __set__ *templatedata* 275 276 Sets the template associated with the kind of line addressed by the 277 *templatecode* to the new value in *templatedata*\. See section 278 [TEMPLATES](#section4) for constraints on the length of templates\. 279 280 - <a name='13'></a>*reportName* __tcaption__ ?*size*? 281 282 Specifies the *size* of the top caption region as the number rows it 283 occupies in the matrix to be formatted\. Only numbers greater than or equal 284 to zero are allowed\. If no *size* is specified the command will return the 285 current size instead\. 286 287 Setting the size of the top caption to a value greater than zero enables the 288 corresponding data template and causes the report to check all used 289 templates for inconsistencies in the definition of the vertical lines \(See 290 section [TEMPLATES](#section4)\)\. 291 292 - <a name='14'></a>*reportName* __bcaption__ *size* 293 294 Specifies the *size* of the bottom caption region as the number rows it 295 occupies in the matrix to be formatted\. Only numbers greater than or equal 296 to zero are allowed\. If no *size* is specified the command will return the 297 current size instead\. 298 299 Setting the size of the bottom caption to a value greater than zero enables 300 the corresponding data template and causes the report to check all used 301 templates for inconsistencies in the definition of the vertical lines \(See 302 section [TEMPLATES](#section4)\)\. 303 304 - <a name='15'></a>*reportName* __size__ *column* ?*number*|__dyn__? 305 306 Specifies the size of the *column* in the output\. The value __dyn__ 307 means that the columnwidth returned by the matrix to be formatted for the 308 specified column shall be used\. The formatting of the column is dynamic\. If 309 a fixed *number* is used instead of __dyn__ it means that the column 310 has a width of that many characters \(padding excluded\)\. Only numbers greater 311 than zero are allowed here\. 312 313 If no size specification is given the command will return the current size 314 of the *column* instead\. 315 316 - <a name='16'></a>*reportName* __sizes__ ?*size\-list*? 317 318 This method allows the user to specify the sizes of all columns in one call\. 319 Its argument is a list containing the sizes to associate with the columns\. 320 The first item is associated with column 0, the next with column 1, and so 321 on\. 322 323 If no *size\-list* is specified the command will return a list containing 324 the currently set sizes instead\. 325 326 - <a name='17'></a>*reportName* __pad__ *column* ?__left__|__right__|__both__ ?*padstring*?? 327 328 This method allows the user to specify padding on the left, right or both 329 sides of a *column*\. If the *padstring* is not specified it defaults to 330 a single space character\. *Note*: An alternative way of specifying the 331 padding is to use vertical separator strings longer than one character in 332 the templates \(See section [TEMPLATES](#section4)\)\. 333 334 If no pad specification is given at all the command will return the current 335 state of padding for the column instead\. This will be a list containing two 336 elements, the first element the left padding, the second describing the 337 right padding\. 338 339 - <a name='18'></a>*reportName* __justify__ *column* ?__left__|__right__|__center__? 340 341 Declares how the cell values for a *column* are filled into the report 342 given the specified size of a column in the report\. 343 344 For __left__ and __right__ justification a cell value shorter than 345 the width of the column is bound with its named edge to the same edge of the 346 column\. The other side is filled with spaces\. In the case of __center__ 347 the spaces are placed to both sides of the value and the left number of 348 spaces is at most one higher than the right number of spaces\. 349 350 For a value longer than the width of the column the value is cut at the 351 named edge\. This means for __left__ justification that the *tail* 352 \(i\.e\. the __right__ part\) of the value is made visible in the output\. 353 For __center__ the value is cut at both sides to fit into the column and 354 the number of characters cut at the left side of the value is at most one 355 less than the number of characters cut from the right side\. 356 357 If no justification was specified the command will return the current 358 justification for the column instead\. 359 360 - <a name='19'></a>*reportName* __printmatrix__ *matrix* 361 362 Formats the *matrix* according to the configuration of the report and 363 returns the resulting string\. The matrix has to have the same number of 364 columns as the report\. The matrix also has to have enough rows so that the 365 top and bottom caption regions do not overlap\. The data region is allowed to 366 be empty\. 367 368 - <a name='20'></a>*reportName* __printmatrix2channel__ *matrix chan* 369 370 Formats the *matrix* according to the configuration of the report and 371 writes the result into the channel *chan*\. The matrix has to have the same 372 number of columns as the report\. The matrix also has to have enough rows so 373 that the top and bottom caption regions do not overlap\. The data region is 374 allowed to be empty\. 375 376 - <a name='21'></a>*reportName* __[columns](\.\./\.\./\.\./\.\./index\.md\#columns)__ 377 378 Returns the number of columns in the report\. 379 380The methods __size__, __pad__ and __justify__ all take a column 381index as their first argument\. This index is allowed to use all the forms of an 382index as accepted by the __lindex__ command\. The allowed range for indices 383is "0,\.\.\.,\[__reportName__ columns\]\-1"\. 384 385# <a name='section7'></a>EXAMPLES 386 387Our examples define some generally useful report styles\. 388 389A simple table with lines surrounding all information and vertical separators, 390but without internal horizontal separators\. 391 392 ::report::defstyle simpletable {} { 393 data set [split "[string repeat "| " [columns]]|"] 394 top set [split "[string repeat "+ - " [columns]]+"] 395 bottom set [top get] 396 top enable 397 bottom enable 398 } 399 400An extension of a __simpletable__, see above, with a title area\. 401 402 ::report::defstyle captionedtable {{n 1}} { 403 simpletable 404 topdata set [data get] 405 topcapsep set [top get] 406 topcapsep enable 407 tcaption $n 408 } 409 410Given the definitions above now an example which actually formats a matrix into 411a tabular report\. It assumes that the matrix actually contains useful data\. 412 413 % ::struct::matrix m 414 % # ... fill m with data, assume 5 columns 415 % ::report::report r 5 style captionedtable 1 416 % r printmatrix m 417 +---+-------------------+-------+-------+--------+ 418 |000|VERSIONS: |2:8.4a3|1:8.4a3|1:8.4a3%| 419 +---+-------------------+-------+-------+--------+ 420 |001|CATCH return ok |7 |13 |53.85 | 421 |002|CATCH return error |68 |91 |74.73 | 422 |003|CATCH no catch used|7 |14 |50.00 | 423 |004|IF if true numeric |12 |33 |36.36 | 424 |005|IF elseif |15 |47 |31.91 | 425 | |true numeric | | | | 426 +---+-------------------+-------+-------+--------+ 427 % 428 % # alternate way of doing the above 429 % m format 2string r 430 431# <a name='section8'></a>Bugs, Ideas, Feedback 432 433This document, and the package it describes, will undoubtedly contain bugs and 434other problems\. Please report such in the category *report* of the [Tcllib 435Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas 436for enhancements you may have for either package and/or documentation\. 437 438When proposing code changes, please provide *unified diffs*, i\.e the output of 439__diff \-u__\. 440 441Note further that *attachments* are strongly preferred over inlined patches\. 442Attachments can be made by going to the __Edit__ form of the ticket 443immediately after its creation, and then using the left\-most button in the 444secondary navigation bar\. 445 446# <a name='keywords'></a>KEYWORDS 447 448[matrix](\.\./\.\./\.\./\.\./index\.md\#matrix), 449[report](\.\./\.\./\.\./\.\./index\.md\#report), 450[table](\.\./\.\./\.\./\.\./index\.md\#table) 451 452# <a name='category'></a>CATEGORY 453 454Data structures 455 456# <a name='copyright'></a>COPYRIGHT 457 458Copyright © 2002\-2014 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> 459