NAME

Table - provide a consistent library for CIToolkit programs to display information in a 2D table.


MODULE

base


SYNOPSIS

  use Table;
  my $t=Table->new(\@nodes_to_tableize);
    or
  my $t=Table->new(\@nodes_to_tableize, { small_headers => 1,
                                          colsort => 'myrinet',
                                          vertical_col_headers =>1
                                         } );
  $t->transpose;
  $t->small_headers(1);
  $t->vertical_col_headers(1);
  $t->space_between_columns(0); # default is one
  $t->section_height(8);
  $t->section_width(0); # default is zero anyway...
  $t->print_table(\%data_hash);
    or
  for $h ($t->row_headers) {
        print "$h | ", join(' ',$t->row_by_key($h)), "\n";
  }
  print "\nLeftovers:\n", join(' ',$t->leftovers);

This synopsis only lists the major methods, see METHODS sections below for more details.


DESCRIPTION

This package provides a consistent library for CIToolkit programs that want to display information in a 2-dimentional table (grid, mesh, etc.) This task is accomplished by parsing and sorting a list of things (hostnames, objectnames, etc.) and sorting them using routines in the Local.pm module.


METHODS

new - create a new table
  my $t=Table->new(\@nodes_to_tableize);

This method accepts a reference to a list of names to parse, and constructs the table.

The sort algorithms that new uses to construct the table can be changed by using the colsort and rowsort helper methods like this:

  my $t=Table->new(\@nodes_to_tableize, {
                        colsort => 'myrinet',
                        rowsort => 'reverse'
                        } );

In this case, instead of using Local::table_colsort() and Local::table_rowsort(), new will use Local::table_colsort_myrinet() and Local::table_rowsort_reverse(). If either does not exist, then the standard sort routine will be used. If that does not exist either, then an internal generic sort will be used.

The methods listed below that alter how print_table works can also be specified in new in the same way as colsort and rowsort. For example, to set options to get a compressed table display:

  my $t=Table->new(\@nodes_to_tableize, {
                        small_headers => 1,
                        vertical_col_headers => 1,
                        space_between_columns => 0
                        } );

Methods to alter the table AFTER it has been constructed:

transpose - flip the table on it's side
  $t->transpose;

This method exchanges the row headers for column headers, the row and column header size values, and the routines for shortening the row and column headers. Most importantly, it transposes the data matrix,

Do-it-all output method:

print_table - display the table to STDOUT.
  $t->print_table(\%data_hash);

This method takes the table as currently formatted and prints it to STDOUT. The only argument is a reference to a hash which should contain a lookup of the data to display for each node. The keys of this hash are the same as the values in the array passed to new, although not all values need to exist, as print_table will fill in missing entries with blanks or unknown_char. The values of the hash are what actually get printed.

Get/Set methods to alter how print_table displays the table:

small_headers - mash the col and row headers to save space
  $t->small_headers(1);
  $current_setting = $t->small_headers();

Set this to 1 to use the table_mash_row and table_mash_col routines in Local.pm to shorten the column and row headers. Set it to 0 (default) to use the full header string. Calling small_headers with no arguments just returns the current setting.

If table_mash_row or table_mash_col do not exist in Local.pm, then an internal generic routine will be used to remove non-alpha-numeric characters.

vertical_col_headers - print column headers vertically
  $t->vertical_col_headers(1);
  $current_setting = $t->vertical_col_headers();

Set this to 1 to turn the column headers 90 degrees to take up less screen width. Set it to 0 (default) to simply print horizontally. Calling vertical_col_headers with no arguments just returns the current setting.

space_between_columns - number of spaces between columns
  $t->space_between_columns(0);
  $t->space_between_columns(3);
  $current_setting = $t->space_between_columns();

This method changes the number of spaces that print_table will use between columns. Default is 1 space. You may want to set it to 0 to save screen space if all your data will be single characters. (Zero spaces and multi-character data can be hard to read.) Calling space_between_columns with no arguments just returns the current setting.

