NAME

Data::Tabular::Dumper - Seamlessly dump tabular data to XML, CSV and XLS.

SYNOPSIS

    use Data::Tabular::Dumper;
    use Data::Tabular::Dumper::Excel;
    use Data::Tabular::Dumper::XML;

    # ....read in access_log and put data into $month

    $date=strftime('%Y%m%d', localtime);

    # output parsed access_log data in XML and XLS format
    my $dumper=Data::Tabular::Dumper->open(XML=>["$date.xml",
                                                 "access", "page"
                                                ],
                                            Excel=>["$date.xls"]);
    # what each field is called
    $dumper->fields([qw(uri hits bytes)]);

    # now output the data
    foreach my $URL (@$month) {
        $dumper->write($URL);
    }

    # sane shutdown
    $dumper->close();

This would produce the following XML :

    <?xml version="1.0" encoding="iso-8859-1"?>
    <access>
      <page>
        <uri>/index.html</uri>
        <hits>4000</hits>
        <bytes>5123412</bytes>
      </page>
      <page>
        <uri>/something/index.html</uri>
        <hits>400</hits>
        <bytes>51234</bytes>
      </page>
      <!-- more page tags here -->
    </access>

And an Excel file that looks roughly like this :

    uri                   hits     bytes
    /index.html            4000    5123412
    /something/index.html   400      51234
    ....

DESCRIPTION

Data::Tabular::Dumper aims to make it easy to turn tabular data into as many file formats as possible. It is useful when you need to provide data that folks will then process further. Because you don't really know what format they want to use, you can provide as many as possible, and let them choose which they want.

Data::Tabular::Dumper METHODS

open(%writers)

Creates the Data::Tabular::Dumper object. %writers is a hash that contains the the package of the object (as keys) and the parameters for it's new() function (as values). As a convienience, the Data::Tabular::Dumper::* modules can be specified as XML, Excel or CSV. The above exampel would create 2 objects, via the following calls :

    Data::Tabular::Dumper::XML->new(["$date.xml","users", "user"]);
    Data::Tabular::Dumper::Excel->new(["$date.xls"]);

You can also create your own packages. See WRITER OBJECTS below.

close()

Does an orderly close of all the writers. Some of the writers need this to clean up data and write file footers properly. Note that DESTROY also calls close.

fields($fieldref)

Sets the column headers to the values in the arrayref $fieldref. Calling this "fields" might be misdenomer. Field headers are often concidered a "special" row of data.

write($dataref)

Writes a row of data from the arrayref $dataref.

WRITER OBJECTS

An object must implement 4 methods for it to be useable by Data::Tabular::Dumper.

open($package, $p)

Create the object. $p is the data handed to Data::Tabular::Dumper->open (often an arrayref).

close()

Do any clean up necesssary, like closing the file.

fields($fieldref)

$fieldref is an arrayref containing all the field headings.

write($dataref)

$dataref is an arrayref containing a row of data to be output.

PREDEFINED OBJECTS

Data::Tabular::Dumper::XML

Produces an XML file of the tabular data.

open($package, [$file, $top, $record])

Opens the file $file. The top element is $top and defaults to DATA. Each record is a $record element and defaults to RECORD.

fields($fieldref)

Define the tag for each data value.

write($dataref)

Output a record. Each item in the arrayref $dataref becomes an element named by the corresponding item set in fields(). If there are more items in $dataref then fields, the last field name is duplicated. Example :

    $xml=Data::Tabular::Dumper::XML->open(['something.xml']);
    $xml->fields([qw(foo bar)]);
    $xml->write([0..5]);

Would produce the following XML :

    <?xml version="1.0" encoding="iso-8859-1"?>
    <DATA>
      <RECORD>
        <foo>0</foo>
        <bar>1</bar>
        <bar>2</bar>
        <bar>3</bar>
        <bar>4</bar>
        <bar>5</bar>
      </RECORD>
    </DATA>

Data::Tabular::Dumper::CSV

Produces an CSV file of the tabular data.

open($package, [$file, $CSVattribs])

Opens the file $file and creates a Text::CSV_XS object using the attributes in $CSVattribs

Example :

    $xml=Data::Tabular::Dumper::CSV->open(['something.xml', 
                                          {eol=>"\n", binary=>1}]);
    $xml->fields([qw(foo bar)]);
    $xml->write("me,you", "other");

Would produce the following CSV :

    foo,bar
    "me,you",other

Data::Tabular::Dumper::Excel

Produces an Excel workbook of the tabular data.

open($package, [$file])

Creates the workbook $file.

fields($fieldref)

Creates a row in bold from the elements in the arrayref $fieldref.

AUTHOR

Philip Gwyn <perl at pied.nu>

SEE ALSO

Text::CSV(3), Spreadsheet::WriteExcel(3), XML, perl(1).