1CSV(3)                User Contributed Perl Documentation               CSV(3)
2
3
4

NAME

6       Class::CSV - Class based CSV parser/writer
7

SYNOPSIS

9         use Class::CSV;
10
11         my $csv = Class::CSV->parse(
12           filename => 'test.csv',
13           fields   => [qw/item qty sub_total/]
14         );
15
16         foreach my $line (@{$csv->lines()}) {
17           $line->sub_total('$'. sprintf("%0.2f", $line->sub_total()));
18
19           print 'Item:     '. $line->item(). "\n".
20                 'Qty:      '. $line->qty(). "\n".
21                 'SubTotal: '. $line->sub_total(). "\n";
22         }
23
24         my $cvs_as_string = $csv->string();
25
26         $csv->print();
27
28         my $csv = Class::CSV->new(
29           fields         => [qw/userid username/],
30           line_separator => "\r\n";
31         );
32
33         $csv->add_line([2063, 'testuser']);
34         $csv->add_line({
35           userid   => 2064,
36           username => 'testuser2'
37         });
38

DESCRIPTION

40       This module can be used to create objects from CSV files, or to create
41       CSV files from objects. Text::CSV_XS is used for parsing and creating
42       CSV file lines, so any limitations in Text::CSV_XS will of course be
43       inherant in this module.
44
45   EXPORT
46       None by default.
47

METHOD

49   CONSTRUCTOR
50       parse
51           the parse constructor takes a hash as its paramater, the various
52           options that can be in this hash are detailed below.
53
54           Required Options
55               ·   fields - an array ref containing the list of field names to
56                   use for each row.  there are some reserved words that
57                   cannot be used as field names, there is no checking done
58                   for this at the moment but it is something to be aware of.
59                   the reserved field names are as follows: "string", "set",
60                   "get". also field names cannot contain whitespace or any
61                   characters that would not be allowed in a method name.
62
63           Source Options (only one of these is needed)
64               ·   filename - the path of the CSV file to be opened and
65                   parsed.
66
67               ·   filehandle - the file handle of the CSV file to be parsed.
68
69               ·   objects - an array ref of objects (e.g. Class::DBI
70                   objects). for this to work properly the field names
71                   provided in fields needs to correspond to the field names
72                   of the objects in the array ref.
73
74               ·   classdbi_objects - depreciated use objects instead - using
75                   classdbi_objects will still work but its advisable to
76                   update your code.
77
78           Optional Options
79               ·   line_separator - the line seperator to be included at the
80                   end of every line. defaulting to "\n" (unix carriage
81                   return).
82
83       new the new constructor takes a hash as its paramater, the same options
84           detailed in parse apply to new however no Source Options can be
85           used. this constructor creates a blank CSV object of which lines
86           can be added via add_line.
87
88   ACCESSING
89       lines
90           returns an array ref containing objects of each CSV line (made via
91           Class::Accessor). the field names given upon construction are
92           available as accessors and can be set or get. for more information
93           please see the notes below or the perldoc for Class::Accessor. the
94           lines accessor is also able to be updated/retrieved in the same way
95           as individual lines fields (examples below).
96
97           Example
98               retrieving the lines:
99
100                 my @lines = @{$csv->lines()};
101
102               removing the first line:
103
104                 pop @lines;
105
106                 $csv->lines(\@lines);
107
108               sorting the lines:
109
110                 @lines = sort { $a->userid() <=> $b->userid() } @lines:
111
112                 $csv->lines(\@lines);
113
114               sorting the lines (all-in-one way):
115
116                 $csv->lines([ sort { $a->userid() <=> $b->userid() } @{$csv->lines()} ]);
117
118           Retrieving a fields value
119               there is two ways to retrieve a fields value (as documented in
120               Class::Accessor). firstly you can call the field name on the
121               object and secondly you can call "get" on the object with the
122               field name as the argument (multiple field names can be
123               specified to retrieve an array of values). examples are below.
124
125                 my $value = $line->test();
126
127               OR
128
129                 my $value = $line->get('test');
130
131               OR
132
133                 my @values = $line->get(qw/test test2 test3/);
134
135           Setting a fields value
136               setting a fields value is simmilar to getting a fields value.
137               there are two ways to set a fields value (as documented in
138               Class::Accessor).  firstly you can simply call the field name
139               on the object with the value as the argument or secondly you
140               can call "set" on the object with a hash of fields and their
141               values to set (this isn't standard in Class::Accessor, i have
142               overloaded the "set" method to allow this). examples are below.
143
144                 $line->test('123');
145
146               OR
147
148                 $line->set( test => '123' );
149
150               OR
151
152                 $line->set(
153                   test  => '123',
154                   test2 => '456'
155                 );
156
157           Retrieving a line as a string
158               to retrieve a line as a string simply call "string" on the
159               object.
160
161                 my $string = $line->string();
162
163       new_line
164           returns a new line object, this can be useful for to "splice" a
165           line into lines (see example below). you can pass the values of the
166           line as an ARRAY ref or a HASH ref.
167
168           Example
169                 my $line = $csv->new_line({ userid => 123, domainname => 'splicey.com' });
170                 my @lines = $csv->lines();
171                 splice(@lines, 1, 0, $line);
172
173               OR
174
175                 splice(@{$csv->lines()}, 1, 0, $csv->new_line({ userid => 123, domainname => 'splicey.com' }));
176
177       add_line
178           adds a line to the lines stack. this is mainly useful when the new
179           constructor is used but can of course be used with any constructor.
180           it will add a new line to the end of the lines stack. you can pass
181           the values of the line as an ARRAY ref or a HASH ref. examples of
182           how to use this are below.
183
184           Example
185                 $csv->add_line(['house', 100000, 4]);
186
187                 $csv->add_line({
188                   item     => 'house',
189                   cost     => 100000,
190                   bedrooms => 4
191                 });
192
193   OUTPUT
194       string
195           returns the object as a string (CSV file format).
196
197       print
198           calls "print" on string (prints the CSV to STDOUT).
199

SEE ALSO

201       Text::CSV_XS, Class::Accessor
202

AUTHOR

204       David Radunz, <david@boxen.net>
205
207       Copyright 2004 by David Radunz
208
209       This library is free software; you can redistribute it and/or modify it
210       under the same terms as Perl itself.
211
212
213
214perl v5.28.1                      2007-02-08                            CSV(3)
Impressum