- NAME
- SYNOPSIS
- DESCRIPTION
- BUGS
- SEE ALSO

# NAME

ActiveState::Table - Simple table class

# SYNOPSIS

     $t = ActiveState::Table->new;
     $t->add_row({ a => 1, b => 2 });
     print $t->as_csv;

# DESCRIPTION

Instances of the `ActiveState::Table` class represent a 2 dimensional table of fields (or columns if you wish) and rows. The fields are ordered and have case-sensitive names. The rows are numbered.

The following methods are provided:

$t = ActiveState::Table->new

  This creates a new empty table object.

$t->fields

  This returns the current field names. In scalar context it returns the number of fields.

$t->rows

  This returns the current rows. Each row is returned as reference to an array of values in the same order as the fields. The array might be shorter than the number of fields, when the trailing values are `undef`.

  In scalar context it returns the number of rows in the table.

$t->fetchrow( $index )

  This returns the given row. An array reference is returned in scalar context. The array might be shorter than the number of fields, when the trailing values are `undef`.

  In list context the values are returned one by one. There will be as many values as there are fields in the table. Some values might be `undef`.

  If there is no row with the given $index, then `undef` is returned in scalar context and the empty list in list context.

$t->fetchrow_arrayref( $index )

  Same as fetchrow() but will return an array reference even in list context.

$t->fetchrow_hashref( $index )

  This returns the given row. A hash reference is returned with keys corresponding to the field names and the values corresponding to the given row. The values might be `undef`, but a key for all the fields will exist.

  If there is no row with the given $index, then `undef` is returned.

$t->add_field( $field )

  This adds another field to the table. The field must be a string. If the field already exists it is not added again, and the add_field() call does nothing.

  There is no return value.

$t->add_row( $row )

  This adds another row to the table. The row must currently be a hash reference. If the hash contains new fields they are added automatically in sorted order. To enforce an order add the fields before adding rows.

  There is no return value.

$t->add_sep
$t->add_sep( $index )

  This adds a separator to the table, shown as a horizonal line in the as_box() output. If $index is provided the separator will appear after the given row, otherwise the separator will appear after last row added.

$t->sort( $comparator )

  This will sort the rows of the table using the given $comparator function to compare elements. The $comparator is called as for perl's builtin sort function. References to the rows to compare is available in `$::a` and `$::b` in the form returned by `$t->fetchrow_arrayref`.

$t->as_box( %options )

  This formats the table as text and returns it. The following options might be provided as key/value pairs:

         name                 | default
         ---------------------+----------
         align                | {}
         null                 | "NULL"
         show_header          | 1
         show_trailer         | 1
         box_chars            | "ascii"
         max_width            | undef
         ---------------------+----------

  The `align` option is a hash with field names as keys and the strings "left", "right" or "center" as values. Alignment for fields not found in this hash is "left".

  The `box_chars` is either the name of a box drawing scheme or the 11 characters to use; starting with the upper left corner and going down one row at a time to the lower right corner, and finally the horizontal and vertical line character. The current named schemes are "dos" and "unicode".

  If `max_width` is specified it limits how wide the box can get. The longest fields are truncated until the box is no wider than the given number of characters. Truncated fields are shown with trailing "..." or "+" marker.

$t->as_csv( %options )

  This formats the table as a CSV file ("comma-separated-values") and returns it. The following options might be provided as key/value pairs:

         name                 | default
         ---------------------+----------
         field_separator      | ","
         row_separator        | "\n"
         null                 | "NULL"
         show_header          | 1
         ---------------------+----------

  Fields that contains the `field_separator` or the quote character will be quoted.

# BUGS

none.

# SEE ALSO

RFC 4180 and http://en.wikipedia.org/wiki/Comma-separated_values