section_width - how many columns to print between dividers
  $t->section_width(8);
  $t->section_width(0);  # no dividers
  $current_setting = $t->section_width();

This method changes the number of columns that will be printed between each divider. If set to 0 (default) then no dividers will be printed.

section_height - how many rows to print between dividiers
  $t->section_height(8);
  $t->section_height(0);  # no dividers
  $current_setting = $t->section_height();

This method changes the number of rows that will be printed between each divider. If set to 0 (default) then no dividers will be printed.

missing_char - for nodes not in the initial list
  $t->missing_char("!");
  $current_setting = $t->missing_char();

If, when displaying the table, print_table finds a location for which no nodename is defined (it wasn't in the list initially passed to new) it can insert a character defined with missing_char.

unknown_char - for nodes not in the data hash
  $t->unknown_char("?");
  $current_setting = $t->unknown_char();

If, when displaying the table, print_table finds a location for which a nodename is defined, but there is no data for it in the data hash passed to print_table, it can insert a character defined with unknown_char.

Methods to help with do-it-yourself output:

These are fairly self explanatory...

num_rows - number of rows in the table
  $n = $t->numrows();
num_cols - number of columns in the table
  $n = $t->numcols();
row_headers - array of row headers
  @headers = $t->row_headers();
col_headers - array of column headers
  @headers = $t->col_headers();
row_header - row header at given index
  $header = $t->row_header(4);
col_header - column header at given index
  $header = $t->col_header(0);
row_by_index - array of nodenames in row with given index
  @nodes_in_row = $t->row_by_index(23);
col_by_index - array of nodenames in column with given index
  @nodes_in_col = $t->col_by_index(7);
row_by_key - array of nodenames in row with given header
  @nodes_in_row = $t->row_by_key("n-24");
col_by_key - array of nodenames in column with given header
  @nodes_in_col = $t->col_by_key("r-10");
node_at_row_col - nodename with given row and column indexes
  $name = $t->node_at_row_col($rownum, $colnum);

Other random methods:

missing - list nodes not in original array
  @nodenames = $t->missing();

If, when displaying the table, print_table finds a location for which no nodename is defined (it wasn't in the list initially passed to new) it will try to recreate the nodename with the table_build_name routine in Local.pm, and store it in a list. missing can be used to retrieve this list.

unknown - list nodes not in data hash
  @nodenames = $t->unknown();

If, when displaying the table, print_table finds a location for which a nodename is defined, but there is no data for it in the data hash passed to print_table, it will store the nodename in a list, which can then be retrieved with unknown.

leftovers - list nodes that couldn't be put on the table
  @nodenames = $t->leftovers();

If, when generating the table, new is unable to parse a nodename and assign it to a row and column, it will store the name in a list, which can then be retrieved with leftovers. Usually, admin nodes with a different naming convention end up in this list and can be ignored. However, it is usually a good idea to check it.


METHODS IN LOCAL.PM

Required methods:

table_row_col - parse the nodename into row and column headers
  ($rowheader, $colheader) = Local::table_row_col($devname);
table_build_name - construct the nodename from row and col headers
  $devname = Local::table_build_name($rowheader, $colheader);

Optional methods:

table_rowsort - sort the row headers
  @sorted = table_rowsort(@row_headers);
table_colsort - sort the column headers
  @sorted = table_colsort(@col_headers);
table_rowsort_YOUR_NAME_HERE - alternative to table_rowsort
  @sorted = table_rowsort_myrinet(@row_headers);
table_colsort_YOUR_NAME_HERE - alternative to table_colsort
  @sorted = table_colsort_reverse(@col_headers);
table_mash_row - munge a row header to save space
  $small = table_mash_row($header);
table_mash_col - munge a column header to save space
  $small = table_mash_col($header);


SEE ALSO

Local.pm - contains site specific parsing and sorting routines

Util.pm - getalpha() is useful for constructing keys in your table