Provided by: libhtml-table-perl_2.08a-5_all bug

NAME

       HTML::Table - produces HTML tables

SYNOPSIS

         use HTML::Table;

         $table1 = new HTML::Table($rows, $cols);
           or
         $table1 = new HTML::Table(-rows=>26,
                                   -cols=>2,
                                   -align=>'center',
                                   -rules=>'rows',
                                   -border=>0,
                                   -bgcolor=>'blue',
                                   -width=>'50%',
                                   -spacing=>0,
                                   -padding=>0,
                                   -style=>'color: blue',
                                   -class=>'myclass',
                                   -evenrowclass=>'even',
                                   -oddrowclass=>'odd',
                                   -head=> ['head1', 'head2'],
                                   -data=> [ ['1:1', '1:2'], ['2:1', '2:2'] ] );
          or
         $table1 = new HTML::Table( [ ['1:1', '1:2'], ['2:1', '2:2'] ] );

         $table1->setCell($cellrow, $cellcol, 'This is Cell 1');
         $table1->setCellBGColor('blue');
         $table1->setCellColSpan(1, 1, 2);
         $table1->setRowHead(1);
         $table1->setColHead(1);

         $table1->print;

         $table2 = new HTML::Table;
         $table2->addRow(@cell_values);
         $table2->addCol(@cell_values2);

         $table1->setCell(1,1, "$table2->getTable");
         $table1->print;

REQUIRES

       Perl5.002

EXPORTS

       Nothing

DESCRIPTION

       HTML::Table is used to generate HTML tables for CGI scripts.  By using the methods
       provided fairly complex tables can be created, manipulated, then printed from Perl
       scripts.  The module also greatly simplifies creating tables within tables from Perl.  It
       is possible to create an entire table using the methods provided and never use an HTML
       tag.

       HTML::Table also allows for creating dynamically sized tables via its addRow and addCol
       methods.  These methods automatically resize the table if passed more cell values than
       will fit in the current table grid.

       Methods are provided for nearly all valid table, row, and cell tags specified for HTML
       3.0.

       A Japanese translation of the documentation is available at:

               http://member.nifty.ne.jp/hippo2000/perltips/html/table.htm

