.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CSV 3pm"
.TH CSV 3pm "2007-02-08" "perl v5.10.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Class::CSV \- Class based CSV parser/writer
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Class::CSV;
\&
\&  my $csv = Class::CSV\->parse(
\&    filename => \*(Aqtest.csv\*(Aq,
\&    fields   => [qw/item qty sub_total/]
\&  );
\&
\&  foreach my $line (@{$csv\->lines()}) {
\&    $line\->sub_total(\*(Aq$\*(Aq. sprintf("%0.2f", $line\->sub_total()));
\&
\&    print \*(AqItem:     \*(Aq. $line\->item(). "\en".
\&          \*(AqQty:      \*(Aq. $line\->qty(). "\en".
\&          \*(AqSubTotal: \*(Aq. $line\->sub_total(). "\en";
\&  }
\&
\&  my $cvs_as_string = $csv\->string();
\&
\&  $csv\->print();
\&
\&  my $csv = Class::CSV\->new(
\&    fields         => [qw/userid username/],
\&    line_separator => "\er\en";
\&  );
\&
\&  $csv\->add_line([2063, \*(Aqtestuser\*(Aq]);
\&  $csv\->add_line({
\&    userid   => 2064,
\&    username => \*(Aqtestuser2\*(Aq
\&  });
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module can be used to create objects from \fI\s-1CSV\s0\fR files, or to create \fI\s-1CSV\s0\fR
files from objects. Text::CSV_XS is used for parsing and creating \fI\s-1CSV\s0\fR file
lines, so any limitations in Text::CSV_XS will of course be inherant in this
module.
.Sh "\s-1EXPORT\s0"
.IX Subsection "EXPORT"
None by default.
.SH "METHOD"
.IX Header "METHOD"
.Sh "\s-1CONSTRUCTOR\s0"
.IX Subsection "CONSTRUCTOR"
.IP "\fBparse\fR" 4
.IX Item "parse"
the parse constructor takes a hash as its paramater, the various options
that can be in this hash are detailed below.
.RS 4
.IP "\fBRequired Options\fR" 4
.IX Item "Required Options"
.RS 4
.PD 0
.IP "\(bu" 4
.PD
\&\fBfields\fR \- 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: \f(CW\*(C`string\*(C'\fR, \f(CW\*(C`set\*(C'\fR, \f(CW\*(C`get\*(C'\fR. also field
names cannot contain whitespace or any characters that would not be allowed
in a method name.
.RE
.RS 4
.RE
.IP "\fBSource Options\fR (only one of these is needed)" 4
.IX Item "Source Options (only one of these is needed)"
.RS 4
.PD 0
.IP "\(bu" 4
.PD
\&\fBfilename\fR \- the path of the \fI\s-1CSV\s0\fR file to be opened and parsed.
.IP "\(bu" 4
\&\fBfilehandle\fR \- the file handle of the \fI\s-1CSV\s0\fR file to be parsed.
.IP "\(bu" 4
\&\fBobjects\fR \- an array ref of objects (e.g. Class::DBI objects). for this
to work properly the field names provided in \fBfields\fR needs to correspond to
the field names of the objects in the array ref.
.IP "\(bu" 4
\&\fBclassdbi_objects\fR \- \fBdepreciated\fR use objects instead \- using
classdbi_objects will still work but its advisable to update your code.
.RE
.RS 4
.RE
.IP "\fBOptional Options\fR" 4
.IX Item "Optional Options"
.RS 4
.PD 0
.IP "\(bu" 4
.PD
\&\fBline_separator\fR \- the line seperator to be included at the end of every
line. defaulting to \f(CW\*(C`\en\*(C'\fR (unix carriage return).
.RE
.RS 4
.RE
.RE
.RS 4
.RE
.IP "\fBnew\fR" 4
.IX Item "new"
the \fInew\fR constructor takes a hash as its paramater, the same options detailed
in \fBparse\fR apply to \fInew\fR however no \fBSource Options\fR can be used. this
constructor creates a blank \fI\s-1CSV\s0\fR object of which lines can be added
via \fBadd_line\fR.
.Sh "\s-1ACCESSING\s0"
.IX Subsection "ACCESSING"
.IP "\fBlines\fR" 4
.IX Item "lines"
returns an array ref containing objects of each \fI\s-1CSV\s0\fR line (made via
Class::Accessor). the field names given upon construction are available
as accessors and can be \fIset\fR or \fIget\fR. for more information please see
the notes below or the perldoc for Class::Accessor. the \fBlines\fR
accessor is also able to be updated/retrieved in the same way as individual
lines fields (examples below).
.RS 4
.IP "\fBExample\fR" 4
.IX Item "Example"
retrieving the lines:
.RS 4
.Sp
.Vb 1
\&  my @lines = @{$csv\->lines()};
.Ve
.RE
.RS 4
.Sp
removing the first line:
.Sp
.Vb 1
\&  pop @lines;
\&
\&  $csv\->lines(\e@lines);
.Ve
.RE
.RS 4
.Sp
sorting the lines:
.Sp
.Vb 1
\&  @lines = sort { $a\->userid() <=> $b\->userid() } @lines:
\&
\&  $csv\->lines(\e@lines);
.Ve
.RE
.RS 4
.Sp
sorting the lines (all-in-one way):
.Sp
.Vb 1
\&  $csv\->lines([ sort { $a\->userid() <=> $b\->userid() } @{$csv\->lines()} ]);
.Ve
.RE
.RS 4
.RE
.IP "\fBRetrieving a fields value\fR" 4
.IX Item "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 \f(CW\*(C`get\*(C'\fR 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.
.RS 4
.Sp
.Vb 1
\&  my $value = $line\->test();
.Ve
.RE
.RS 4
.Sp
\&\fI\s-1OR\s0\fR
.Sp
.Vb 1
\&  my $value = $line\->get(\*(Aqtest\*(Aq);
.Ve
.RE
.RS 4
.Sp
\&\fI\s-1OR\s0\fR
.Sp
.Vb 1
\&  my @values = $line\->get(qw/test test2 test3/);
.Ve
.RE
.RS 4
.RE
.IP "\fBSetting a fields value\fR" 4
.IX Item "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 \f(CW\*(C`set\*(C'\fR on the object with a hash
of fields and their values to set (this isn't standard in Class::Accessor,
i have overloaded the \f(CW\*(C`set\*(C'\fR method to allow this). examples are below.
.RS 4
.Sp
.Vb 1
\&  $line\->test(\*(Aq123\*(Aq);
.Ve
.RE
.RS 4
.Sp
\&\fI\s-1OR\s0\fR
.Sp
.Vb 1
\&  $line\->set( test => \*(Aq123\*(Aq );
.Ve
.RE
.RS 4
.Sp
\&\fI\s-1OR\s0\fR
.Sp
.Vb 4
\&  $line\->set(
\&    test  => \*(Aq123\*(Aq,
\&    test2 => \*(Aq456\*(Aq
\&  );
.Ve
.RE
.RS 4
.RE
.IP "\fBRetrieving a line as a string\fR" 4
.IX Item "Retrieving a line as a string"
to retrieve a line as a string simply call \f(CW\*(C`string\*(C'\fR on the object.
.RS 4
.Sp
.Vb 1
\&  my $string = $line\->string();
.Ve
.RE
.RS 4
.RE
.RE
.RS 4
.RE
.IP "\fBnew_line\fR" 4
.IX Item "new_line"
returns a new line object, this can be useful for to \f(CW\*(C`splice\*(C'\fR a line into
\&\fBlines\fR (see example below). you can pass the values of
the line as an \fI\s-1ARRAY\s0\fR ref or a \fI\s-1HASH\s0\fR ref.
.RS 4
.IP "\fBExample\fR" 4
.IX Item "Example"
.Vb 3
\&  my $line = $csv\->new_line({ userid => 123, domainname => \*(Aqsplicey.com\*(Aq });
\&  my @lines = $csv\->lines();
\&  splice(@lines, 1, 0, $line);
.Ve
.Sp
\&\fI\s-1OR\s0\fR
.Sp
.Vb 1
\&  splice(@{$csv\->lines()}, 1, 0, $csv\->new_line({ userid => 123, domainname => \*(Aqsplicey.com\*(Aq }));
.Ve
.RE
.RS 4
.RE
.IP "\fBadd_line\fR" 4
.IX Item "add_line"
adds a line to the \fBlines\fR stack. this is mainly useful when the \fBnew\fR
constructor is used but can of course be used with any constructor. it will
add a new line to the end of the \fBlines\fR stack. you can pass the values of
the line as an \fI\s-1ARRAY\s0\fR ref or a \fI\s-1HASH\s0\fR ref. examples of how to use this
are below.
.RS 4
.IP "\fBExample\fR" 4
.IX Item "Example"
.Vb 1
\&  $csv\->add_line([\*(Aqhouse\*(Aq, 100000, 4]);
\&
\&  $csv\->add_line({
\&    item     => \*(Aqhouse\*(Aq,
\&    cost     => 100000,
\&    bedrooms => 4
\&  });
.Ve
.RE
.RS 4
.RE
.Sh "\s-1OUTPUT\s0"
.IX Subsection "OUTPUT"
.IP "\fBstring\fR" 4
.IX Item "string"
returns the object as a string (\fI\s-1CSV\s0\fR file format).
.IP "\fBprint\fR" 4
.IX Item "print"
calls \f(CW\*(C`print\*(C'\fR on \fBstring\fR (prints the \fI\s-1CSV\s0\fR to \s-1STDOUT\s0).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Text::CSV_XS, Class::Accessor
.SH "AUTHOR"
.IX Header "AUTHOR"
David Radunz, <david@boxen.net>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2004 by David Radunz
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.