home *** CD-ROM | disk | FTP | other *** search
<HTML> <HEAD> <TITLE>Text::CSV_XS - comma-separated values manipulation routines</TITLE> <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css"> <LINK REV="made" HREF="mailto:"> </HEAD> <BODY> <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%> <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc"> <STRONG><P CLASS=block> Text::CSV_XS - comma-separated values manipulation routines</P></STRONG> </TD></TR> </TABLE> <A NAME="__index__"></A> <!-- INDEX BEGIN --> <UL> <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI> <LI><A HREF="#synopsis">SYNOPSIS</A></LI> <LI><A HREF="#description">DESCRIPTION</A></LI> <LI><A HREF="#functions">FUNCTIONS</A></LI> <LI><A HREF="#example">EXAMPLE</A></LI> <LI><A HREF="#caveats">CAVEATS</A></LI> <LI><A HREF="#author">AUTHOR</A></LI> <LI><A HREF="#see also">SEE ALSO</A></LI> </UL> <!-- INDEX END --> <HR> <P> <H1><A NAME="name">NAME</A></H1> <P>Text::CSV_XS - comma-separated values manipulation routines</P> <P> <HR> <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1> <UL> <LI>Linux</LI> <LI>Solaris</LI> <LI>Windows</LI> </UL> <HR> <H1><A NAME="synopsis">SYNOPSIS</A></H1> <PRE> use Text::CSV_XS;</PRE> <PRE> $csv = Text::CSV_XS->new(); # create a new object $csv = Text::CSV_XS->new(\%attr); # create a new object</PRE> <PRE> $status = $csv->combine(@columns); # combine columns into a string $line = $csv->string(); # get the combined string</PRE> <PRE> $status = $csv->parse($line); # parse a CSV string into fields @columns = $csv->fields(); # get the parsed fields</PRE> <PRE> $status = $csv->status(); # get the most recent status $bad_argument = $csv->error_input(); # get the most recent bad argument</PRE> <PRE> $status = $csv->print($io, $columns); # Write an array of fields immediately # to a file $io</PRE> <PRE> $columns = $csv->getline($io); # Read a line from file $io, parse it # and return an array ref of fields</PRE> <PRE> $csv->types(\@t_array); # Set column types</PRE> <P> <HR> <H1><A NAME="description">DESCRIPTION</A></H1> <P>Text::CSV_XS provides facilities for the composition and decomposition of comma-separated values. An instance of the Text::CSV_XS class can combine fields into a CSV string and parse a CSV string into fields.</P> <P> <HR> <H1><A NAME="functions">FUNCTIONS</A></H1> <DL> <DT><STRONG><A NAME="item_version"><CODE>version()</CODE></A></STRONG><BR> <DD> (Class method) Returns the current module version. <P></P> <DT><STRONG><A NAME="item_new"><CODE>new(\%attr)</CODE></A></STRONG><BR> <DD> (Class method) Returns a new instance of Text::CSV_XS. The objects attributes are described by the (optional) hash ref <CODE>\%attr</CODE>. Currently the following attributes are available: <DL> <DT><STRONG><A NAME="item_quote_char">quote_char</A></STRONG><BR> <DD> The char used for quoting fields containing blanks, by default the double quote character (<CODE>"</CODE>). A value of undef suppresses quote chars. (For simple cases only). <P></P> <DT><STRONG><A NAME="item_eol">eol</A></STRONG><BR> <DD> An end-of-line string to add to rows, usually <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> (nothing, default), <CODE>"\012"</CODE> (Line Feed) or <CODE>"\015\012"</CODE> (Carriage Return, Line Feed) <P></P> <DT><STRONG><A NAME="item_escape_char">escape_char</A></STRONG><BR> <DD> The char used for escaping certain characters inside quoted fields, by default the same character. (<CODE>"</CODE>) <P></P> <DT><STRONG><A NAME="item_sep_char">sep_char</A></STRONG><BR> <DD> The char used for separating fields, by default a comme. (<CODE>,</CODE>) <P></P> <DT><STRONG><A NAME="item_binary">binary</A></STRONG><BR> <DD> If this attribute is TRUE, you may use binary characters in quoted fields, including line feeds, carriage returns and NUL bytes. (The latter must be escaped as <CODE>"0</CODE>.) By default this feature is off. <P></P> <DT><STRONG><A NAME="item_types">types</A></STRONG><BR> <DD> A set of column types; this attribute is immediately passed to the <EM>types</EM> method below. You must not set this attribute otherwise, except for using the <EM>types</EM> method. For details see the description of the <EM>types</EM> method below. <P></P> <DT><STRONG><A NAME="item_always_quote">always_quote</A></STRONG><BR> <DD> By default the generated fields are quoted only, if they need to, for example, if they contain the separator. If you set this attribute to a TRUE value, then all fields will be quoted. This is typically easier to handle in external applications. (Poor creatures who aren't using Text::CSV_XS. :-) <P></P></DL> <P>To sum it up,</P> <PRE> $csv = Text::CSV_XS->new();</PRE> <P>is equivalent to</P> <PRE> $csv = Text::CSV_XS->new({ 'quote_char' => '"', 'escape_char' => '"', 'sep_char' => ',', 'binary' => 0 });</PRE> <DT><STRONG><A NAME="item_combine">combine</A></STRONG><BR> <DD> <PRE> $status = $csv->combine(@columns);</PRE> <P>This object function constructs a CSV string from the arguments, returning success or failure. Failure can result from lack of arguments or an argument containing an invalid character. Upon success, <A HREF="#item_string"><CODE>string()</CODE></A> can be called to retrieve the resultant CSV string. Upon failure, the value returned by <A HREF="#item_string"><CODE>string()</CODE></A> is undefined and <A HREF="#item_error_input"><CODE>error_input()</CODE></A> can be called to retrieve an invalid argument.</P> <DT><STRONG><A NAME="item_print">print</A></STRONG><BR> <DD> <PRE> $status = $csv->print($io, $columns);</PRE> <P>Similar to combine, but it expects an array ref as input (not an array!) and the resulting string is not really created, but immediately written to the <EM>$io</EM> object, typically an IO handle or any other object that offers a <EM>print</EM> method. Note, this implies that the following is wrong:</P> <PRE> open(FILE, ">whatever"); $status = $csv->print(\*FILE, $columns);</PRE> <P>The glob <CODE>\*FILE</CODE> is not an object, thus it doesn't have a print method. The solution is to use an IO::File object or to hide the glob behind an IO::Wrap object. See <A HREF="../../../IO/File(3).html">the IO::File(3) manpage</A> and <A HREF="../../../IO/Wrap(3).html">the IO::Wrap(3) manpage</A> for details.</P> <P>For performance reasons the print method doesn't create a result string. In particular the <EM>$csv->string()</EM>, <EM>$csv->status()</EM>, <EM>$csv-</EM>fields()> and <EM>$csv->error_input()</EM> methods are meaningless after executing this method.</P> <DT><STRONG><A NAME="item_string">string</A></STRONG><BR> <DD> <PRE> $line = $csv->string();</PRE> <P>This object function returns the input to <A HREF="#item_parse"><CODE>parse()</CODE></A> or the resultant CSV string of <A HREF="#item_combine"><CODE>combine()</CODE></A>, whichever was called more recently.</P> <DT><STRONG><A NAME="item_parse">parse</A></STRONG><BR> <DD> <PRE> $status = $csv->parse($line);</PRE> <P>This object function decomposes a CSV string into fields, returning success or failure. Failure can result from a lack of argument or the given CSV string is improperly formatted. Upon success, <A HREF="#item_fields"><CODE>fields()</CODE></A> can be called to retrieve the decomposed fields . Upon failure, the value returned by <A HREF="#item_fields"><CODE>fields()</CODE></A> is undefined and <A HREF="#item_error_input"><CODE>error_input()</CODE></A> can be called to retrieve the invalid argument.</P> <P>You may use the <EM>types()</EM> method for setting column types. See the description below.</P> <DT><STRONG><A NAME="item_getline">getline</A></STRONG><BR> <DD> <PRE> $columns = $csv->getline($io);</PRE> <P>This is the counterpart to print, like parse is the counterpart to combine: It reads a row from the IO object $io using $io-><A HREF="#item_getline"><CODE>getline()</CODE></A> and parses this row into an array ref. This array ref is returned by the function or undef for failure.</P> <P>The <EM>$csv->string()</EM>, <EM>$csv->fields()</EM> and <EM>$csv->status()</EM> methods are meaningless, again.</P> <DT><STRONG>types</STRONG><BR> <DD> <PRE> $csv->types(\@tref);</PRE> <P>This method is used to force that columns are of a given type. For example, if you have an integer column, two double columns and a string column, then you might do a</P> <PRE> $csv->types([Text::CSV_XS::IV(), Text::CSV_XS::NV(), Text::CSV_XS::NV(), Text::CSV_XS::PV()]);</PRE> <P>Column types are used only for decoding columns, in other words by the <EM>parse()</EM> and <EM>getline()</EM> methods.</P> <P>You can unset column types by doing a</P> <PRE> $csv->types(undef);</PRE> <P>or fetch the current type settings with</P> <PRE> $types = $csv->types();</PRE> <DT><STRONG><A NAME="item_fields">fields</A></STRONG><BR> <DD> <PRE> @columns = $csv->fields();</PRE> <P>This object function returns the input to <A HREF="#item_combine"><CODE>combine()</CODE></A> or the resultant decomposed fields of <A HREF="#item_parse"><CODE>parse()</CODE></A>, whichever was called more recently.</P> <DT><STRONG><A NAME="item_status">status</A></STRONG><BR> <DD> <PRE> $status = $csv->status();</PRE> <P>This object function returns success (or failure) of <A HREF="#item_combine"><CODE>combine()</CODE></A> or <A HREF="#item_parse"><CODE>parse()</CODE></A>, whichever was called more recently.</P> <DT><STRONG><A NAME="item_error_input">error_input</A></STRONG><BR> <DD> <PRE> $bad_argument = $csv->error_input();</PRE> <P>This object function returns the erroneous argument (if it exists) of <A HREF="#item_combine"><CODE>combine()</CODE></A> or <A HREF="#item_parse"><CODE>parse()</CODE></A>, whichever was called more recently.</P> </DL> <P> <HR> <H1><A NAME="example">EXAMPLE</A></H1> <PRE> require Text::CSV_XS;</PRE> <PRE> my $csv = Text::CSV_XS->new;</PRE> <PRE> my $column = ''; my $sample_input_string = '"I said, ""Hi!""",Yes,"",2.34,,"1.09"'; if ($csv->parse($sample_input_string)) { my @field = $csv->fields; my $count = 0; for $column (@field) { print ++$count, " => ", $column, "\n"; } print "\n"; } else { my $err = $csv->error_input; print "parse() failed on argument: ", $err, "\n"; }</PRE> <PRE> my @sample_input_fields = ('You said, "Hello!"', 5.67, 'Surely', '', '3.14159'); if ($csv->combine(@sample_input_fields)) { my $string = $csv->string; print $string, "\n"; } else { my $err = $csv->error_input; print "combine() failed on argument: ", $err, "\n"; }</PRE> <P> <HR> <H1><A NAME="caveats">CAVEATS</A></H1> <P>This module is based upon a working definition of CSV format which may not be the most general.</P> <OL> <LI> Allowable characters within a CSV field include 0x09 (tab) and the inclusive range of 0x20 (space) through 0x7E (tilde). In binary mode all characters are accepted, at least in quoted fields: <P></P> <LI> A field within CSV may be surrounded by double-quotes. (The quote char) <P></P> <LI> A field within CSV must be surrounded by double-quotes to contain a comma. (The separator char) <P></P> <LI> A field within CSV must be surrounded by double-quotes to contain an embedded double-quote, represented by a pair of consecutive double-quotes. In binary mode you may additionally use the sequence <CODE>"0</CODE> for representation of a NUL byte. <P></P> <LI> A CSV string may be terminated by 0x0A (line feed) or by 0x0D,0x0A (carriage return, line feed). <P></P></OL> <P> <HR> <H1><A NAME="author">AUTHOR</A></H1> <P>Alan Citterman <EM><<A HREF="mailto:alan@mfgrtl.com">alan@mfgrtl.com</A>></EM> wrote the original Perl module. Please don't send mail concerning Text::CSV_XS to Alan, as he's not involved in the C part which is now the main part of the module.</P> <P>Jochen Wiedmann <EM><<A HREF="mailto:joe@ispsoft.de">joe@ispsoft.de</A>></EM> rewrote the encoding and decoding in C by implementing a simple finite-state machine and added the variable quote, escape and separator characters, the binary mode and the print and getline methods.</P> <P> <HR> <H1><A NAME="see also">SEE ALSO</A></H1> <P><EM>perl(1)</EM>, <A HREF="../../../IO/File(3).html">the IO::File(3) manpage</A>, <A HREF="../../../IO/Wrap(3).html">the IO::Wrap(3) manpage</A></P> <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%> <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc"> <STRONG><P CLASS=block> Text::CSV_XS - comma-separated values manipulation routines</P></STRONG> </TD></TR> </TABLE> </BODY> </HTML> 
