home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _4bf5643d5775c09074657775f176e968 < prev    next >
Text File  |  2000-03-23  |  14KB  |  324 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>Text::CSV_XS - comma-separated values manipulation routines</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> Text::CSV_XS - comma-separated values manipulation routines</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <LI><A HREF="#functions">FUNCTIONS</A></LI>
  26.     <LI><A HREF="#example">EXAMPLE</A></LI>
  27.     <LI><A HREF="#caveats">CAVEATS</A></LI>
  28.     <LI><A HREF="#author">AUTHOR</A></LI>
  29.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  30. </UL>
  31. <!-- INDEX END -->
  32.  
  33. <HR>
  34. <P>
  35. <H1><A NAME="name">NAME</A></H1>
  36. <P>Text::CSV_XS - comma-separated values manipulation routines</P>
  37. <P>
  38. <HR>
  39. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  40. <UL>
  41. <LI>Linux</LI>
  42. <LI>Solaris</LI>
  43. <LI>Windows</LI>
  44. </UL>
  45. <HR>
  46. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  47. <PRE>
  48.  use Text::CSV_XS;</PRE>
  49. <PRE>
  50.  $csv = Text::CSV_XS->new();           # create a new object
  51.  $csv = Text::CSV_XS->new(\%attr);     # create a new object</PRE>
  52. <PRE>
  53.  $status = $csv->combine(@columns);    # combine columns into a string
  54.  $line = $csv->string();               # get the combined string</PRE>
  55. <PRE>
  56.  $status = $csv->parse($line);         # parse a CSV string into fields
  57.  @columns = $csv->fields();            # get the parsed fields</PRE>
  58. <PRE>
  59.  $status = $csv->status();             # get the most recent status
  60.  $bad_argument = $csv->error_input();  # get the most recent bad argument</PRE>
  61. <PRE>
  62.  $status = $csv->print($io, $columns); # Write an array of fields immediately
  63.                                        # to a file $io</PRE>
  64. <PRE>
  65.  $columns = $csv->getline($io);        # Read a line from file $io, parse it
  66.                                        # and return an array ref of fields</PRE>
  67. <PRE>
  68.  $csv->types(\@t_array);               # Set column types</PRE>
  69. <P>
  70. <HR>
  71. <H1><A NAME="description">DESCRIPTION</A></H1>
  72. <P>Text::CSV_XS provides facilities for the composition and decomposition of
  73. comma-separated values.  An instance of the Text::CSV_XS class can combine
  74. fields into a CSV string and parse a CSV string into fields.</P>
  75. <P>
  76. <HR>
  77. <H1><A NAME="functions">FUNCTIONS</A></H1>
  78. <DL>
  79. <DT><STRONG><A NAME="item_version"><CODE>version()</CODE></A></STRONG><BR>
  80. <DD>
  81. (Class method) Returns the current module version.
  82. <P></P>
  83. <DT><STRONG><A NAME="item_new"><CODE>new(\%attr)</CODE></A></STRONG><BR>
  84. <DD>
  85. (Class method) Returns a new instance of Text::CSV_XS. The objects
  86. attributes are described by the (optional) hash ref <CODE>\%attr</CODE>.
  87. Currently the following attributes are available:
  88. <DL>
  89. <DT><STRONG><A NAME="item_quote_char">quote_char</A></STRONG><BR>
  90. <DD>
  91. The char used for quoting fields containing blanks, by default the
  92. double quote character (<CODE>"</CODE>). A value of undef suppresses
  93. quote chars. (For simple cases only).
  94. <P></P>
  95. <DT><STRONG><A NAME="item_eol">eol</A></STRONG><BR>
  96. <DD>
  97. An end-of-line string to add to rows, usually <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> (nothing,
  98. default), <CODE>"\012"</CODE> (Line Feed) or <CODE>"\015\012"</CODE> (Carriage Return,
  99. Line Feed)
  100. <P></P>
  101. <DT><STRONG><A NAME="item_escape_char">escape_char</A></STRONG><BR>
  102. <DD>
  103. The char used for escaping certain characters inside quoted fields,
  104. by default the same character. (<CODE>"</CODE>)
  105. <P></P>
  106. <DT><STRONG><A NAME="item_sep_char">sep_char</A></STRONG><BR>
  107. <DD>
  108. The char used for separating fields, by default a comme. (<CODE>,</CODE>)
  109. <P></P>
  110. <DT><STRONG><A NAME="item_binary">binary</A></STRONG><BR>
  111. <DD>
  112. If this attribute is TRUE, you may use binary characters in quoted fields,
  113. including line feeds, carriage returns and NUL bytes. (The latter must
  114. be escaped as <CODE>"0</CODE>.) By default this feature is off.
  115. <P></P>
  116. <DT><STRONG><A NAME="item_types">types</A></STRONG><BR>
  117. <DD>
  118. A set of column types; this attribute is immediately passed to the
  119. <EM>types</EM> method below. You must not set this attribute otherwise,
  120. except for using the <EM>types</EM> method. For details see the description
  121. of the <EM>types</EM> method below.
  122. <P></P>
  123. <DT><STRONG><A NAME="item_always_quote">always_quote</A></STRONG><BR>
  124. <DD>
  125. By default the generated fields are quoted only, if they need to, for
  126. example, if they contain the separator. If you set this attribute to
  127. a TRUE value, then all fields will be quoted. This is typically easier
  128. to handle in external applications. (Poor creatures who aren't using
  129. Text::CSV_XS. :-)
  130. <P></P></DL>
  131. <P>To sum it up,</P>
  132. <PRE>
  133.  $csv = Text::CSV_XS->new();</PRE>
  134. <P>is equivalent to</P>
  135. <PRE>
  136.  $csv = Text::CSV_XS->new({
  137.      'quote_char'  => '"',
  138.      'escape_char' => '"',
  139.      'sep_char'    => ',',
  140.      'binary'      => 0
  141.  });</PRE>
  142. <DT><STRONG><A NAME="item_combine">combine</A></STRONG><BR>
  143. <DD>
  144. <PRE>
  145.  $status = $csv->combine(@columns);</PRE>
  146. <P>This object function constructs a CSV string from the arguments, returning
  147. success or failure.  Failure can result from lack of arguments or an argument
  148. containing an invalid character.  Upon success, <A HREF="#item_string"><CODE>string()</CODE></A> can be called to
  149. retrieve the resultant CSV string.  Upon failure, the value returned by
  150. <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
  151. invalid argument.</P>
  152. <DT><STRONG><A NAME="item_print">print</A></STRONG><BR>
  153. <DD>
  154. <PRE>
  155.  $status = $csv->print($io, $columns);</PRE>
  156. <P>Similar to combine, but it expects an array ref as input (not an array!)
  157. and the resulting string is not really created, but immediately written
  158. to the <EM>$io</EM> object, typically an IO handle or any other object that
  159. offers a <EM>print</EM> method. Note, this implies that the following is wrong:</P>
  160. <PRE>
  161.  open(FILE, ">whatever");
  162.  $status = $csv->print(\*FILE, $columns);</PRE>
  163. <P>The glob <CODE>\*FILE</CODE> is not an object, thus it doesn't have a print
  164. method. The solution is to use an IO::File object or to hide the
  165. 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>
  166. for details.</P>
  167. <P>For performance reasons the print method doesn't create a result string.
  168. In particular the <EM>$csv->string()</EM>, <EM>$csv->status()</EM>,
  169. <EM>$csv-</EM>fields()> and <EM>$csv->error_input()</EM> methods are meaningless
  170. after executing this method.</P>
  171. <DT><STRONG><A NAME="item_string">string</A></STRONG><BR>
  172. <DD>
  173. <PRE>
  174.  $line = $csv->string();</PRE>
  175. <P>This object function returns the input to <A HREF="#item_parse"><CODE>parse()</CODE></A> or the resultant CSV
  176. string of <A HREF="#item_combine"><CODE>combine()</CODE></A>, whichever was called more recently.</P>
  177. <DT><STRONG><A NAME="item_parse">parse</A></STRONG><BR>
  178. <DD>
  179. <PRE>
  180.  $status = $csv->parse($line);</PRE>
  181. <P>This object function decomposes a CSV string into fields, returning
  182. success or failure.  Failure can result from a lack of argument or the
  183. given CSV string is improperly formatted.  Upon success, <A HREF="#item_fields"><CODE>fields()</CODE></A> can
  184. be called to retrieve the decomposed fields .  Upon failure, the value
  185. 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
  186. to retrieve the invalid argument.</P>
  187. <P>You may use the <EM>types()</EM> method for setting column types. See the
  188. description below.</P>
  189. <DT><STRONG><A NAME="item_getline">getline</A></STRONG><BR>
  190. <DD>
  191. <PRE>
  192.  $columns = $csv->getline($io);</PRE>
  193. <P>This is the counterpart to print, like parse is the counterpart to
  194. combine: It reads a row from the IO object $io using $io-><A HREF="#item_getline"><CODE>getline()</CODE></A>
  195. and parses this row into an array ref. This array ref is returned
  196. by the function or undef for failure.</P>
  197. <P>The <EM>$csv->string()</EM>, <EM>$csv->fields()</EM> and <EM>$csv->status()</EM>
  198. methods are meaningless, again.</P>
  199. <DT><STRONG>types</STRONG><BR>
  200. <DD>
  201. <PRE>
  202.  $csv->types(\@tref);</PRE>
  203. <P>This method is used to force that columns are of a given type. For
  204. example, if you have an integer column, two double columns and a
  205. string column, then you might do a</P>
  206. <PRE>
  207.  $csv->types([Text::CSV_XS::IV(),
  208.               Text::CSV_XS::NV(),
  209.               Text::CSV_XS::NV(),
  210.               Text::CSV_XS::PV()]);</PRE>
  211. <P>Column types are used only for decoding columns, in other words
  212. by the <EM>parse()</EM> and <EM>getline()</EM> methods.</P>
  213. <P>You can unset column types by doing a</P>
  214. <PRE>
  215.  $csv->types(undef);</PRE>
  216. <P>or fetch the current type settings with</P>
  217. <PRE>
  218.  $types = $csv->types();</PRE>
  219. <DT><STRONG><A NAME="item_fields">fields</A></STRONG><BR>
  220. <DD>
  221. <PRE>
  222.  @columns = $csv->fields();</PRE>
  223. <P>This object function returns the input to <A HREF="#item_combine"><CODE>combine()</CODE></A> or the resultant
  224. decomposed fields of <A HREF="#item_parse"><CODE>parse()</CODE></A>, whichever was called more recently.</P>
  225. <DT><STRONG><A NAME="item_status">status</A></STRONG><BR>
  226. <DD>
  227. <PRE>
  228.  $status = $csv->status();</PRE>
  229. <P>This object function returns success (or failure) of <A HREF="#item_combine"><CODE>combine()</CODE></A> or
  230. <A HREF="#item_parse"><CODE>parse()</CODE></A>, whichever was called more recently.</P>
  231. <DT><STRONG><A NAME="item_error_input">error_input</A></STRONG><BR>
  232. <DD>
  233. <PRE>
  234.  $bad_argument = $csv->error_input();</PRE>
  235. <P>This object function returns the erroneous argument (if it exists) of
  236. <A HREF="#item_combine"><CODE>combine()</CODE></A> or <A HREF="#item_parse"><CODE>parse()</CODE></A>, whichever was called more recently.</P>
  237. </DL>
  238. <P>
  239. <HR>
  240. <H1><A NAME="example">EXAMPLE</A></H1>
  241. <PRE>
  242.   require Text::CSV_XS;</PRE>
  243. <PRE>
  244.   my $csv = Text::CSV_XS->new;</PRE>
  245. <PRE>
  246.   my $column = '';
  247.   my $sample_input_string = '"I said, ""Hi!""",Yes,"",2.34,,"1.09"';
  248.   if ($csv->parse($sample_input_string)) {
  249.     my @field = $csv->fields;
  250.     my $count = 0;
  251.     for $column (@field) {
  252.       print ++$count, " => ", $column, "\n";
  253.     }
  254.     print "\n";
  255.   } else {
  256.     my $err = $csv->error_input;
  257.     print "parse() failed on argument: ", $err, "\n";
  258.   }</PRE>
  259. <PRE>
  260.   my @sample_input_fields = ('You said, "Hello!"',
  261.                              5.67,
  262.                              'Surely',
  263.                              '',
  264.                              '3.14159');
  265.   if ($csv->combine(@sample_input_fields)) {
  266.     my $string = $csv->string;
  267.     print $string, "\n";
  268.   } else {
  269.     my $err = $csv->error_input;
  270.     print "combine() failed on argument: ", $err, "\n";
  271.   }</PRE>
  272. <P>
  273. <HR>
  274. <H1><A NAME="caveats">CAVEATS</A></H1>
  275. <P>This module is based upon a working definition of CSV format which may not be
  276. the most general.</P>
  277. <OL>
  278. <LI>
  279. Allowable characters within a CSV field include 0x09 (tab) and the inclusive
  280. range of 0x20 (space) through 0x7E (tilde). In binary mode all characters
  281. are accepted, at least in quoted fields:
  282. <P></P>
  283. <LI>
  284. A field within CSV may be surrounded by double-quotes. (The quote char)
  285. <P></P>
  286. <LI>
  287. A field within CSV must be surrounded by double-quotes to contain a comma.
  288. (The separator char)
  289. <P></P>
  290. <LI>
  291. A field within CSV must be surrounded by double-quotes to contain an embedded
  292. double-quote, represented by a pair of consecutive double-quotes. In binary
  293. mode you may additionally use the sequence <CODE>"0</CODE> for representation of a
  294. NUL byte.
  295. <P></P>
  296. <LI>
  297. A CSV string may be terminated by 0x0A (line feed) or by 0x0D,0x0A
  298. (carriage return, line feed).
  299. <P></P></OL>
  300. <P>
  301. <HR>
  302. <H1><A NAME="author">AUTHOR</A></H1>
  303. <P>Alan Citterman <EM><<A HREF="mailto:alan@mfgrtl.com">alan@mfgrtl.com</A>></EM> wrote the original Perl
  304. module. Please don't send mail concerning Text::CSV_XS to Alan, as
  305. he's not involved in the C part which is now the main part of the
  306. module.</P>
  307. <P>Jochen Wiedmann <EM><<A HREF="mailto:joe@ispsoft.de">joe@ispsoft.de</A>></EM> rewrote the encoding and
  308. decoding in C by implementing a simple finite-state machine and added
  309. the variable quote, escape and separator characters, the binary mode
  310. and the print and getline methods.</P>
  311. <P>
  312. <HR>
  313. <H1><A NAME="see also">SEE ALSO</A></H1>
  314. <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>
  315. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  316. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  317. <STRONG><P CLASS=block> Text::CSV_XS - comma-separated values manipulation routines</P></STRONG>
  318. </TD></TR>
  319. </TABLE>
  320.  
  321. </BODY>
  322.  
  323. </HTML>
  324.