Class::CSV - Class based CSV parser/writer

       David Radunz, <david@boxen.net>

       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.

perl v5.38.2                                       2024-07-11                                           CSV(3pm)

       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.

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

           RequiredOptions
               •   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.

           SourceOptions (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.

           OptionalOptions
               •   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 SourceOptions can be used. this constructor creates a blank CSV object of which lines can
           be added via add_line.

   ACCESSINGlines
           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()} ]);

           Retrievingafieldsvalue
               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/);

           Settingafieldsvalue
               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'
                 );

           Retrievingalineasastring
               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
                 });

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

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

       Class::CSV - Class based CSV parser/writer

       Text::CSV_XS, Class::Accessor

         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'
         });