NAME

       Class::CSV - Class based CSV parser/writer

SYNOPSIS

         use Class::CSV;

         my $csv = Class::CSV->parse(
           filename => 'test.csv',
           fields   => [qw/item qty sub_total/]
         );

         foreach my $line (@{$csv->lines()}) {
           $line->sub_total('$'. sprintf("%0.2f", $line->sub_total()));

           print 'Item:     '. $line->item(). "\n".
                 'Qty:      '. $line->qty(). "\n".
                 'SubTotal: '. $line->sub_total(). "\n";
         }

         my $cvs_as_string = $csv->string();

         $csv->print();

         my $csv = Class::CSV->new(
           fields         => [qw/userid username/],
           line_separator => "\r\n";
         );

         $csv->add_line([2063, 'testuser']);
         $csv->add_line({
           userid   => 2064,
           username => 'testuser2'
         });

DESCRIPTION

       This module can be used to create objects from CSV files, or to create CSV files from
       objects. Text::CSV_XS is used for parsing and creating CSV file lines, so any limitations
       in Text::CSV_XS will of course be inherant in this module.

   EXPORT
       None by default.

METHOD

   CONSTRUCTOR
       parse
           the parse constructor takes a hash as its paramater, the various options that can be
           in this hash are detailed below.

           Required Options
               •   fields - an array ref containing the list of field names to use for each row.
                   there are some reserved words that cannot be used as field names, there is no
                   checking done for this at the moment but it is something to be aware of. the
                   reserved field names are as follows: "string", "set", "get". also field names
                   cannot contain whitespace or any characters that would not be allowed in a
                   method name.

           Source Options (only one of these is needed)
               •   filename - the path of the CSV file to be opened and parsed.

               •   filehandle - the file handle of the CSV file to be parsed.

               •   objects - an array ref of objects (e.g. Class::DBI objects). for this to work
                   properly the field names provided in fields needs to correspond to the field
                   names of the objects in the array ref.

               •   classdbi_objects - depreciated use objects instead - using classdbi_objects
                   will still work but its advisable to update your code.

           Optional Options
               •   line_separator - the line seperator to be included at the end of every line.
                   defaulting to "\n" (unix carriage return).

       new the new constructor takes a hash as its paramater, the same options detailed in parse
           apply to new however no Source Options can be used. this constructor creates a blank
           CSV object of which lines can be added via add_line.

   ACCESSING
       lines
           returns an array ref containing objects of each CSV line (made via Class::Accessor).
           the field names given upon construction are available as accessors and can be set or
           get. for more information please see the notes below or the perldoc for
           Class::Accessor. the lines accessor is also able to be updated/retrieved in the same
           way as individual lines fields (examples below).

           Example
               retrieving the lines:

                 my @lines = @{$csv->lines()};

               removing the first line:

                 pop @lines;

                 $csv->lines(\@lines);

               sorting the lines:

                 @lines = sort { $a->userid() <=> $b->userid() } @lines:

                 $csv->lines(\@lines);

               sorting the lines (all-in-one way):

                 $csv->lines([ sort { $a->userid() <=> $b->userid() } @{$csv->lines()} ]);

           Retrieving a fields value
               there is two ways to retrieve a fields value (as documented in Class::Accessor).
               firstly you can call the field name on the object and secondly you can call "get"
               on the object with the field name as the argument (multiple field names can be
               specified to retrieve an array of values). examples are below.

                 my $value = $line->test();

               OR

                 my $value = $line->get('test');

               OR

                 my @values = $line->get(qw/test test2 test3/);

           Setting a fields value
               setting a fields value is simmilar to getting a fields value. there are two ways
               to set a fields value (as documented in Class::Accessor).  firstly you can simply
               call the field name on the object with the value as the argument or secondly you
               can call "set" on the object with a hash of fields and their values to set (this
               isn't standard in Class::Accessor, i have overloaded the "set" method to allow
               this). examples are below.

                 $line->test('123');

               OR

                 $line->set( test => '123' );

               OR

                 $line->set(
                   test  => '123',
                   test2 => '456'
                 );

           Retrieving a line as a string
               to retrieve a line as a string simply call "string" on the object.

                 my $string = $line->string();

       new_line
           returns a new line object, this can be useful for to "splice" a line into lines (see
           example below). you can pass the values of the line as an ARRAY ref or a HASH ref.

           Example
                 my $line = $csv->new_line({ userid => 123, domainname => 'splicey.com' });
                 my @lines = $csv->lines();
                 splice(@lines, 1, 0, $line);

               OR

                 splice(@{$csv->lines()}, 1, 0, $csv->new_line({ userid => 123, domainname => 'splicey.com' }));

       add_line
           adds a line to the lines stack. this is mainly useful when the new constructor is used
           but can of course be used with any constructor. it will add a new line to the end of
           the lines stack. you can pass the values of the line as an ARRAY ref or a HASH ref.
           examples of how to use this are below.

           Example
                 $csv->add_line(['house', 100000, 4]);

                 $csv->add_line({
                   item     => 'house',
                   cost     => 100000,
                   bedrooms => 4
                 });

   OUTPUT
       string
           returns the object as a string (CSV file format).

       print
           calls "print" on string (prints the CSV to STDOUT).

SEE ALSO

       Text::CSV_XS, Class::Accessor

AUTHOR

       David Radunz, <david@boxen.net>

COPYRIGHT AND LICENSE

       Copyright 2004 by David Radunz

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