1Text::CSV(3) User Contributed Perl Documentation Text::CSV(3)
2
6 Text::CSV - comma-separated values manipulator (using XS or PurePerl)
7
9 use Text::CSV;
10 my @rows;
12 my $csv = Text::CSV->new ( { binary => 1 } ) # should set binary attribute.
13 or die "Cannot use CSV: ".Text::CSV->error_diag ();
14 open my $fh, "<:encoding(utf8)", "test.csv" or die "test.csv: $!";
16 while ( my $row = $csv->getline( $fh ) ) {
17 $row->[2] =~ m/pattern/ or next; # 3rd field should match
18 push @rows, $row;
19 }
20 $csv->eof or $csv->error_diag();
21 close $fh;
22 $csv->eol ("\r\n");
24 open $fh, ">:encoding(utf8)", "new.csv" or die "new.csv: $!";
26 $csv->print ($fh, $_) for @rows;
27 close $fh or die "new.csv: $!";
28 #
30 # parse and combine style
31 #
32 $status = $csv->combine(@columns); # combine columns into a string
34 $line = $csv->string(); # get the combined string
35 $status = $csv->parse($line); # parse a CSV string into fields
37 @columns = $csv->fields(); # get the parsed fields
38 $status = $csv->status (); # get the most recent status
40 $bad_argument = $csv->error_input (); # get the most recent bad argument
41 $diag = $csv->error_diag (); # if an error occured, explains WHY
42 $status = $csv->print ($io, $colref); # Write an array of fields
44 # immediately to a file $io
45 $colref = $csv->getline ($io); # Read a line from file $io,
46 # parse it and return an array
47 # ref of fields
48 $csv->column_names (@names); # Set column names for getline_hr ()
49 $ref = $csv->getline_hr ($io); # getline (), but returns a hashref
50 $eof = $csv->eof (); # Indicate if last parse or
51 # getline () hit End Of File
52 $csv->types(\@t_array); # Set column types
54
56 Text::CSV provides facilities for the composition and decomposition of
57 comma-separated values using Text::CSV_XS or its pure Perl version.
58 An instance of the Text::CSV class can combine fields into a CSV string
60 and parse a CSV string into fields.
61 The module accepts either strings or files as input and can utilize any
63 user-specified characters as delimiters, separators, and escapes so it
64 is perhaps better called ASV (anything separated values) rather than
65 just CSV.
66
68 1.21
69 This module is compatible with Text::CSV_XS 0.80 and later.
71 Embedded newlines
73 Important Note: The default behavior is to only accept ASCII
74 characters. This means that fields can not contain newlines. If your
75 data contains newlines embedded in fields, or characters above 0x7e
76 (tilde), or binary data, you *must* set "binary => 1" in the call to
77 "new ()". To cover the widest range of parsing options, you will
78 always want to set binary.
79 But you still have the problem that you have to pass a correct line to
81 the "parse ()" method, which is more complicated from the usual point
82 of usage:
83 my $csv = Text::CSV->new ({ binary => 1, eol => $/ });
85 while (<>) { # WRONG!
86 $csv->parse ($_);
87 my @fields = $csv->fields ();
88 will break, as the while might read broken lines, as that does not care
90 about the quoting. If you need to support embedded newlines, the way to
91 go is either
92 my $csv = Text::CSV->new ({ binary => 1, eol => $/ });
94 while (my $row = $csv->getline (*ARGV)) {
95 my @fields = @$row;
96 or, more safely in perl 5.6 and up
98 my $csv = Text::CSV->new ({ binary => 1, eol => $/ });
100 open my $io, "<", $file or die "$file: $!";
101 while (my $row = $csv->getline ($io)) {
102 my @fields = @$row;
103 Unicode (UTF8)
105 On parsing (both for "getline ()" and "parse ()"), if the source is
106 marked being UTF8, then all fields that are marked binary will also be
107 be marked UTF8.
108 For complete control over encoding, please use Text::CSV::Encoded:
110 use Text::CSV::Encoded;
112 my $csv = Text::CSV::Encoded->new ({
113 encoding_in => "iso-8859-1", # the encoding comes into Perl
114 encoding_out => "cp1252", # the encoding comes out of Perl
115 });
116 $csv = Text::CSV::Encoded->new ({ encoding => "utf8" });
118 # combine () and print () accept *literally* utf8 encoded data
119 # parse () and getline () return *literally* utf8 encoded data
120 $csv = Text::CSV::Encoded->new ({ encoding => undef }); # default
122 # combine () and print () accept UTF8 marked data
123 # parse () and getline () return UTF8 marked data
124 On combining ("print ()" and "combine ()"), if any of the combining
126 fields was marked UTF8, the resulting string will be marked UTF8.
127 Note however if the backend module is Text::CSV_XS, that all fields
129 "before" the first field that was marked UTF8 and contained 8-bit
130 characters that were not upgraded to UTF8, these will be bytes in the
131 resulting string too, causing errors. If you pass data of different
132 encoding, or you don't know if there is different encoding, force it to
133 be upgraded before you pass them on:
134 # backend = Text::CSV_XS
136 $csv->print ($fh, [ map { utf8::upgrade (my $x = $_); $x } @data ]);
137
139 See to "SPECIFICATION" in Text::CSV_XS.
140
142 These methods are common between XS and puer Perl version. Most of the
143 document was shamelessly copied and replaced from Text::CSV_XS.
144 version ()
146 (Class method) Returns the current backend module version. If you want
147 the module version, you can use the "VERSION" method,
148 print Text::CSV->VERSION; # This module version
150 print Text::CSV->version; # The version of the worker module
151 # same as Text::CSV->backend->version
152 new (\%attr)
154 (Class method) Returns a new instance of Text::CSV_XS. The objects
155 attributes are described by the (optional) hash ref "\%attr".
156 Currently the following attributes are available:
157 eol An end-of-line string to add to rows. "undef" is replaced with an
159 empty string. The default is "$\". Common values for "eol" are
160 "\012" (Line Feed) or "\015\012" (Carriage Return, Line Feed).
161 Cannot be longer than 7 (ASCII) characters.
162 If both $/ and "eol" equal "\015", parsing lines that end on only a
164 Carriage Return without Line Feed, will be "parse"d correct. Line
165 endings, whether in $/ or "eol", other than "undef", "\n", "\r\n",
166 or "\r" are not (yet) supported for parsing.
167 sep_char
169 The char used for separating fields, by default a comma. (",").
170 Limited to a single-byte character, usually in the range from 0x20
171 (space) to 0x7e (tilde).
172 The separation character can not be equal to the quote character.
174 The separation character can not be equal to the escape character.
175 See also "CAVEATS" in Text::CSV_XS
177 allow_whitespace
179 When this option is set to true, whitespace (TAB's and SPACE's)
180 surrounding the separation character is removed when parsing. If
181 either TAB or SPACE is one of the three major characters
182 "sep_char", "quote_char", or "escape_char" it will not be
183 considered whitespace.
184 So lines like:
186 1 , "foo" , bar , 3 , zapp
188 are now correctly parsed, even though it violates the CSV specs.
190 Note that all whitespace is stripped from start and end of each
192 field. That would make it more a feature than a way to be able to
193 parse bad CSV lines, as
194 1, 2.0, 3, ape , monkey
196 will now be parsed as
198 ("1", "2.0", "3", "ape", "monkey")
200 even if the original line was perfectly sane CSV.
202 blank_is_undef
204 Under normal circumstances, CSV data makes no distinction between
205 quoted- and unquoted empty fields. They both end up in an empty
206 string field once read, so
207 1,"",," ",2
209 is read as
211 ("1", "", "", " ", "2")
213 When writing CSV files with "always_quote" set, the unquoted empty
215 field is the result of an undefined value. To make it possible to
216 also make this distinction when reading CSV data, the
217 "blank_is_undef" option will cause unquoted empty fields to be set
218 to undef, causing the above to be parsed as
219 ("1", "", undef, " ", "2")
221 empty_is_undef
223 Going one step further than "blank_is_undef", this attribute
224 converts all empty fields to undef, so
225 1,"",," ",2
227 is read as
229 (1, undef, undef, " ", 2)
231 Note that this only effects fields that are really empty, not
233 fields that are empty after stripping allowed whitespace. YMMV.
234 quote_char
236 The char used for quoting fields containing blanks, by default the
237 double quote character ("""). A value of undef suppresses quote
238 chars. (For simple cases only). Limited to a single-byte
239 character, usually in the range from 0x20 (space) to 0x7e (tilde).
240 The quote character can not be equal to the separation character.
242 allow_loose_quotes
244 By default, parsing fields that have "quote_char" characters inside
245 an unquoted field, like
246 1,foo "bar" baz,42
248 would result in a parse error. Though it is still bad practice to
250 allow this format, we cannot help there are some vendors that make
251 their applications spit out lines styled like this.
252 In case there is really bad CSV data, like
254 1,"foo "bar" baz",42
256 or
258 1,""foo bar baz"",42
260 there is a way to get that parsed, and leave the quotes inside the
262 quoted field as-is. This can be achieved by setting
263 "allow_loose_quotes" AND making sure that the "escape_char" is not
264 equal to "quote_char".
265 escape_char
267 The character used for escaping certain characters inside quoted
268 fields. Limited to a single-byte character, usually in the range
269 from 0x20 (space) to 0x7e (tilde).
270 The "escape_char" defaults to being the literal double-quote mark
272 (""") in other words, the same as the default "quote_char". This
273 means that doubling the quote mark in a field escapes it:
274 "foo","bar","Escape ""quote mark"" with two ""quote marks""","baz"
276 If you change the default quote_char without changing the default
278 escape_char, the escape_char will still be the quote mark. If
279 instead you want to escape the quote_char by doubling it, you will
280 need to change the escape_char to be the same as what you changed
281 the quote_char to.
282 The escape character can not be equal to the separation character.
284 allow_loose_escapes
286 By default, parsing fields that have "escape_char" characters that
287 escape characters that do not need to be escaped, like:
288 my $csv = Text::CSV->new ({ escape_char => "\\" });
290 $csv->parse (qq{1,"my bar\'s",baz,42});
291 would result in a parse error. Though it is still bad practice to
293 allow this format, this option enables you to treat all escape
294 character sequences equal.
295 binary
297 If this attribute is TRUE, you may use binary characters in quoted
298 fields, including line feeds, carriage returns and NULL bytes. (The
299 latter must be escaped as ""0".) By default this feature is off.
300 If a string is marked UTF8, binary will be turned on automatically
302 when binary characters other than CR or NL are encountered. Note
303 that a simple string like "\x{00a0}" might still be binary, but not
304 marked UTF8, so setting "{ binary => 1 }" is still a wise option.
305 types
307 A set of column types; this attribute is immediately passed to the
308 types method below. You must not set this attribute otherwise,
309 except for using the types method. For details see the description
310 of the types method below.
311 always_quote
313 By default the generated fields are quoted only, if they need to,
314 for example, if they contain the separator. If you set this
315 attribute to a TRUE value, then all defined fields will be quoted.
316 This is typically easier to handle in external applications.
317 quote_space
319 By default, a space in a field would trigger quotation. As no rule
320 exists this to be forced in CSV, nor any for the opposite, the
321 default is true for safety. You can exclude the space from this
322 trigger by setting this option to 0.
323 quote_null
325 By default, a NULL byte in a field would be escaped. This attribute
326 enables you to treat the NULL byte as a simple binary character in
327 binary mode (the "{ binary => 1 }" is set). The default is true.
328 You can prevent NULL escapes by setting this attribute to 0.
329 keep_meta_info
331 By default, the parsing of input lines is as simple and fast as
332 possible. However, some parsing information - like quotation of the
333 original field - is lost in that process. Set this flag to true to
334 be able to retrieve that information after parsing with the methods
335 "meta_info ()", "is_quoted ()", and "is_binary ()" described below.
336 Default is false.
337 verbatim
339 This is a quite controversial attribute to set, but it makes hard
340 things possible.
341 The basic thought behind this is to tell the parser that the
343 normally special characters newline (NL) and Carriage Return (CR)
344 will not be special when this flag is set, and be dealt with as
345 being ordinary binary characters. This will ease working with data
346 with embedded newlines.
347 When "verbatim" is used with "getline ()", "getline ()" auto-
349 chomp's every line.
350 Imagine a file format like
352 M^^Hans^Janssen^Klas 2\n2A^Ja^11-06-2007#\r\n
354 where, the line ending is a very specific "#\r\n", and the sep_char
356 is a ^ (caret). None of the fields is quoted, but embedded binary
357 data is likely to be present. With the specific line ending, that
358 shouldn not be too hard to detect.
359 By default, Text::CSV' parse function however is instructed to only
361 know about "\n" and "\r" to be legal line endings, and so has to
362 deal with the embedded newline as a real end-of-line, so it can
363 scan the next line if binary is true, and the newline is inside a
364 quoted field. With this attribute however, we can tell parse () to
365 parse the line as if \n is just nothing more than a binary
366 character.
367 For parse () this means that the parser has no idea about line
369 ending anymore, and getline () chomps line endings on reading.
370 auto_diag
372 Set to true will cause "error_diag ()" to be automatically be
373 called in void context upon errors.
374 If set to a value greater than 1, it will die on errors instead of
376 warn.
377 To check future plans and a difference in XS version, please see to
379 "auto_diag" in Text::CSV_XS.
380 To sum it up,
382 $csv = Text::CSV->new ();
384 is equivalent to
386 $csv = Text::CSV->new ({
388 quote_char => '"',
389 escape_char => '"',
390 sep_char => ',',
391 eol => $\,
392 always_quote => 0,
393 quote_space => 1,
394 quote_null => 1,
395 binary => 0,
396 keep_meta_info => 0,
397 allow_loose_quotes => 0,
398 allow_loose_escapes => 0,
399 allow_whitespace => 0,
400 blank_is_undef => 0,
401 empty_is_undef => 0,
402 verbatim => 0,
403 auto_diag => 0,
404 });
405 For all of the above mentioned flags, there is an accessor method
407 available where you can inquire for the current value, or change the
408 value
409 my $quote = $csv->quote_char;
411 $csv->binary (1);
412 It is unwise to change these settings halfway through writing CSV data
414 to a stream. If however, you want to create a new stream using the
415 available CSV object, there is no harm in changing them.
416 If the "new ()" constructor call fails, it returns "undef", and makes
418 the fail reason available through the "error_diag ()" method.
419 $csv = Text::CSV->new ({ ecs_char => 1 }) or
421 die "" . Text::CSV->error_diag ();
422 "error_diag ()" will return a string like
424 "INI - Unknown attribute 'ecs_char'"
426 print
428 $status = $csv->print ($io, $colref);
429 Similar to "combine () + string () + print", but more efficient. It
431 expects an array ref as input (not an array!) and the resulting string
432 is not really created (XS version), but immediately written to the $io
433 object, typically an IO handle or any other object that offers a print
434 method. Note, this implies that the following is wrong in perl 5.005_xx
435 and older:
436 open FILE, ">", "whatever";
438 $status = $csv->print (\*FILE, $colref);
439 as in perl 5.005 and older, the glob "\*FILE" is not an object, thus it
441 does not have a print method. The solution is to use an IO::File object
442 or to hide the glob behind an IO::Wrap object. See IO::File and
443 IO::Wrap for details.
444 For performance reasons the print method doesn't create a result
446 string. (If its backend is PP version, result strings are created
447 internally.) In particular the $csv->string (), $csv->status (),
448 $csv-fields ()> and $csv->error_input () methods are meaningless after
449 executing this method.
450 combine
452 $status = $csv->combine (@columns);
453 This object function constructs a CSV string from the arguments,
455 returning success or failure. Failure can result from lack of
456 arguments or an argument containing an invalid character. Upon
457 success, "string ()" can be called to retrieve the resultant CSV
458 string. Upon failure, the value returned by "string ()" is undefined
459 and "error_input ()" can be called to retrieve an invalid argument.
460 string
462 $line = $csv->string ();
463 This object function returns the input to "parse ()" or the resultant
465 CSV string of "combine ()", whichever was called more recently.
466 getline
468 $colref = $csv->getline ($io);
469 This is the counterpart to print, like parse is the counterpart to
471 combine: It reads a row from the IO object $io using $io->getline ()
472 and parses this row into an array ref. This array ref is returned by
473 the function or undef for failure.
474 When fields are bound with "bind_columns ()", the return value is a
476 reference to an empty list.
477 The $csv->string (), $csv->fields () and $csv->status () methods are
479 meaningless, again.
480 getline_all
482 $arrayref = $csv->getline_all ($io);
483 $arrayref = $csv->getline_all ($io, $offset);
484 $arrayref = $csv->getline_all ($io, $offset, $length);
485 This will return a reference to a list of "getline ($io)" results. In
487 this call, "keep_meta_info" is disabled. If $offset is negative, as
488 with "splice ()", only the last "abs ($offset)" records of $io are
489 taken into consideration.
490 Given a CSV file with 10 lines:
492 lines call
494 ----- ---------------------------------------------------------
495 0..9 $csv->getline_all ($io) # all
496 0..9 $csv->getline_all ($io, 0) # all
497 8..9 $csv->getline_all ($io, 8) # start at 8
498 - $csv->getline_all ($io, 0, 0) # start at 0 first 0 rows
499 0..4 $csv->getline_all ($io, 0, 5) # start at 0 first 5 rows
500 4..5 $csv->getline_all ($io, 4, 2) # start at 4 first 2 rows
501 8..9 $csv->getline_all ($io, -2) # last 2 rows
502 6..7 $csv->getline_all ($io, -4, 2) # first 2 of last 4 rows
503 parse
505 $status = $csv->parse ($line);
506 This object function decomposes a CSV string into fields, returning
508 success or failure. Failure can result from a lack of argument or the
509 given CSV string is improperly formatted. Upon success, "fields ()"
510 can be called to retrieve the decomposed fields . Upon failure, the
511 value returned by "fields ()" is undefined and "error_input ()" can be
512 called to retrieve the invalid argument.
513 You may use the types () method for setting column types. See the
515 description below.
516 getline_hr
518 The "getline_hr ()" and "column_names ()" methods work together to
519 allow you to have rows returned as hashrefs. You must call
520 "column_names ()" first to declare your column names.
521 $csv->column_names (qw( code name price description ));
523 $hr = $csv->getline_hr ($io);
524 print "Price for $hr->{name} is $hr->{price} EUR\n";
525 "getline_hr ()" will croak if called before "column_names ()".
527 getline_hr_all
529 $arrayref = $csv->getline_hr_all ($io);
530 $arrayref = $csv->getline_hr_all ($io, $offset);
531 $arrayref = $csv->getline_hr_all ($io, $offset, $length);
532 This will return a reference to a list of "getline_hr ($io)" results.
534 In this call, "keep_meta_info" is disabled.
535 column_names
537 Set the keys that will be used in the "getline_hr ()" calls. If no keys
538 (column names) are passed, it'll return the current setting.
539 "column_names ()" accepts a list of scalars (the column names) or a
541 single array_ref, so you can pass "getline ()"
542 $csv->column_names ($csv->getline ($io));
544 "column_names ()" does no checking on duplicates at all, which might
546 lead to unwanted results. Undefined entries will be replaced with the
547 string "\cAUNDEF\cA", so
548 $csv->column_names (undef, "", "name", "name");
550 $hr = $csv->getline_hr ($io);
551 Will set "$hr-"{"\cAUNDEF\cA"}> to the 1st field, "$hr-"{""}> to the
553 2nd field, and "$hr-"{name}> to the 4th field, discarding the 3rd
554 field.
555 "column_names ()" croaks on invalid arguments.
557 bind_columns
559 Takes a list of references to scalars to store the fields fetched
560 "getline ()" in. When you don't pass enough references to store the
561 fetched fields in, "getline ()" will fail. If you pass more than there
562 are fields to return, the remaining references are left untouched.
563 $csv->bind_columns (\$code, \$name, \$price, \$description);
565 while ($csv->getline ($io)) {
566 print "The price of a $name is \x{20ac} $price\n";
567 }
568 eof
570 $eof = $csv->eof ();
571 If "parse ()" or "getline ()" was used with an IO stream, this method
573 will return true (1) if the last call hit end of file, otherwise it
574 will return false (''). This is useful to see the difference between a
575 failure and end of file.
576 types
578 $csv->types (\@tref);
579 This method is used to force that columns are of a given type. For
581 example, if you have an integer column, two double columns and a string
582 column, then you might do a
583 $csv->types ([Text::CSV::IV (),
585 Text::CSV::NV (),
586 Text::CSV::NV (),
587 Text::CSV::PV ()]);
588 Column types are used only for decoding columns, in other words by the
590 parse () and getline () methods.
591 You can unset column types by doing a
593 $csv->types (undef);
595 or fetch the current type settings with
597 $types = $csv->types ();
599 IV Set field type to integer.
601 NV Set field type to numeric/float.
603 PV Set field type to string.
605 fields
607 @columns = $csv->fields ();
608 This object function returns the input to "combine ()" or the resultant
610 decomposed fields of C successful <parse ()>, whichever was called more
611 recently.
612 Note that the return value is undefined after using "getline ()", which
614 does not fill the data structures returned by "parse ()".
615 meta_info
617 @flags = $csv->meta_info ();
618 This object function returns the flags of the input to "combine ()" or
620 the flags of the resultant decomposed fields of "parse ()", whichever
621 was called more recently.
622 For each field, a meta_info field will hold flags that tell something
624 about the field returned by the "fields ()" method or passed to the
625 "combine ()" method. The flags are bit-wise-or'd like:
626 0x0001
628 The field was quoted.
629 0x0002
631 The field was binary.
632 See the "is_*** ()" methods below.
634 is_quoted
636 my $quoted = $csv->is_quoted ($column_idx);
637 Where $column_idx is the (zero-based) index of the column in the last
639 result of "parse ()".
640 This returns a true value if the data in the indicated column was
642 enclosed in "quote_char" quotes. This might be important for data where
643 ",20070108," is to be treated as a numeric value, and where
644 ","20070108"," is explicitly marked as character string data.
645 is_binary
647 my $binary = $csv->is_binary ($column_idx);
648 Where $column_idx is the (zero-based) index of the column in the last
650 result of "parse ()".
651 This returns a true value if the data in the indicated column contained
653 any byte in the range [\x00-\x08,\x10-\x1F,\x7F-\xFF]
654 status
656 $status = $csv->status ();
657 This object function returns success (or failure) of "combine ()" or
659 "parse ()", whichever was called more recently.
660 error_input
662 $bad_argument = $csv->error_input ();
663 This object function returns the erroneous argument (if it exists) of
665 "combine ()" or "parse ()", whichever was called more recently.
666 error_diag
668 Text::CSV->error_diag ();
669 $csv->error_diag ();
670 $error_code = 0 + $csv->error_diag ();
671 $error_str = "" . $csv->error_diag ();
672 ($cde, $str, $pos) = $csv->error_diag ();
673 If (and only if) an error occured, this function returns the
675 diagnostics of that error.
676 If called in void context, it will print the internal error code and
678 the associated error message to STDERR.
679 If called in list context, it will return the error code and the error
681 message in that order. If the last error was from parsing, the third
682 value returned is the best guess at the location within the line that
683 was being parsed. It's value is 1-based.
684 Note: $pos returned by the backend Text::CSV_PP does not show the error
686 point in many cases (see to the below line). It is for conscience's
687 sake in using Text::CSV_PP.
688 If called in scalar context, it will return the diagnostics in a single
690 scalar, a-la $!. It will contain the error code in numeric context, and
691 the diagnostics message in string context.
692 Depending on the used worker module, returned diagnostics is
694 diffferent.
695 Text::CSV_XS parses csv strings by dividing one character while
697 Text::CSV_PP by using the regular expressions. That difference makes
698 the different cause of the failure.
699 When called as a class method or a direct function call, the error diag
701 is that of the last "new ()" call.
702 SetDiag
704 $csv->SetDiag (0);
705 Use to reset the diagnostics if you are dealing with errors.
707 Some methods are Text::CSV only.
709 backend
710 Returns the backend module name called by Text::CSV. "module" is
711 an alias.
712 is_xs
714 Returns true value if Text::CSV or the object uses XS module as
715 worker.
716 is_pp
718 Returns true value if Text::CSV or the object uses pure-Perl module
719 as worker.
720
722 If an error occured, $csv->error_diag () can be used to get more
723 information on the cause of the failure. Note that for speed reasons,
724 the internal value is never cleared on success, so using the value
725 returned by error_diag () in normal cases - when no error occured - may
726 cause unexpected results.
727 This function changes depending on the used module (XS or PurePerl).
729 See to "DIAGNOSTICS" in Text::CSV_XS and "DIAGNOSTICS" in Text::CSV_PP.
731 HISTORY AND WORKER MODULES
733 This module, Text::CSV was firstly written by Alan Citterman which
734 could deal with only ascii characters. Then, Jochen Wiedmann wrote
735 Text::CSV_XS which has the binary mode. This XS version is maintained
736 by H.Merijn Brand and Text::CSV_PP written by Makamaka was pure-Perl
737 version of Text::CSV_XS.
738 Now, Text::CSV was rewritten by Makamaka and become a wrapper to
740 Text::CSV_XS or Text::CSV_PP. Text::CSV_PP will be bundled in this
741 distribution.
742 When you use Text::CSV, it calls a backend worker module - Text::CSV_XS
744 or Text::CSV_PP. By default, Text::CSV tries to use Text::CSV_XS which
745 must be complied and installed properly. If this call is fail,
746 Text::CSV uses Text::CSV_PP.
747 The required Text::CSV_XS version is 0.41 in Text::CSV version 1.03.
749 If you set an enviornment variable "PERL_TEXT_CSV", The calling action
751 will be changed.
752 PERL_TEXT_CSV = 0
754 PERL_TEXT_CSV = 'Text::CSV_PP'
755 Always use Text::CSV_PP
756 PERL_TEXT_CSV = 1
758 PERL_TEXT_CSV = 'Text::CSV_XS,Text::CSV_PP'
759 (The default) Use compiled Text::CSV_XS if it is properly compiled
760 & installed, otherwise use Text::CSV_PP
761 PERL_TEXT_CSV = 2
763 PERL_TEXT_CSV = 'Text::CSV_XS'
764 Always use compiled Text::CSV_XS, die if it isn't properly compiled
765 & installed.
766 These ideas come from DBI::PurePerl mechanism.
768 example:
770 BEGIN { $ENV{PERL_TEXT_CSV} = 0 }
772 use Text::CSV; # always uses Text::CSV_PP
773 In future, it may be able to specify another module.
775
777 Wrapper mechanism
778 Currently the wrapper mechanism is to change symbolic table for
779 speed.
780 for my $method (@PublicMethods) {
782 *{"Text::CSV::$method"} = \&{"$class\::$method"};
783 }
784 But how about it - calling worker module object?
786 sub parse {
788 my $self = shift;
789 $self->{_WORKER_OBJECT}->parse(@_); # XS or PP CSV object
790 }
791 See to "TODO" in Text::CSV_XS and "TODO" in Text::CSV_PP.
793
795 Text::CSV_PP, Text::CSV_XS and Text::CSV::Encoded.
796
798 Alan Citterman <alan[at]mfgrtl.com> wrote the original Perl module.
799 Please don't send mail concerning Text::CSV to Alan, as he's not a
800 present maintainer.
801 Jochen Wiedmann <joe[at]ispsoft.de> rewrote the encoding and decoding
803 in C by implementing a simple finite-state machine and added the
804 variable quote, escape and separator characters, the binary mode and
805 the print and getline methods. See ChangeLog releases 0.10 through
806 0.23.
807 H.Merijn Brand <h.m.brand[at]xs4all.nl> cleaned up the code, added the
809 field flags methods, wrote the major part of the test suite, completed
810 the documentation, fixed some RT bugs. See ChangeLog releases 0.25 and
811 on.
812 Makamaka Hannyaharamitu, <makamaka[at]cpan.org> wrote Text::CSV_PP
814 which is the pure-Perl version of Text::CSV_XS.
815 New Text::CSV (since 0.99) is maintained by Makamaka.
817
819 Text::CSV
820 Copyright (C) 1997 Alan Citterman. All rights reserved. Copyright (C)
822 2007-2009 Makamaka Hannyaharamitu.
823 Text::CSV_PP:
825 Copyright (C) 2005-2010 Makamaka Hannyaharamitu.
827 Text:CSV_XS:
829 Copyright (C) 2007-2010 H.Merijn Brand for PROCURA B.V. Copyright (C)
831 1998-2001 Jochen Wiedmann. All rights reserved. Portions Copyright (C)
832 1997 Alan Citterman. All rights reserved.
833 This library is free software; you can redistribute it and/or modify it
835 under the same terms as Perl itself.
836perl v5.12.3 2010-12-27 Text::CSV(3)