/ 
IO-StructuredOutput-1.008
River stage zero No dependents
/ IO::StructuredOutput

NAME

IO::StructuredOutput - Perl OO extension to ease creation of structured data output (html tables, csv files, excel spreadsheets, etc)

SYNOPSIS

use IO::StructuredOutput;
my $io_so = IO::StructuredOutput->new;
$io_so->format('xls'); # or 'html' or 'csv'

# optionally setup some styles
$io_so->defaultstyle( { bold => 1,
                        font => 'arial',
                        underline => 1 } );
my $style_italic = $io_so->addstyle( { italic => 1 } );
my $style_align = $io_so->addstyle( { align => 'right',
                                      bg_color => '24#AAAAAA',
                                      color => '25#FF0000' } );

my $ws = $io_so->addsheet('some title');
my $number_of_sheets_currently = $io_so->sheetcount();
my $current_sheet_name = $ws->name();

my $ws2 = $io_so->addsheet('new page');

# add row with default styles
$ws->addrow( ['some data','another cell','etc'] );

# add row, with one cell that spans multiple columns
$ws->addrow( [ ['data that spans 2 cells/columns',''], 'third cell'] );

# set the style for the whole row
$ws2->addrow( ['data','in','the','other','sheet'], $style_italic );

# different style for each cell (undef to use default style)
$ws2->addrow( ['more','data','in','this','sheet'],
              [$style_italic, $style_align, undef,
               $style_italic, $style_align ] );

my $rows_added_to_first_sheet = $ws->rowcount();

my $output = $io_so->output();

ABSTRACT

IO::StructuredOutput provides a high level abstraction from creating output that is formatted in a structured way (like in tables). Currently, excel, csv, and html table output are supported.

csv data is returned in a zip archive
xls data is returned as an excel spreadsheet
html data is returned as plain text w/ html formatting

DESCRIPTION

Provides a high level abstraction from creating output that is formatted in a structured way (like in tables). Currently, excel, csv, and html table output are supported.

REQUIRES

IO::Scalar
Spreadsheet::WriteExcel
Archive::Zip
Text::CSV_XS

EXPORT

None.

METHODS

$io_so = IO::StructuredOutput->new;

This creates a new IO::StructuredOutput object.

$io_so->format( $output_format );

Sets the output format for this instance. Valid output formats are 'html', 'csv', or 'xls', for HTML, Comma Separated Values files in a Zip archive, or an Excel spreadsheet respectively. Defaults to 'html'.

MUST be called before any other methods if using anything but 'html'.

$io_so->defaultstyle( \%options );

This method sets the default style for the output. For 'csv' format, it's basically ignored. Uses the same options as addstyle().

$style = $io_so->addstyle( \%options );

Create a new Style object. The following options are supported:

font => $fontname

$fontname can be anything you want, but it's suggested you use font names that will likely be available on the end users systems, such as 'arial', 'helvetica', 'Times New Roman', etc.

size => $fontsize

$fontsize should be an integer value.

bg_color => "$index#$hex"
color => "$index#$hex"

bg_color set's the cells background color.

color set's the font color.

$index should be a number between 8 and 63 inclusively (a limit imposed by excel output). For each unique color passed into an IO::StructuredOutput instance, a unique index number should be used. The index is ignored in csv and html output formats.

$hex should consist of three 2 character hex numbers (ie. FFFFFF for white, or 000000 for black). Order is red, green, blue.

bold => $bool
italic => $bool
underline => $bool
num_format => $bool
text_wrap => $bool
border => $bool

Set to true (1) to turn option on, or false (0) to turn if off.

num_format, text_wrap, and border are currently only effective under the 'xls' format.

align => $horizontal_alignment

Sets the alignment of text in the cells. 'horizontal alignment' should be one of 'center','left', or 'right'

valign => $vertical_alignment

Sets the alignment of text in the cells. 'vertical alignment' should be one of 'top','center', or 'bottom'

$ws = $io_so->addsheet($title);

Creates a new Sheet object. Adds a new page/sheet/file/table as appropriate for the format being used. $title is optional, but if supplied it must be unique the the IO::StructuredOutput instance, and will be truncated to 31 characters (a limit of Excel spreadsheets).

$number_of_sheets_currently = $io_so->sheetcount();

Returns the current number of pages/sheets/files/tables in the document.

$current_sheet_name = $ws->name();

Returns the name (title) of the sheet object.

$ws->addrow( \@data );
$ws->addrow( \@data, $style );
$ws->addrow( \@data, \@styles );
$ws->addrow( [$data1, [$data_for_two_columns,undef] ], \@styles );

Adds a row of cells to the page/sheet.

Each element of \@data represents one cell column that will be filled in.

If an item in \@data is an array referance, the first element of that array referance will be used to fill a cell that spans as many columns as there are elements in that array referance. In other words, the resulting row from the last example above would consist of the first column being filled with $data1, and $data_for_two_columns filling a cell that spans the two columns next to it.

If $style option is a scalar, that style will be applied to every cell in that row.

If $style is an array referance, it must contain the same number of elements as the \@data passed in. $style->[0] will be applied the the data in the first cell which will be filed with the data from $data->[0].

$rows_added_to_first_sheet = $ws->rowcount();

Returns the number of rows added to that Sheet object.

$output = $io_so->output();

  • Build the datafile, and returns a referance to it.

  • It can be accessed by dereferancing it, like so:

  • A document of 'xls' format will return an Excel document.

  • A document of 'html' format will return an HTML page (without header|footer) as a scalar variable of plain text.

  • A document of 'csv' format will return a Zip file consisting of one file (with it's name set to the $title of the page) for each page added.

SEE ALSO

IO::Scalar
Spreadsheet::WriteExcel
Archive::Zip
Text::CSV_XS

AUTHOR

Josh Miller, <jmiller@purifieddata.net>

COPYRIGHT AND LICENSE

Copyright 2003 by Josh Miller

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