Unix/Linux Go Back    


RedHat 9 (Linux i386) - man page for report (redhat section n)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


report(n)				  Matrix reports				report(n)

NAME
       report - Create and manipulate report objects

SYNOPSIS
       package require Tcl 8.2

       package require report ?0.3?

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

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

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

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 cap-
       tion 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
       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 con-
	      tains 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 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  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
       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.

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 possible to enable or
	      disable data lines.

	      Enabling a template causes the report to check all used templates for  inconsisten-
	      cies 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 corre-
	      sponding data template and causes the report to check all used templates for incon-
	      sistencies 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 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 colum-
	      nwidth 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. 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  cur-
	      rently 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  charac-
	      ter.  Note: An alternative way of specifying the padding is to use vertical separa-
	      tor 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 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 cap-
	      tion 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 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

KEYWORDS
       matrix, report, table

report					       0.3					report(n)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 11:41 AM.