


report(n)                 Matrix reports                report(n)


______________________________________________________________________________

NAME
       report - Create and manipulate report objects

SYNOPSIS
       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

_________________________________________________________________




report                        0.3.1                             1





report(n)                 Matrix reports                report(n)


DESCRIPTION
       This  package  provides report objects which can be used by the format-
       ting 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  sepa-
       rator-  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  opera-
              tions on the report. It has the following general form:

              reportName option ?arg arg ...?
                     Option  and  the args determine the exact behavior of the
                     command. See section REPORT  METHODS  for  more  explana-
                     tions.  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 associ-
              ated 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 pre-
              defined style plain, followed by the first style defined by  the
              user, and so on.


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



report                        0.3.1                             2





report(n)                 Matrix reports                report(n)


       The size of the data area is specified implicitly.

LINES
       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:

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

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

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

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

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

       botdatasep
              This  line  is used to separate the data rows in the bottom cap-
              tion region, if it contains more  than  one  row  and  the  user
              enabled its usage.

       bottom The  bottommost line of a report. Separates the report from any-
              thing which comes after it. The user can  enable  the  usage  of
              this line at will.

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

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



report                        0.3.1                             3





report(n)                 Matrix reports                report(n)


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


TEMPLATES
       Each template is a list of strings used to format the line it is  asso-
       ciated  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  sepa-
       rator 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
       Styles are a way for the user of this package to define common configu-
       rations 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 configura-
       tion.

       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.

REPORT METHODS
       The following commands are possible for report objects:



report                        0.3.1                             4





report(n)                 Matrix reports                report(n)


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

       reportName templatecode disable|enable
              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  tem-
              plates  for  inconsistencies  in  the definition of the vertical
              lines (See section TEMPLATES).

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

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

       reportName templatecode set templatedata
              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.

       reportName tcaption ?size?
              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).

       reportName bcaption size
              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 speci-
              fied 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).

       reportName size column ?number|dyn?
              Specifies  the  size  of the column in the output. The value dyn
              means that the columnwidth returned by the matrix to be  format-
              ted  for  the  specified column shall be used. The formatting of
              the column is dynamic. If a fixed number is used instead of  dyn



report                        0.3.1                             5





report(n)                 Matrix reports                report(n)


              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.

       reportName sizes ?size-list?
              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 con-
              taining the currently set sizes instead.

       reportName pad column ?left|right|both ?padstring??
              This method allows the user to  specify  padding  on  the  left,
              right  or both sides of a column. If the padstring is not speci-
              fied it defaults to a single space character. Note: An  alterna-
              tive  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.

       reportName justify column ?left|right|center?
              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.

       reportName printmatrix matrix
              Formats  the matrix according to the configuration of the report
              and returns the resulting string. The matrix  has  to  have  the



report                        0.3.1                             6





report(n)                 Matrix reports                report(n)


              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.

       reportName printmatrix2channel matrix chan
              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.

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

EXAMPLES
       Our examples define some generally useful report styles.

       A simple table with lines surrounding all information and vertical sep-
       arators, 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 con-
       tains useful data.


           % ::struct::matrix m



report                        0.3.1                             7





report(n)                 Matrix reports                report(n)


           % # ... 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


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

KEYWORDS
       matrix, report, table

CATEGORY
       Data structures

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
























report                        0.3.1                             8


