Summary

###########################################################################

	File:     printcol.icn

	Subject:  Procedure to format columnar data

	Author:   Robert J. Alexander

	Date:     August 14, 1996

###########################################################################

   This file is in the public domain.

###########################################################################
  
     This procedure deals with with the problem of printing tabular
  data where the total width of items to be printed is wider than
  the page.  Simply allowing the data to wrap to additional lines
  often produces marginally readable output.  This procedure facil-
  itates printing such groups of data as vertical columns down the
  page length, instead of as horizontal rows across the page.  That
  way many, many fields can be printed neatly.  The programming of
  such a transformation can be a nuisance.  This procedure does
  much of the work for you, like deciding how many items can fit
  across the page width and ensuring that entire items will be
  printed on the same page without page breaks (if that service is
  requested).

###########################################################################
  
     For example, suppose we have a list of records we would like
  to print.  The record is defined as:
  
          record rec(item1,item2,item3,...)
  
  Also suppose that lines such as
  
          Field 1   Field 2   Field 3     ...
          -------   -------   -------     ---
          Record 1    item1     item2     item3      ...
          Record 2    item1     item2     item3      ...
  
  are too long to print across the page.  This procedure will print
  them as:
  
          TITLE
          =====
          Record 1   Record 2     ...
          --------   --------     ---
          Field 1   item1      item1       ...
          Field 2   item2      item2       ...
          Field 3   item3      item3       ...
  
  The arguments are:
  
       items:       a co-expression that produces a sequence of
                    items (usually structured data objects, but not
                    necessarily) for which data is to be printed.
  
       fields:      a list of procedures to produce the field's
                    data.  Each procedure takes two arguments.  The
                    procedure's action depends upon what is passed
                    in the first argument:
  
            header      Produces the row heading string to be used
                        for that field (the field name).
  
            width       Produces the maximum field width that can
                        be produced (including the column header).
  
            Other      Produces the field value string for the
                        item passed as the argument.
  
          The second argument is arbitrary data from the procedures
       with each invocation.  The data returned by the first func-
       tion on the list is used as a column heading string (the
       item name).
  
       title:       optional.
  
  
       pagelength:  if null (omitted) page breaks are ignored.
  
       linelength:  default 80.
  
       auxdata:     auxiliary arbitrary data to be passed to the field
                    procedures -- see `fields', above.
  
###########################################################################

This file is part of the (main) package.

printcol(items, fields, title, pagelength, linelength, auxdata)