report(n) Matrix reports report(n) 







report - Create and manipulate report objects








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












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:







  

  
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 runtime 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.










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
    specified by the user as the number of rows they occupy in the matrix to
    format. The size of the data area is specified implicitly.








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:



  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
This line defines the format of data lines in the top caption region of
      the report.

  

  
This line defines the format of data lines in the data region of the
      report.

  

  
This line defines the format of data lines in the bottom caption region of
      the report.










Each template is a list of strings used to format the line it is
    associated with. For a report containing n columns a template for a
    data line has to contain "n+1" items and a template for a
    separator 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 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 commands found in a safe interpreter and
    the configuration methods of report objects. The latter implicitly 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.








The following commands are possible for report objects:



  

  
Destroys the report, including its storage space and associated
    command.

  

  
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).

  

  

  
Returns the whether the template addressed by the templatecode is
      currently enabled or not.

  

  
Returns the template currently associated with the kind of line addressed
      by the templatecode. All known templatecodes are allowed here.

  

  
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.

  

  
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).

  

  

  
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 specified 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).

  

  

  
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.

  

  

  
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.

  

  

  
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 alternative way of
      specifying the padding is to use vertical separator strings longer than
      one character 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.

  

  

  
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.

  

  

  
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.

  

  
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.

  

  
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".








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









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://sourceforge.net/tracker/?group_id=12883]. Please also report any
    ideas for enhancements you may have for either package and/or
  documentation.








matrix, report, table








Data structures








Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net>








  

    0.3.1
    report