METHODS

         [] indicate optional parameters. default value will
            be used if no value is specified

         row_num indicates that a row number is required.
               Rows are numbered from 1.  To refer to the last row use the value -1.

         col_num indicates that a col number is required.
               Cols are numbered from 1.  To refer to the last col use the value -1.

   Sections
           From version 2.07 onwards HTML::Table supports table sections (THEAD, TFOOT & TBODY).

           Each section can have its own attributes (id, class, etc) set, and will contain 1 or
           more rows.  Section numbering starts at 0, only tbody is allowed to have more than one
           section.

           Methods for manipultaing sections and their data are available and have the general
           form:

             setSectionCell ( section, section_num, row_num, col_num, data );

             For example, the following adds a row to the first body section:

             addSectionRow ( 'tbody', 0, "Cell 1", "Cell 2", "Cell 3" );

           For backwards compatibility, methods with Section in their name will default to
           manipulating the first body section.

             For example, the following sets the class for the first row in the
             first body section:

             setRowClass ( 1, 'row_class' );

             Which is semantically equivalent to:

             setSectionRowClass ( 'tbody', 0, 1, 'row_class' );

   Creation
       new HTML::Table([num_rows, num_cols])
           Creates a new HTML table object.  If rows and columns are specified, the table will be
           initialized to that size.  Row and Column numbers start at 1,1.  0,0 is considered an
           empty table.

       new HTML::Table([-rows=>num_rows, -cols=>num_cols, -border=>border_width,
       -align=>table_alignment, -style=>table_style, -class=>table_class, -evenrowclass=>'even',
       -oddrowclass=>'odd', -bgcolor=>back_colour, -width=>table_width, -spacing=>cell_spacing,
       -padding=>cell_padding])
           Creates a new HTML table object.  If rows and columns are specified, the table will be
           initialized to that size.  Row and Column numbers start at 1,1.  0,0 is considered an
           empty table.

           If evenrowclass or oddrowclass is specified, these classes will be applied to even and
           odd rows, respectively, unless those rows have a specific class applied to it.

   Table Level Methods
       setBorder([pixels])
           Sets the table Border Width

       setWidth([pixels|percentofscreen])
           Sets the table width

                   $table->setWidth(500);
             or
                   $table->setWidth('100%');

       setCellSpacing([pixels])
       setCellPadding([pixels])
       setCaption("CaptionText" [, top|bottom])
       setBGColor([colorname|colortriplet])
       autoGrow([1|true|on|anything|0|false|off|no|disable])
           Switches on (default) or off automatic growing of the table if row or column values
           passed to setCell exceed current table size.

       setAlign ( [ left , center , right ] )
       setRules ( [ rows , cols , all, both , groups  ] )
       setStyle ( 'css style' )
           Sets the table style attribute.

       setClass ( 'css class' )
           Sets the table class attribute.

       setEvenRowClass ( 'css class' )
           Sets the class attribute of even rows in the table.

       setOddRowClass ( 'css class' )
           Sets the class attribute of odd rows in the table.

       setAttr ( 'user attribute' )
           Sets a user defined attribute for the table.  Useful for when HTML::Table hasn't
           implemented a particular attribute yet

       sort ( [sort_col_num, sort_type, sort_order, num_rows_to_skip] )
                   or
             sort( -sort_col => sort_col_num,
                   -sort_type => sort_type,
                   -sort_order => sort_order,
                   -skip_rows => num_rows_to_skip,
                   -strip_html => strip_html,
                   -strip_non_numeric => strip_non_numeric,
                   -presort_func => \&filter_func )

               sort_type in { ALPHA | NUMERIC },
               sort_order in { ASC | DESC },
               strip_html in { 0 | 1 }, defaults to 1,
               strip_non_numeric in { 0 | 1 }, defaults to 1

             Sort all rows on a given column (optionally skipping table header rows
             by specifiying num_rows_to_skip).

             By default sorting ignores HTML Tags and &nbsp, setting the strip_html parameter to 0
             disables this behaviour.

             By default numeric Sorting ignores non numeric chararacters, setting the strip_non_numeric
             parameter to 0 disables this behaviour.

             You can provide your own pre-sort function, useful for pre-processing the cell contents
             before sorting for example dates.

       getTableRows
           Returns the number of rows in the table.

       getTableCols
           Returns the number of columns in the table.

       getStyle
           Returns the table's style attribute.

   Section Level Methods
       setSectionId ( [tbody|thead|tfoot], section_num, 'id' )
           Sets the id attribute for the section.

       setSectionClass ( [tbody|thead|tfoot], section_num, 'class' )
           Sets the class attribute for the section.

       setSectionStyle ( [tbody|thead|tfoot], section_num, 'style' )
           Sets the style attribute for the section.

       setSectionAlign ( [tbody|thead|tfoot], section_num, [center|right|left] )
           Sets the horizontal alignment for the section.

       setSectionValign ( [tbody|thead|tfoot], section_num, [center|top|bottom|middle|baseline] )
           Sets the vertical alignment for the section.

       setSectionAttr ( [tbody|thead|tfoot], section_num, 'user attribute' )
           Sets a user defined attribute for the cell.  Useful for when HTML::Table hasn't
           implemented a particular attribute yet

   Cell Level Methods
       setCell(row_num, col_num, "content")
           Sets the content of a table cell.  This could be any string, even another table object
           via the getTable method.  If the row and/or column numbers are outside the existing
           table boundaries extra rows and/or columns are created automatically.

       setSectionCell([tbody|thead|tfoot], section_num, row_num, col_num, "content")
           Same as setCell, but able to specify which section to act on.

       setCellAlign(row_num, col_num, [center|right|left])
           Sets the horizontal alignment for the cell.

       setSectionCellAlign([tbody|thead|tfoot], section_num, row_num, col_num,
       [center|right|left])
           Same as setCellAlign, but able to specify which section to act on.

       setCellVAlign(row_num, col_num, [center|top|bottom|middle|baseline])
           Sets the vertical alignment for the cell.

       setSectionCellVAlign([tbody|thead|tfoot], section_num, row_num, col_num,
       [center|top|bottom|middle|baseline])
           Same as setCellVAlign, but able to specify which section to act on.

       setCellWidth(row_num, col_num, [pixels|percentoftable])
           Sets the width of the cell.

       setSectionCellWidth([tbody|thead|tfoot], section_num, row_num, col_num,
       [pixels|percentoftable])
           Same as setCellWidth, but able to specify which section to act on.

       setCellHeight(row_num, col_num, [pixels])
           Sets the height of the cell.

       setSectionCellHeight([tbody|thead|tfoot], section_num, row_num, col_num, [pixels])
           Same as setCellHeight, but able to specify which section to act on.

       setCellHead(row_num, col_num, [0|1])
           Sets cell to be of type head (Ie <th></th>)

       setSectionCellHead([tbody|thead|tfoot], section_num, row_num, col_num, [0|1])
           Same as setCellHead, but able to specify which section to act on.

       setCellNoWrap(row_num, col_num, [0|1])
           Sets the NoWrap attribute of the cell.

       setSectionCellNoWrap([tbody|thead|tfoot], section_num, row_num, col_num, [0|1])
           Same as setCellNoWrap, but able to specify which section to act on.

       setCellBGColor(row_num, col_num, [colorname|colortriplet])
           Sets the background colour for the cell.

       setSectionCellBGColor([tbody|thead|tfoot], section_num, row_num, col_num,
       [colorname|colortriplet])
           Same as setCellBGColor, but able to specify which section to act on.

       setCellRowSpan(row_num, col_num, num_cells)
           Causes the cell to overlap a number of cells below it.  If the overlap number is
           greater than number of cells below the cell, a false value will be returned.

       setSectionCellRowSpan([tbody|thead|tfoot], section_num, row_num, col_num, num_cells)
           Same as setCellRowSpan, but able to specify which section to act on.

       setCellColSpan(row_num, col_num, num_cells)
           Causes the cell to overlap a number of cells to the right.  If the overlap number is
           greater than number of cells to the right of the cell, a false value will be returned.

       setSectionCellColSpan([tbody|thead|tfoot], section_num, row_num, col_num, num_cells)
           Same as setCellColSpan, but able to specify which section to act on.

       setCellSpan(row_num, col_num, num_rows, num_cols)
           Joins the block of cells with the starting cell specified.  The joined area will be
           num_cols wide and num_rows deep.

       setSectionCellSpan([tbody|thead|tfoot], section_num, row_num, col_num, num_rows, num_cols)
           Same as setCellSpan, but able to specify which section to act on.

       setCellFormat(row_num, col_num, start_string, end_string)
           Start_string should be a string of valid HTML, which is output before the cell
           contents, end_string is valid HTML that is output after the cell contents.  This
           enables formatting to be applied to the cell contents.

                   $table->setCellFormat(1, 2, '<b>', '</b>');

       setSectionCellFormat([tbody|thead|tfoot], section_num, row_num, col_num, start_string,
       end_string)
           Same as setCellFormat, but able to specify which section to act on.

       setCellStyle (row_num, col_num, 'css style')
           Sets the cell style attribute.

       setSectionCellStyle([tbody|thead|tfoot], section_num, row_num, col_num, 'css style')
           Same as setCellStyle, but able to specify which section to act on.

       setCellClass (row_num, col_num, 'css class')
           Sets the cell class attribute.

       setSectionCellClass([tbody|thead|tfoot], section_num, row_num, col_num, 'css class')
           Same as setCellClass, but able to specify which section to act on.

       setCellAttr (row_num, col_num, 'user attribute')
           Sets a user defined attribute for the cell.  Useful for when HTML::Table hasn't
           implemented a particular attribute yet

       setSectionCellAttr([tbody|thead|tfoot], section_num, row_num, col_num, 'css class')
           Same as setCellAttr, but able to specify which section to act on.

       setLastCell*
           All of the setCell methods have a corresponding setLastCell method which does not
           accept the row_num and col_num parameters, but automatically applies to the last row
           and last col of the table.

           NB.  Only works on the setCell* methods, not on the setSectionCell* methods.

       getCell(row_num, col_num)
           Returns the contents of the specified cell as a string.

       getSectionCell([tbody|thead|tfoot], section_num, row_num, col_num)
           Same as getCell, but able to specify which section to act on.

       getCellStyle(row_num, col_num)
           Returns cell's style attribute.

       getSectionCellStyle([tbody|thead|tfoot], section_num, row_num, col_num)
           Same as getCellStyle, but able to specify which section to act on.

   Column Level Methods
       addCol("cell 1 content" [, "cell 2 content",  ...])
           Adds a column to the right end of the table.  Assumes if you pass more values than
           there are rows that you want to increase the number of rows.

       addSectionCol([tbody|thead|tfoot], section_num, "cell 1 content" [, "cell 2 content",
       ...])
           Same as addCol, but able to specify which section to act on.

       setColAlign(col_num, [center|right|left])
           Applies setCellAlign over the entire column.

       setSectionColAlign([tbody|thead|tfoot], section_num, col_num, [center|right|left])
           Same as setColAlign, but able to specify which section to act on.

       setColVAlign(col_num, [center|top|bottom|middle|baseline])
           Applies setCellVAlign over the entire column.

       setSectionColVAlign([tbody|thead|tfoot], section_num, col_num,
       [center|top|bottom|middle|baseline])
           Same as setColVAlign, but able to specify which section to act on.

       setColWidth(col_num, [pixels|percentoftable])
           Applies setCellWidth over the entire column.

       setSectionColWidth([tbody|thead|tfoot], section_num, col_num, [pixels|percentoftable])
           Same as setColWidth, but able to specify which section to act on.

       setColHeight(col_num, [pixels])
           Applies setCellHeight over the entire column.

       setSectionColHeight([tbody|thead|tfoot], section_num, col_num, [pixels])
           Same as setColHeight, but able to specify which section to act on.

       setColHead(col_num, [0|1])
           Applies setCellHead over the entire column.

       setSectionColHead([tbody|thead|tfoot], section_num, col_num, [0|1])
           Same as setColHead, but able to specify which section to act on.

       setColNoWrap(col_num, [0|1])
           Applies setCellNoWrap over the entire column.

       setSectionColNoWrap([tbody|thead|tfoot], section_num, col_num, [0|1])
           Same as setColNoWrap, but able to specify which section to act on.

       setColBGColor(row_num, [colorname|colortriplet])
           Applies setCellBGColor over the entire column.

       setSectionColBGColor([tbody|thead|tfoot], section_num, col_num, [colorname|colortriplet])
           Same as setColBGColor, but able to specify which section to act on.

       setColFormat(col_num, start_string, end_sting)
           Applies setCellFormat over the entire column.

       setSectionColFormat([tbody|thead|tfoot], section_num, col_num, start_string, end_sting)
           Same as setColFormat, but able to specify which section to act on.

       setColStyle (col_num, 'css style')
           Applies setCellStyle over the entire column.

       setSectionColStyle([tbody|thead|tfoot], section_num, col_num, 'css style')
           Same as setColStyle, but able to specify which section to act on.

       setColClass (col_num, 'css class')
           Applies setCellClass over the entire column.

       setSectionColClass([tbody|thead|tfoot], section_num, col_num, 'css class')
           Same as setColClass, but able to specify which section to act on.

       setColAttr (col_num, 'user attribute')
           Applies setCellAttr over the entire column.

       setSectionColAttr([tbody|thead|tfoot], section_num, col_num, 'user attribute')
           Same as setColAttr, but able to specify which section to act on.

       setLastCol*
           All of the setCol methods have a corresponding setLastCol method which does not accept
           the col_num parameter, but automatically applies to the last col of the table.

           NB.  Only works on the setCol* methods, not on the setSectionCol* methods.

       getColStyle(col_num)
           Returns column's style attribute.  Only really useful after setting a column's style
           via setColStyle().

       getSectionColStyle([tbody|thead|tfoot], section_num, col_num)
           Same as getColStyle, but able to specify which section to act on.

   Row Level Methods
       addRow("cell 1 content" [, "cell 2 content",  ...])
           Adds a row to the bottom of the first body section of the table.

           Adds a row to the bottom of the table.  Assumes if you pass more values than there are
           columns that you want to increase the number of columns.

       addSectionRow([tbody|thead|tfoot], section_num, "cell 1 content" [, "cell 2 content",
       ...])
           Same as addRow, but able to specify which section to act on.

       delRow(row_num)
           Deletes a row from the first body section of the table.  If -1 is passed as row_num,
           the last row in the section will be deleted.

       delSectionRow([tbody|thead|tfoot], section_num, row_num)
           Same as delRow, but able to specify which section to act on.

       setRowAlign(row_num, [center|right|left])
           Sets the Align attribute of the row.

       setSectionRowAlign([tbody|thead|tfoot], section_num, row_num, [center|right|left])
           Same as setRowAlign, but able to specify which section to act on.

       setRowVAlign(row_num, [center|top|bottom|middle|baseline])
           Sets the VAlign attribute of the row.

       setSectionRowVAlign([tbody|thead|tfoot], section_num, row_num,
       [center|top|bottom|middle|baseline])
           Same as setRowVAlign, but able to specify which section to act on.

       setRowNoWrap(col_num, [0|1])
           Sets the NoWrap attribute of the row.

       setSectionRowNoWrap([tbody|thead|tfoot], section_num, row_num, [0|1])
           Same as setRowNoWrap, but able to specify which section to act on.

       setRowBGColor(row_num, [colorname|colortriplet])
           Sets the BGColor attribute of the row.

       setSectionRowBGColor([tbody|thead|tfoot], section_num, row_num, [colorname|colortriplet])
           Same as setRowBGColor, but able to specify which section to act on.

       setRowStyle (row_num, 'css style')
           Sets the Style attribute of the row.

       setSectionRowStyle([tbody|thead|tfoot], section_num, row_num, 'css style')
           Same as setRowStyle, but able to specify which section to act on.

       setRowClass (row_num, 'css class')
           Sets the Class attribute of the row.

       setSectionRowClass([tbody|thead|tfoot], section_num, row_num, 'css class')
           Same as setRowClass, but able to specify which section to act on.

       setRowAttr (row_num, 'user attribute')
           Sets the Attr attribute of the row.

       setSectionRowAttr([tbody|thead|tfoot], section_num, row_num, 'user attribute')
           Same as setRowAttr, but able to specify which section to act on.

       setRCellsWidth(row_num, [pixels|percentoftable])
       setRowWidth(row_num, [pixels|percentoftable])  ** Deprecated **
           Applies setCellWidth over the entire row.

       setSectionRCellsWidth([tbody|thead|tfoot], section_num, row_num, [pixels|percentoftable])
       setSectionRowWidth([tbody|thead|tfoot], section_num, row_num, [pixels|percentoftable])
       ** Deprecated **
           Same as setRowWidth, but able to specify which section to act on.

       setRCellsHeight(row_num, [pixels])
       setRowHeight(row_num, [pixels])   ** Deprecated **
           Applies setCellHeight over the entire row.

       setSectionRCellsHeight([tbody|thead|tfoot], section_num, row_num, [pixels])
       setSectionRowHeight([tbody|thead|tfoot], section_num, row_num, [pixels])  ** Deprecated **
           Same as setRowHeight, but able to specify which section to act on.

       setRCellsHead(row_num, [0|1])
       setRowHead(row_num, [0|1])  ** Deprecated **
           Applies setCellHead over the entire row.

       setSectionRCellsHead([tbody|thead|tfoot], section_num, row_num, [0|1])
       setSectionRowHead([tbody|thead|tfoot], section_num, row_num, [0|1])  ** Deprecated **
           Same as setRowHead, but able to specify which section to act on.

       setRCellsFormat(row_num, start_string, end_string)
       setRowFormat(row_num, start_string, end_string)  ** Deprecated **
           Applies setCellFormat over the entire row.

       setSectionRCellsFormat([tbody|thead|tfoot], section_num, row_num, start_string,
       end_string)
       setSectionRowFormat([tbody|thead|tfoot], section_num, row_num, start_string, end_string)
       ** Deprecated **
           Same as setRowFormat, but able to specify which section to act on.

       setLastRow*
           All of the setRow methods have a corresponding setLastRow method which does not accept
           the row_num parameter, but automatically applies to the last row of the table.

           NB.  Only works on the setRow* methods, not on the setSectionRow* methods.

       getRowStyle(row_num)
           Returns row's style attribute.

       getSectionRowStyle([tbody|thead|tfoot], section_num, row_num)
           Same as getRowStyle, but able to specify which section to act on.

   Output Methods
       getTable
           Returns a string containing the HTML representation of the table.

           The same effect can also be achieved by using the object reference in a string scalar
           context.

           For example...

                   This code snippet:

                           $table = new HTML::Table(2, 2);
                           print '<p>Start</p>';
                           print $table->getTable;
                           print '<p>End</p>';

                   would produce the same output as:

                           $table = new HTML::Table(2, 2);
                           print "<p>Start</p>$table<p>End</p>";

       print
           Prints HTML representation of the table to STDOUT

