NAME

       ::report::report - Create and manipulate report objects


SYNOPSIS

       package require report ?1.0?

       ::report::report reportName columns ?style style arg...?

       ::report::defstyle styleName arguments script

       ::report::rmstyle styleName

       ::report::stylearguments styleName

       ::report::stylebody styleName

       ::report::styles

_________________________________________________________________


DESCRIPTION

       This  package provides report objects which can be used by
       the formatting methods of matrix objects to generate tabu­
       lar  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  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
              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.

              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 asso­
              ciated with the style styleName.

       ::report::styles
              This  introspection command returns a list contain­
              ing 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 bot­
       tom 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.


LINES

       Each of the ten line classes can have a template (see sec­
       tion below) associated with it 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 separa­
       tors 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.

              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 caption 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 anything 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.

       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 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 corre­
       sponding 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 verti­
       cal 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

       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 repli­
       cated 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 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  con­
       figure 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  cur­
       rently  executing the style script. The arguments declared
       here are available in the script as variables. When  call­
       ing  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:

       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 possi­
              ble to enable or disable data lines.

              Enabling a template causes the report to check  all
              used  templates  for inconsistencies in the defini­
              tion of the vertical lines (See section TEMPLATES).

       reportName templatecode enabled
              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.

       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 format­
              ted. 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 specified the  com­
              mand 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 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.

       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.

              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.

       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 specified it defaults to a single
              space character. Note: An alternative way of speci­
              fying  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 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


       reportName printmatrix2channel matrix chan
              Formats  the  matrix according to the configuration
              of the report and writes the result into the  chan­
              nel 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 separators, but without internal horizontal sepa­
       rators.

              ::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
                topcapsep set [top get]
                topcapsep enable
                tcaption $n
              }


KEYWORDS

       matrix, report, table


Man(1) output converted with man2html