CLASS VARIABLES

HISTORY

       This module was originally created in 1997 by Stacy Lacy and whose last version was
       uploaded to CPAN in 1998.  The module was adopted in July 2000 by Anthony Peacock in order
       to distribute a revised version.  This adoption took place without the explicit consent of
       Stacy Lacy as it proved impossible to contact them at the time.  Explicit consent for the
       adoption has since been received.

AUTHOR

       Anthony Peacock, a.peacock@chime.ucl.ac.uk Stacy Lacy (Original author)

CONTRIBUTIONS

       Douglas Riordan <doug.riordan@gmail.com> For get methods for Style attributes.

       Jay Flaherty, fty@mediapulse.com For ROW, COL & CELL HEAD methods. Modified the new method
       to allow hash of values.

       John Stumbles, john@uk.stumbles.org For autogrow behaviour of setCell, and allowing
       alignment specifications to be case insensitive

       Arno Teunisse, Arno.Teunisse@Simac.nl For the methods adding rules, styles and table
       alignment attributes.

       Ville Skyttä, ville.skytta@iki.fi For general fixes

       Paul Vernaza, vernaza@stwing.upenn.edu For the setLast... methods

       David Link, dvlink@yahoo.com For the sort method

       Tommi Maekitalo, t.maekitalo@epgmbh.de For adding the 'head' parameter to the new method
       and for adding the initialisation from an array ref to the new method.

       Chris Weyl, cweyl@alumni.drew.edu For adding the even/odd row class support.

COPYRIGHT

       Copyright (c) 2000-2007 Anthony Peacock, CHIME.  Copyright (c) 1997 Stacy Lacy

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

SEE ALSO

       perl(1), CGI(3)