1Text::CSV_PP(3) User Contributed Perl Documentation Text::CSV_PP(3)
2
6 Text::CSV_PP - Text::CSV_XS compatible pure-Perl module
7
9 This section is taken from Text::CSV_XS.
10 # Functional interface
12 use Text::CSV_PP qw( csv );
13 # Read whole file in memory
15 my $aoa = csv (in => "data.csv"); # as array of array
16 my $aoh = csv (in => "data.csv",
17 headers => "auto"); # as array of hash
18 # Write array of arrays as csv file
20 csv (in => $aoa, out => "file.csv", sep_char=> ";");
21 # Only show lines where "code" is odd
23 csv (in => "data.csv", filter => { code => sub { $_ % 2 }});
24 # Object interface
26 use Text::CSV_PP;
27 my @rows;
29 # Read/parse CSV
30 my $csv = Text::CSV_PP->new ({ binary => 1, auto_diag => 1 });
31 open my $fh, "<:encoding(utf8)", "test.csv" or die "test.csv: $!";
32 while (my $row = $csv->getline ($fh)) {
33 $row->[2] =~ m/pattern/ or next; # 3rd field should match
34 push @rows, $row;
35 }
36 close $fh;
37 # and write as CSV
39 open $fh, ">:encoding(utf8)", "new.csv" or die "new.csv: $!";
40 $csv->say ($fh, $_) for @rows;
41 close $fh or die "new.csv: $!";
42
44 Text::CSV_PP is a pure-perl module that provides facilities for the
45 composition and decomposition of comma-separated values. This is
46 (almost) compatible with much faster Text::CSV_XS, and mainly used as
47 its fallback module when you use Text::CSV module without having
48 installed Text::CSV_XS. If you don't have any reason to use this module
49 directly, use Text::CSV for speed boost and portability (or maybe
50 Text::CSV_XS when you write an one-off script and don't need to care
51 about portability).
52 The following caveats are taken from the doc of Text::CSV_XS.
54 Embedded newlines
56 Important Note: The default behavior is to accept only ASCII
57 characters in the range from 0x20 (space) to 0x7E (tilde). This means
58 that the fields can not contain newlines. If your data contains
59 newlines embedded in fields, or characters above 0x7E (tilde), or
60 binary data, you must set "binary => 1" in the call to "new". To cover
61 the widest range of parsing options, you will always want to set
62 binary.
63 But you still have the problem that you have to pass a correct line to
65 the "parse" method, which is more complicated from the usual point of
66 usage:
67 my $csv = Text::CSV_PP->new ({ binary => 1, eol => $/ });
69 while (<>) { # WRONG!
70 $csv->parse ($_);
71 my @fields = $csv->fields ();
72 }
73 this will break, as the "while" might read broken lines: it does not
75 care about the quoting. If you need to support embedded newlines, the
76 way to go is to not pass "eol" in the parser (it accepts "\n", "\r",
77 and "\r\n" by default) and then
78 my $csv = Text::CSV_PP->new ({ binary => 1 });
80 open my $fh, "<", $file or die "$file: $!";
81 while (my $row = $csv->getline ($fh)) {
82 my @fields = @$row;
83 }
84 The old(er) way of using global file handles is still supported
86 while (my $row = $csv->getline (*ARGV)) { ... }
88 Unicode
90 Unicode is only tested to work with perl-5.8.2 and up.
91 See also "BOM".
93 The simplest way to ensure the correct encoding is used for in- and
95 output is by either setting layers on the filehandles, or setting the
96 "encoding" argument for "csv".
97 open my $fh, "<:encoding(UTF-8)", "in.csv" or die "in.csv: $!";
99 or
100 my $aoa = csv (in => "in.csv", encoding => "UTF-8");
101 open my $fh, ">:encoding(UTF-8)", "out.csv" or die "out.csv: $!";
103 or
104 csv (in => $aoa, out => "out.csv", encoding => "UTF-8");
105 On parsing (both for "getline" and "parse"), if the source is marked
107 being UTF8, then all fields that are marked binary will also be marked
108 UTF8.
109 On combining ("print" and "combine"): if any of the combining fields
111 was marked UTF8, the resulting string will be marked as UTF8. Note
112 however that all fields before the first field marked UTF8 and
113 contained 8-bit characters that were not upgraded to UTF8, these will
114 be "bytes" in the resulting string too, possibly causing unexpected
115 errors. If you pass data of different encoding, or you don't know if
116 there is different encoding, force it to be upgraded before you pass
117 them on:
118 $csv->print ($fh, [ map { utf8::upgrade (my $x = $_); $x } @data ]);
120 For complete control over encoding, please use Text::CSV::Encoded:
122 use Text::CSV::Encoded;
124 my $csv = Text::CSV::Encoded->new ({
125 encoding_in => "iso-8859-1", # the encoding comes into Perl
126 encoding_out => "cp1252", # the encoding comes out of Perl
127 });
128 $csv = Text::CSV::Encoded->new ({ encoding => "utf8" });
130 # combine () and print () accept *literally* utf8 encoded data
131 # parse () and getline () return *literally* utf8 encoded data
132 $csv = Text::CSV::Encoded->new ({ encoding => undef }); # default
134 # combine () and print () accept UTF8 marked data
135 # parse () and getline () return UTF8 marked data
136 BOM
138 BOM (or Byte Order Mark) handling is available only inside the
139 "header" method. This method supports the following encodings:
140 "utf-8", "utf-1", "utf-32be", "utf-32le", "utf-16be", "utf-16le",
141 "utf-ebcdic", "scsu", "bocu-1", and "gb-18030". See Wikipedia
142 <https://en.wikipedia.org/wiki/Byte_order_mark>.
143 If a file has a BOM, the easiest way to deal with that is
145 my $aoh = csv (in => $file, detect_bom => 1);
147 All records will be encoded based on the detected BOM.
149 This implies a call to the "header" method, which defaults to also
151 set the "column_names". So this is not the same as
152 my $aoh = csv (in => $file, headers => "auto");
154 which only reads the first record to set "column_names" but ignores
156 any meaning of possible present BOM.
157
159 This section is also taken from Text::CSV_XS.
160 version
162 (Class method) Returns the current module version.
163 new
165 (Class method) Returns a new instance of class Text::CSV_PP. The
166 attributes are described by the (optional) hash ref "\%attr".
167 my $csv = Text::CSV_PP->new ({ attributes ... });
169 The following attributes are available:
171 eol
173 my $csv = Text::CSV_PP->new ({ eol => $/ });
175 $csv->eol (undef);
176 my $eol = $csv->eol;
177 The end-of-line string to add to rows for "print" or the record
179 separator for "getline".
180 When not passed in a parser instance, the default behavior is to
182 accept "\n", "\r", and "\r\n", so it is probably safer to not specify
183 "eol" at all. Passing "undef" or the empty string behave the same.
184 When not passed in a generating instance, records are not terminated
186 at all, so it is probably wise to pass something you expect. A safe
187 choice for "eol" on output is either $/ or "\r\n".
188 Common values for "eol" are "\012" ("\n" or Line Feed), "\015\012"
190 ("\r\n" or Carriage Return, Line Feed), and "\015" ("\r" or Carriage
191 Return). The "eol" attribute cannot exceed 7 (ASCII) characters.
192 If both $/ and "eol" equal "\015", parsing lines that end on only a
194 Carriage Return without Line Feed, will be "parse"d correct.
195 sep_char
197 my $csv = Text::CSV_PP->new ({ sep_char => ";" });
199 $csv->sep_char (";");
200 my $c = $csv->sep_char;
201 The char used to separate fields, by default a comma. (","). Limited
203 to a single-byte character, usually in the range from 0x20 (space) to
204 0x7E (tilde). When longer sequences are required, use "sep".
205 The separation character can not be equal to the quote character or to
207 the escape character.
208 sep
210 my $csv = Text::CSV_PP->new ({ sep => "\N{FULLWIDTH COMMA}" });
212 $csv->sep (";");
213 my $sep = $csv->sep;
214 The chars used to separate fields, by default undefined. Limited to 8
216 bytes.
217 When set, overrules "sep_char". If its length is one byte it acts as
219 an alias to "sep_char".
220 quote_char
222 my $csv = Text::CSV_PP->new ({ quote_char => "'" });
224 $csv->quote_char (undef);
225 my $c = $csv->quote_char;
226 The character to quote fields containing blanks or binary data, by
228 default the double quote character ("""). A value of undef suppresses
229 quote chars (for simple cases only). Limited to a single-byte
230 character, usually in the range from 0x20 (space) to 0x7E (tilde).
231 When longer sequences are required, use "quote".
232 "quote_char" can not be equal to "sep_char".
234 quote
236 my $csv = Text::CSV_PP->new ({ quote => "\N{FULLWIDTH QUOTATION MARK}" });
238 $csv->quote ("'");
239 my $quote = $csv->quote;
240 The chars used to quote fields, by default undefined. Limited to 8
242 bytes.
243 When set, overrules "quote_char". If its length is one byte it acts as
245 an alias to "quote_char".
246 escape_char
248 my $csv = Text::CSV_PP->new ({ escape_char => "\\" });
250 $csv->escape_char (":");
251 my $c = $csv->escape_char;
252 The character to escape certain characters inside quoted fields.
254 This is limited to a single-byte character, usually in the range
255 from 0x20 (space) to 0x7E (tilde).
256 The "escape_char" defaults to being the double-quote mark ("""). In
258 other words the same as the default "quote_char". This means that
259 doubling the quote mark in a field escapes it:
260 "foo","bar","Escape ""quote mark"" with two ""quote marks""","baz"
262 If you change the "quote_char" without changing the
264 "escape_char", the "escape_char" will still be the double-quote
265 ("""). If instead you want to escape the "quote_char" by doubling it
266 you will need to also change the "escape_char" to be the same as what
267 you have changed the "quote_char" to.
268 Setting "escape_char" to <undef> or "" will disable escaping completely
270 and is greatly discouraged. This will also disable "escape_null".
271 The escape character can not be equal to the separation character.
273 binary
275 my $csv = Text::CSV_PP->new ({ binary => 1 });
277 $csv->binary (0);
278 my $f = $csv->binary;
279 If this attribute is 1, you may use binary characters in quoted
281 fields, including line feeds, carriage returns and "NULL" bytes. (The
282 latter could be escaped as ""0".) By default this feature is off.
283 If a string is marked UTF8, "binary" will be turned on automatically
285 when binary characters other than "CR" and "NL" are encountered. Note
286 that a simple string like "\x{00a0}" might still be binary, but not
287 marked UTF8, so setting "{ binary => 1 }" is still a wise option.
288 strict
290 my $csv = Text::CSV_PP->new ({ strict => 1 });
292 $csv->strict (0);
293 my $f = $csv->strict;
294 If this attribute is set to 1, any row that parses to a different
296 number of fields than the previous row will cause the parser to throw
297 error 2014.
298 formula_handling
300 formula
302 my $csv = Text::CSV_PP->new ({ formula => "none" });
304 $csv->formula ("none");
305 my $f = $csv->formula;
306 This defines the behavior of fields containing formulas. As formulas
308 are considered dangerous in spreadsheets, this attribute can define an
309 optional action to be taken if a field starts with an equal sign ("=").
310 For purpose of code-readability, this can also be written as
312 my $csv = Text::CSV_PP->new ({ formula_handling => "none" });
314 $csv->formula_handling ("none");
315 my $f = $csv->formula_handling;
316 Possible values for this attribute are
318 none
320 Take no specific action. This is the default.
321 $csv->formula ("none");
323 die
325 Cause the process to "die" whenever a leading "=" is encountered.
326 $csv->formula ("die");
328 croak
330 Cause the process to "croak" whenever a leading "=" is encountered.
331 (See Carp)
332 $csv->formula ("croak");
334 diag
336 Report position and content of the field whenever a leading "=" is
337 found. The value of the field is unchanged.
338 $csv->formula ("diag");
340 empty
342 Replace the content of fields that start with a "=" with the empty
343 string.
344 $csv->formula ("empty");
346 $csv->formula ("");
347 undef
349 Replace the content of fields that start with a "=" with "undef".
350 $csv->formula ("undef");
352 $csv->formula (undef);
353 All other values will give a warning and then fallback to "diag".
355 decode_utf8
357 my $csv = Text::CSV_PP->new ({ decode_utf8 => 1 });
359 $csv->decode_utf8 (0);
360 my $f = $csv->decode_utf8;
361 This attributes defaults to TRUE.
363 While parsing, fields that are valid UTF-8, are automatically set to
365 be UTF-8, so that
366 $csv->parse ("\xC4\xA8\n");
368 results in
370 PV("\304\250"\0) [UTF8 "\x{128}"]
372 Sometimes it might not be a desired action. To prevent those upgrades,
374 set this attribute to false, and the result will be
375 PV("\304\250"\0)
377 auto_diag
379 my $csv = Text::CSV_PP->new ({ auto_diag => 1 });
381 $csv->auto_diag (2);
382 my $l = $csv->auto_diag;
383 Set this attribute to a number between 1 and 9 causes "error_diag" to
385 be automatically called in void context upon errors.
386 In case of error "2012 - EOF", this call will be void.
388 If "auto_diag" is set to a numeric value greater than 1, it will "die"
390 on errors instead of "warn". If set to anything unrecognized, it will
391 be silently ignored.
392 Future extensions to this feature will include more reliable auto-
394 detection of "autodie" being active in the scope of which the error
395 occurred which will increment the value of "auto_diag" with 1 the
396 moment the error is detected.
397 diag_verbose
399 my $csv = Text::CSV_PP->new ({ diag_verbose => 1 });
401 $csv->diag_verbose (2);
402 my $l = $csv->diag_verbose;
403 Set the verbosity of the output triggered by "auto_diag". Currently
405 only adds the current input-record-number (if known) to the
406 diagnostic output with an indication of the position of the error.
407 blank_is_undef
409 my $csv = Text::CSV_PP->new ({ blank_is_undef => 1 });
411 $csv->blank_is_undef (0);
412 my $f = $csv->blank_is_undef;
413 Under normal circumstances, "CSV" data makes no distinction between
415 quoted- and unquoted empty fields. These both end up in an empty
416 string field once read, thus
417 1,"",," ",2
419 is read as
421 ("1", "", "", " ", "2")
423 When writing "CSV" files with either "always_quote" or "quote_empty"
425 set, the unquoted empty field is the result of an undefined value.
426 To enable this distinction when reading "CSV" data, the
427 "blank_is_undef" attribute will cause unquoted empty fields to be set
428 to "undef", causing the above to be parsed as
429 ("1", "", undef, " ", "2")
431 note that this is specifically important when loading "CSV" fields
433 into a database that allows "NULL" values, as the perl equivalent for
434 "NULL" is "undef" in DBI land.
435 empty_is_undef
437 my $csv = Text::CSV_PP->new ({ empty_is_undef => 1 });
439 $csv->empty_is_undef (0);
440 my $f = $csv->empty_is_undef;
441 Going one step further than "blank_is_undef", this attribute
443 converts all empty fields to "undef", so
444 1,"",," ",2
446 is read as
448 (1, undef, undef, " ", 2)
450 Note that this effects only fields that are originally empty, not
452 fields that are empty after stripping allowed whitespace. YMMV.
453 allow_whitespace
455 my $csv = Text::CSV_PP->new ({ allow_whitespace => 1 });
457 $csv->allow_whitespace (0);
458 my $f = $csv->allow_whitespace;
459 When this option is set to true, the whitespace ("TAB"'s and
461 "SPACE"'s) surrounding the separation character is removed when
462 parsing. If either "TAB" or "SPACE" is one of the three characters
463 "sep_char", "quote_char", or "escape_char" it will not be considered
464 whitespace.
465 Now lines like:
467 1 , "foo" , bar , 3 , zapp
469 are parsed as valid "CSV", even though it violates the "CSV" specs.
471 Note that all whitespace is stripped from both start and end of
473 each field. That would make it more than a feature to enable parsing
474 bad "CSV" lines, as
475 1, 2.0, 3, ape , monkey
477 will now be parsed as
479 ("1", "2.0", "3", "ape", "monkey")
481 even if the original line was perfectly acceptable "CSV".
483 allow_loose_quotes
485 my $csv = Text::CSV_PP->new ({ allow_loose_quotes => 1 });
487 $csv->allow_loose_quotes (0);
488 my $f = $csv->allow_loose_quotes;
489 By default, parsing unquoted fields containing "quote_char" characters
491 like
492 1,foo "bar" baz,42
494 would result in parse error 2034. Though it is still bad practice to
496 allow this format, we cannot help the fact that some vendors
497 make their applications spit out lines styled this way.
498 If there is really bad "CSV" data, like
500 1,"foo "bar" baz",42
502 or
504 1,""foo bar baz"",42
506 there is a way to get this data-line parsed and leave the quotes inside
508 the quoted field as-is. This can be achieved by setting
509 "allow_loose_quotes" AND making sure that the "escape_char" is not
510 equal to "quote_char".
511 allow_loose_escapes
513 my $csv = Text::CSV_PP->new ({ allow_loose_escapes => 1 });
515 $csv->allow_loose_escapes (0);
516 my $f = $csv->allow_loose_escapes;
517 Parsing fields that have "escape_char" characters that escape
519 characters that do not need to be escaped, like:
520 my $csv = Text::CSV_PP->new ({ escape_char => "\\" });
522 $csv->parse (qq{1,"my bar\'s",baz,42});
523 would result in parse error 2025. Though it is bad practice to allow
525 this format, this attribute enables you to treat all escape character
526 sequences equal.
527 allow_unquoted_escape
529 my $csv = Text::CSV_PP->new ({ allow_unquoted_escape => 1 });
531 $csv->allow_unquoted_escape (0);
532 my $f = $csv->allow_unquoted_escape;
533 A backward compatibility issue where "escape_char" differs from
535 "quote_char" prevents "escape_char" to be in the first position of a
536 field. If "quote_char" is equal to the default """ and "escape_char"
537 is set to "\", this would be illegal:
538 1,\0,2
540 Setting this attribute to 1 might help to overcome issues with
542 backward compatibility and allow this style.
543 always_quote
545 my $csv = Text::CSV_PP->new ({ always_quote => 1 });
547 $csv->always_quote (0);
548 my $f = $csv->always_quote;
549 By default the generated fields are quoted only if they need to be.
551 For example, if they contain the separator character. If you set this
552 attribute to 1 then all defined fields will be quoted. ("undef" fields
553 are not quoted, see "blank_is_undef"). This makes it quite often easier
554 to handle exported data in external applications.
555 quote_space
557 my $csv = Text::CSV_PP->new ({ quote_space => 1 });
559 $csv->quote_space (0);
560 my $f = $csv->quote_space;
561 By default, a space in a field would trigger quotation. As no rule
563 exists this to be forced in "CSV", nor any for the opposite, the
564 default is true for safety. You can exclude the space from this
565 trigger by setting this attribute to 0.
566 quote_empty
568 my $csv = Text::CSV_PP->new ({ quote_empty => 1 });
570 $csv->quote_empty (0);
571 my $f = $csv->quote_empty;
572 By default the generated fields are quoted only if they need to be.
574 An empty (defined) field does not need quotation. If you set this
575 attribute to 1 then empty defined fields will be quoted. ("undef"
576 fields are not quoted, see "blank_is_undef"). See also "always_quote".
577 quote_binary
579 my $csv = Text::CSV_PP->new ({ quote_binary => 1 });
581 $csv->quote_binary (0);
582 my $f = $csv->quote_binary;
583 By default, all "unsafe" bytes inside a string cause the combined
585 field to be quoted. By setting this attribute to 0, you can disable
586 that trigger for bytes >= 0x7F.
587 escape_null
589 my $csv = Text::CSV_PP->new ({ escape_null => 1 });
591 $csv->escape_null (0);
592 my $f = $csv->escape_null;
593 By default, a "NULL" byte in a field would be escaped. This option
595 enables you to treat the "NULL" byte as a simple binary character in
596 binary mode (the "{ binary => 1 }" is set). The default is true. You
597 can prevent "NULL" escapes by setting this attribute to 0.
598 When the "escape_char" attribute is set to undefined, this attribute
600 will be set to false.
601 The default setting will encode "=\x00=" as
603 "="0="
605 With "escape_null" set, this will result in
607 "=\x00="
609 The default when using the "csv" function is "false".
611 For backward compatibility reasons, the deprecated old name
613 "quote_null" is still recognized.
614 keep_meta_info
616 my $csv = Text::CSV_PP->new ({ keep_meta_info => 1 });
618 $csv->keep_meta_info (0);
619 my $f = $csv->keep_meta_info;
620 By default, the parsing of input records is as simple and fast as
622 possible. However, some parsing information - like quotation of the
623 original field - is lost in that process. Setting this flag to true
624 enables retrieving that information after parsing with the methods
625 "meta_info", "is_quoted", and "is_binary" described below. Default is
626 false for performance.
627 If you set this attribute to a value greater than 9, than you can
629 control output quotation style like it was used in the input of the the
630 last parsed record (unless quotation was added because of other
631 reasons).
632 my $csv = Text::CSV_PP->new ({
634 binary => 1,
635 keep_meta_info => 1,
636 quote_space => 0,
637 });
638 my $row = $csv->parse (q{1,,"", ," ",f,"g","h""h",help,"help"});
640 $csv->print (*STDOUT, \@row);
642 # 1,,, , ,f,g,"h""h",help,help
643 $csv->keep_meta_info (11);
644 $csv->print (*STDOUT, \@row);
645 # 1,,"", ," ",f,"g","h""h",help,"help"
646 undef_str
648 my $csv = Text::CSV_PP->new ({ undef_str => "\\N" });
650 $csv->undef_str (undef);
651 my $s = $csv->undef_str;
652 This attribute optionally defines the output of undefined fields. The
654 value passed is not changed at all, so if it needs quotation, the
655 quotation needs to be included in the value of the attribute. Use with
656 caution, as passing a value like ",",,,,""" will for sure mess up
657 your output. The default for this attribute is "undef", meaning no
658 special treatment.
659 This attribute is useful when exporting CSV data to be imported in
661 custom loaders, like for MySQL, that recognize special sequences for
662 "NULL" data.
663 This attribute has no meaning when parsing CSV data.
665 verbatim
667 my $csv = Text::CSV_PP->new ({ verbatim => 1 });
669 $csv->verbatim (0);
670 my $f = $csv->verbatim;
671 This is a quite controversial attribute to set, but makes some hard
673 things possible.
674 The rationale behind this attribute is to tell the parser that the
676 normally special characters newline ("NL") and Carriage Return ("CR")
677 will not be special when this flag is set, and be dealt with as being
678 ordinary binary characters. This will ease working with data with
679 embedded newlines.
680 When "verbatim" is used with "getline", "getline" auto-"chomp"'s
682 every line.
683 Imagine a file format like
685 M^^Hans^Janssen^Klas 2\n2A^Ja^11-06-2007#\r\n
687 where, the line ending is a very specific "#\r\n", and the sep_char is
689 a "^" (caret). None of the fields is quoted, but embedded binary
690 data is likely to be present. With the specific line ending, this
691 should not be too hard to detect.
692 By default, Text::CSV_PP' parse function is instructed to only know
694 about "\n" and "\r" to be legal line endings, and so has to deal with
695 the embedded newline as a real "end-of-line", so it can scan the next
696 line if binary is true, and the newline is inside a quoted field. With
697 this option, we tell "parse" to parse the line as if "\n" is just
698 nothing more than a binary character.
699 For "parse" this means that the parser has no more idea about line
701 ending and "getline" "chomp"s line endings on reading.
702 types
704 A set of column types; the attribute is immediately passed to the
706 "types" method.
707 callbacks
709 See the "Callbacks" section below.
711 accessors
713 To sum it up,
715 $csv = Text::CSV_PP->new ();
717 is equivalent to
719 $csv = Text::CSV_PP->new ({
721 eol => undef, # \r, \n, or \r\n
722 sep_char => ',',
723 sep => undef,
724 quote_char => '"',
725 quote => undef,
726 escape_char => '"',
727 binary => 0,
728 decode_utf8 => 1,
729 auto_diag => 0,
730 diag_verbose => 0,
731 blank_is_undef => 0,
732 empty_is_undef => 0,
733 allow_whitespace => 0,
734 allow_loose_quotes => 0,
735 allow_loose_escapes => 0,
736 allow_unquoted_escape => 0,
737 always_quote => 0,
738 quote_empty => 0,
739 quote_space => 1,
740 escape_null => 1,
741 quote_binary => 1,
742 keep_meta_info => 0,
743 strict => 0,
744 formula => 0,
745 verbatim => 0,
746 undef_str => undef,
747 types => undef,
748 callbacks => undef,
749 });
750 For all of the above mentioned flags, an accessor method is available
752 where you can inquire the current value, or change the value
753 my $quote = $csv->quote_char;
755 $csv->binary (1);
756 It is not wise to change these settings halfway through writing "CSV"
758 data to a stream. If however you want to create a new stream using the
759 available "CSV" object, there is no harm in changing them.
760 If the "new" constructor call fails, it returns "undef", and makes
762 the fail reason available through the "error_diag" method.
763 $csv = Text::CSV_PP->new ({ ecs_char => 1 }) or
765 die "".Text::CSV_PP->error_diag ();
766 "error_diag" will return a string like
768 "INI - Unknown attribute 'ecs_char'"
770 known_attributes
772 @attr = Text::CSV_PP->known_attributes;
773 @attr = Text::CSV_PP::known_attributes;
774 @attr = $csv->known_attributes;
775 This method will return an ordered list of all the supported
777 attributes as described above. This can be useful for knowing what
778 attributes are valid in classes that use or extend Text::CSV_PP.
779 print
781 $status = $csv->print ($fh, $colref);
782 Similar to "combine" + "string" + "print", but much more efficient.
784 It expects an array ref as input (not an array!) and the resulting
785 string is not really created, but immediately written to the $fh
786 object, typically an IO handle or any other object that offers a
787 "print" method.
788 For performance reasons "print" does not create a result string, so
790 all "string", "status", "fields", and "error_input" methods will return
791 undefined information after executing this method.
792 If $colref is "undef" (explicit, not through a variable argument) and
794 "bind_columns" was used to specify fields to be printed, it is
795 possible to make performance improvements, as otherwise data would have
796 to be copied as arguments to the method call:
797 $csv->bind_columns (\($foo, $bar));
799 $status = $csv->print ($fh, undef);
800 A short benchmark
802 my @data = ("aa" .. "zz");
804 $csv->bind_columns (\(@data));
805 $csv->print ($fh, [ @data ]); # 11800 recs/sec
807 $csv->print ($fh, \@data ); # 57600 recs/sec
808 $csv->print ($fh, undef ); # 48500 recs/sec
809 say
811 $status = $csv->say ($fh, $colref);
812 Like "print", but "eol" defaults to "$\".
814 print_hr
816 $csv->print_hr ($fh, $ref);
817 Provides an easy way to print a $ref (as fetched with "getline_hr")
819 provided the column names are set with "column_names".
820 It is just a wrapper method with basic parameter checks over
822 $csv->print ($fh, [ map { $ref->{$_} } $csv->column_names ]);
824 combine
826 $status = $csv->combine (@fields);
827 This method constructs a "CSV" record from @fields, returning success
829 or failure. Failure can result from lack of arguments or an argument
830 that contains an invalid character. Upon success, "string" can be
831 called to retrieve the resultant "CSV" string. Upon failure, the
832 value returned by "string" is undefined and "error_input" could be
833 called to retrieve the invalid argument.
834 string
836 $line = $csv->string ();
837 This method returns the input to "parse" or the resultant "CSV"
839 string of "combine", whichever was called more recently.
840 getline
842 $colref = $csv->getline ($fh);
843 This is the counterpart to "print", as "parse" is the counterpart to
845 "combine": it parses a row from the $fh handle using the "getline"
846 method associated with $fh and parses this row into an array ref.
847 This array ref is returned by the function or "undef" for failure.
848 When $fh does not support "getline", you are likely to hit errors.
849 When fields are bound with "bind_columns" the return value is a
851 reference to an empty list.
852 The "string", "fields", and "status" methods are meaningless again.
854 getline_all
856 $arrayref = $csv->getline_all ($fh);
857 $arrayref = $csv->getline_all ($fh, $offset);
858 $arrayref = $csv->getline_all ($fh, $offset, $length);
859 This will return a reference to a list of getline ($fh) results. In
861 this call, "keep_meta_info" is disabled. If $offset is negative, as
862 with "splice", only the last "abs ($offset)" records of $fh are taken
863 into consideration.
864 Given a CSV file with 10 lines:
866 lines call
868 ----- ---------------------------------------------------------
869 0..9 $csv->getline_all ($fh) # all
870 0..9 $csv->getline_all ($fh, 0) # all
871 8..9 $csv->getline_all ($fh, 8) # start at 8
872 - $csv->getline_all ($fh, 0, 0) # start at 0 first 0 rows
873 0..4 $csv->getline_all ($fh, 0, 5) # start at 0 first 5 rows
874 4..5 $csv->getline_all ($fh, 4, 2) # start at 4 first 2 rows
875 8..9 $csv->getline_all ($fh, -2) # last 2 rows
876 6..7 $csv->getline_all ($fh, -4, 2) # first 2 of last 4 rows
877 getline_hr
879 The "getline_hr" and "column_names" methods work together to allow you
880 to have rows returned as hashrefs. You must call "column_names" first
881 to declare your column names.
882 $csv->column_names (qw( code name price description ));
884 $hr = $csv->getline_hr ($fh);
885 print "Price for $hr->{name} is $hr->{price} EUR\n";
886 "getline_hr" will croak if called before "column_names".
888 Note that "getline_hr" creates a hashref for every row and will be
890 much slower than the combined use of "bind_columns" and "getline" but
891 still offering the same ease of use hashref inside the loop:
892 my @cols = @{$csv->getline ($fh)};
894 $csv->column_names (@cols);
895 while (my $row = $csv->getline_hr ($fh)) {
896 print $row->{price};
897 }
898 Could easily be rewritten to the much faster:
900 my @cols = @{$csv->getline ($fh)};
902 my $row = {};
903 $csv->bind_columns (\@{$row}{@cols});
904 while ($csv->getline ($fh)) {
905 print $row->{price};
906 }
907 Your mileage may vary for the size of the data and the number of rows.
909 With perl-5.14.2 the comparison for a 100_000 line file with 14 rows:
910 Rate hashrefs getlines
912 hashrefs 1.00/s -- -76%
913 getlines 4.15/s 313% --
914 getline_hr_all
916 $arrayref = $csv->getline_hr_all ($fh);
917 $arrayref = $csv->getline_hr_all ($fh, $offset);
918 $arrayref = $csv->getline_hr_all ($fh, $offset, $length);
919 This will return a reference to a list of getline_hr ($fh) results.
921 In this call, "keep_meta_info" is disabled.
922 parse
924 $status = $csv->parse ($line);
925 This method decomposes a "CSV" string into fields, returning success
927 or failure. Failure can result from a lack of argument or the given
928 "CSV" string is improperly formatted. Upon success, "fields" can be
929 called to retrieve the decomposed fields. Upon failure calling "fields"
930 will return undefined data and "error_input" can be called to
931 retrieve the invalid argument.
932 You may use the "types" method for setting column types. See "types"'
934 description below.
935 The $line argument is supposed to be a simple scalar. Everything else
937 is supposed to croak and set error 1500.
938 fragment
940 This function tries to implement RFC7111 (URI Fragment Identifiers for
941 the text/csv Media Type) - http://tools.ietf.org/html/rfc7111
942 my $AoA = $csv->fragment ($fh, $spec);
944 In specifications, "*" is used to specify the last item, a dash ("-")
946 to indicate a range. All indices are 1-based: the first row or
947 column has index 1. Selections can be combined with the semi-colon
948 (";").
949 When using this method in combination with "column_names", the
951 returned reference will point to a list of hashes instead of a list
952 of lists. A disjointed cell-based combined selection might return
953 rows with different number of columns making the use of hashes
954 unpredictable.
955 $csv->column_names ("Name", "Age");
957 my $AoH = $csv->fragment ($fh, "col=3;8");
958 If the "after_parse" callback is active, it is also called on every
960 line parsed and skipped before the fragment.
961 row
963 row=4
964 row=5-7
965 row=6-*
966 row=1-2;4;6-*
967 col
969 col=2
970 col=1-3
971 col=4-*
972 col=1-2;4;7-*
973 cell
975 In cell-based selection, the comma (",") is used to pair row and
976 column
977 cell=4,1
979 The range operator ("-") using "cell"s can be used to define top-left
981 and bottom-right "cell" location
982 cell=3,1-4,6
984 The "*" is only allowed in the second part of a pair
986 cell=3,2-*,2 # row 3 till end, only column 2
988 cell=3,2-3,* # column 2 till end, only row 3
989 cell=3,2-*,* # strip row 1 and 2, and column 1
990 Cells and cell ranges may be combined with ";", possibly resulting in
992 rows with different number of columns
993 cell=1,1-2,2;3,3-4,4;1,4;4,1
995 Disjointed selections will only return selected cells. The cells
997 that are not specified will not be included in the returned
998 set, not even as "undef". As an example given a "CSV" like
999 11,12,13,...19
1001 21,22,...28,29
1002 : :
1003 91,...97,98,99
1004 with "cell=1,1-2,2;3,3-4,4;1,4;4,1" will return:
1006 11,12,14
1008 21,22
1009 33,34
1010 41,43,44
1011 Overlapping cell-specs will return those cells only once, So
1013 "cell=1,1-3,3;2,2-4,4;2,3;4,2" will return:
1014 11,12,13
1016 21,22,23,24
1017 31,32,33,34
1018 42,43,44
1019 RFC7111 <http://tools.ietf.org/html/rfc7111> does not allow different
1021 types of specs to be combined (either "row" or "col" or "cell").
1022 Passing an invalid fragment specification will croak and set error
1023 2013.
1024 column_names
1026 Set the "keys" that will be used in the "getline_hr" calls. If no
1027 keys (column names) are passed, it will return the current setting as a
1028 list.
1029 "column_names" accepts a list of scalars (the column names) or a
1031 single array_ref, so you can pass the return value from "getline" too:
1032 $csv->column_names ($csv->getline ($fh));
1034 "column_names" does no checking on duplicates at all, which might lead
1036 to unexpected results. Undefined entries will be replaced with the
1037 string "\cAUNDEF\cA", so
1038 $csv->column_names (undef, "", "name", "name");
1040 $hr = $csv->getline_hr ($fh);
1041 Will set "$hr->{"\cAUNDEF\cA"}" to the 1st field, "$hr->{""}" to the
1043 2nd field, and "$hr->{name}" to the 4th field, discarding the 3rd
1044 field.
1045 "column_names" croaks on invalid arguments.
1047 header
1049 This method does NOT work in perl-5.6.x
1050 Parse the CSV header and set "sep", column_names and encoding.
1052 my @hdr = $csv->header ($fh);
1054 $csv->header ($fh, { sep_set => [ ";", ",", "|", "\t" ] });
1055 $csv->header ($fh, { detect_bom => 1, munge_column_names => "lc" });
1056 The first argument should be a file handle.
1058 This method resets some object properties, as it is supposed to be
1060 invoked only once per file or stream. It will leave attributes
1061 "column_names" and "bound_columns" alone of setting column names is
1062 disabled. Reading headers on previously process objects might fail on
1063 perl-5.8.0 and older.
1064 Assuming that the file opened for parsing has a header, and the header
1066 does not contain problematic characters like embedded newlines, read
1067 the first line from the open handle then auto-detect whether the header
1068 separates the column names with a character from the allowed separator
1069 list.
1070 If any of the allowed separators matches, and none of the other
1072 allowed separators match, set "sep" to that separator for the
1073 current CSV_PP instance and use it to parse the first line, map those
1074 to lowercase, and use that to set the instance "column_names":
1075 my $csv = Text::CSV_PP->new ({ binary => 1, auto_diag => 1 });
1077 open my $fh, "<", "file.csv";
1078 binmode $fh; # for Windows
1079 $csv->header ($fh);
1080 while (my $row = $csv->getline_hr ($fh)) {
1081 ...
1082 }
1083 If the header is empty, contains more than one unique separator out of
1085 the allowed set, contains empty fields, or contains identical fields
1086 (after folding), it will croak with error 1010, 1011, 1012, or 1013
1087 respectively.
1088 If the header contains embedded newlines or is not valid CSV in any
1090 other way, this method will croak and leave the parse error untouched.
1091 A successful call to "header" will always set the "sep" of the $csv
1093 object. This behavior can not be disabled.
1094 return value
1096 On error this method will croak.
1098 In list context, the headers will be returned whether they are used to
1100 set "column_names" or not.
1101 In scalar context, the instance itself is returned. Note: the values
1103 as found in the header will effectively be lost if "set_column_names"
1104 is false.
1105 Options
1107 sep_set
1109 $csv->header ($fh, { sep_set => [ ";", ",", "|", "\t" ] });
1110 The list of legal separators defaults to "[ ";", "," ]" and can be
1112 changed by this option. As this is probably the most often used
1113 option, it can be passed on its own as an unnamed argument:
1114 $csv->header ($fh, [ ";", ",", "|", "\t", "::", "\x{2063}" ]);
1116 Multi-byte sequences are allowed, both multi-character and
1118 Unicode. See "sep".
1119 detect_bom
1121 $csv->header ($fh, { detect_bom => 1 });
1122 The default behavior is to detect if the header line starts with a
1124 BOM. If the header has a BOM, use that to set the encoding of $fh.
1125 This default behavior can be disabled by passing a false value to
1126 "detect_bom".
1127 Supported encodings from BOM are: UTF-8, UTF-16BE, UTF-16LE,
1129 UTF-32BE, and UTF-32LE. BOM's also support UTF-1, UTF-EBCDIC, SCSU,
1130 BOCU-1, and GB-18030 but Encode does not (yet). UTF-7 is not
1131 supported.
1132 If a supported BOM was detected as start of the stream, it is stored
1134 in the abject attribute "ENCODING".
1135 my $enc = $csv->{ENCODING};
1137 The encoding is used with "binmode" on $fh.
1139 If the handle was opened in a (correct) encoding, this method will
1141 not alter the encoding, as it checks the leading bytes of the first
1142 line. In case the stream starts with a decode BOM ("U+FEFF"),
1143 "{ENCODING}" will be "" (empty) instead of the default "undef".
1144 munge_column_names
1146 This option offers the means to modify the column names into
1147 something that is most useful to the application. The default is to
1148 map all column names to lower case.
1149 $csv->header ($fh, { munge_column_names => "lc" });
1151 The following values are available:
1153 lc - lower case
1155 uc - upper case
1156 none - do not change
1157 \%hash - supply a mapping
1158 \&cb - supply a callback
1159 Literal:
1161 $csv->header ($fh, { munge_column_names => "none" });
1163 Hash:
1165 $csv->header ($fh, { munge_column_names => { foo => "sombrero" });
1167 if a value does not exist, the original value is used unchanged
1169 Callback:
1171 $csv->header ($fh, { munge_column_names => sub { fc } });
1173 $csv->header ($fh, { munge_column_names => sub { "column_".$col++ } });
1174 $csv->header ($fh, { munge_column_names => sub { lc (s/\W+/_/gr) } });
1175 As this callback is called in a "map", you can use $_ directly.
1177 set_column_names
1179 $csv->header ($fh, { set_column_names => 1 });
1180 The default is to set the instances column names using
1182 "column_names" if the method is successful, so subsequent calls to
1183 "getline_hr" can return a hash. Disable setting the header can be
1184 forced by using a false value for this option.
1185 As described in "return value" above, content is lost in scalar
1187 context.
1188 Validation
1190 When receiving CSV files from external sources, this method can be
1192 used to protect against changes in the layout by restricting to known
1193 headers (and typos in the header fields).
1194 my %known = (
1196 "record key" => "c_rec",
1197 "rec id" => "c_rec",
1198 "id_rec" => "c_rec",
1199 "kode" => "code",
1200 "code" => "code",
1201 "vaule" => "value",
1202 "value" => "value",
1203 );
1204 my $csv = Text::CSV_PP->new ({ binary => 1, auto_diag => 1 });
1205 open my $fh, "<", $source or die "$source: $!";
1206 $csv->header ($fh, { munge_column_names => sub {
1207 s/\s+$//;
1208 s/^\s+//;
1209 $known{lc $_} or die "Unknown column '$_' in $source";
1210 }});
1211 while (my $row = $csv->getline_hr ($fh)) {
1212 say join "\t", $row->{c_rec}, $row->{code}, $row->{value};
1213 }
1214 bind_columns
1216 Takes a list of scalar references to be used for output with "print"
1217 or to store in the fields fetched by "getline". When you do not pass
1218 enough references to store the fetched fields in, "getline" will fail
1219 with error 3006. If you pass more than there are fields to return,
1220 the content of the remaining references is left untouched.
1221 $csv->bind_columns (\$code, \$name, \$price, \$description);
1223 while ($csv->getline ($fh)) {
1224 print "The price of a $name is \x{20ac} $price\n";
1225 }
1226 To reset or clear all column binding, call "bind_columns" with the
1228 single argument "undef". This will also clear column names.
1229 $csv->bind_columns (undef);
1231 If no arguments are passed at all, "bind_columns" will return the list
1233 of current bindings or "undef" if no binds are active.
1234 Note that in parsing with "bind_columns", the fields are set on the
1236 fly. That implies that if the third field of a row causes an error
1237 (or this row has just two fields where the previous row had more), the
1238 first two fields already have been assigned the values of the current
1239 row, while the rest of the fields will still hold the values of the
1240 previous row. If you want the parser to fail in these cases, use the
1241 "strict" attribute.
1242 eof
1244 $eof = $csv->eof ();
1245 If "parse" or "getline" was used with an IO stream, this method will
1247 return true (1) if the last call hit end of file, otherwise it will
1248 return false (''). This is useful to see the difference between a
1249 failure and end of file.
1250 Note that if the parsing of the last line caused an error, "eof" is
1252 still true. That means that if you are not using "auto_diag", an idiom
1253 like
1254 while (my $row = $csv->getline ($fh)) {
1256 # ...
1257 }
1258 $csv->eof or $csv->error_diag;
1259 will not report the error. You would have to change that to
1261 while (my $row = $csv->getline ($fh)) {
1263 # ...
1264 }
1265 +$csv->error_diag and $csv->error_diag;
1266 types
1268 $csv->types (\@tref);
1269 This method is used to force that (all) columns are of a given type.
1271 For example, if you have an integer column, two columns with
1272 doubles and a string column, then you might do a
1273 $csv->types ([Text::CSV_PP::IV (),
1275 Text::CSV_PP::NV (),
1276 Text::CSV_PP::NV (),
1277 Text::CSV_PP::PV ()]);
1278 Column types are used only for decoding columns while parsing, in
1280 other words by the "parse" and "getline" methods.
1281 You can unset column types by doing a
1283 $csv->types (undef);
1285 or fetch the current type settings with
1287 $types = $csv->types ();
1289 IV Set field type to integer.
1291 NV Set field type to numeric/float.
1293 PV Set field type to string.
1295 fields
1297 @columns = $csv->fields ();
1298 This method returns the input to "combine" or the resultant
1300 decomposed fields of a successful "parse", whichever was called more
1301 recently.
1302 Note that the return value is undefined after using "getline", which
1304 does not fill the data structures returned by "parse".
1305 meta_info
1307 @flags = $csv->meta_info ();
1308 This method returns the "flags" of the input to "combine" or the flags
1310 of the resultant decomposed fields of "parse", whichever was called
1311 more recently.
1312 For each field, a meta_info field will hold flags that inform
1314 something about the field returned by the "fields" method or
1315 passed to the "combine" method. The flags are bit-wise-"or"'d like:
1316 " "0x0001
1318 The field was quoted.
1319 " "0x0002
1321 The field was binary.
1322 See the "is_***" methods below.
1324 is_quoted
1326 my $quoted = $csv->is_quoted ($column_idx);
1327 Where $column_idx is the (zero-based) index of the column in the
1329 last result of "parse".
1330 This returns a true value if the data in the indicated column was
1332 enclosed in "quote_char" quotes. This might be important for fields
1333 where content ",20070108," is to be treated as a numeric value, and
1334 where ","20070108"," is explicitly marked as character string data.
1335 This method is only valid when "keep_meta_info" is set to a true value.
1337 is_binary
1339 my $binary = $csv->is_binary ($column_idx);
1340 Where $column_idx is the (zero-based) index of the column in the
1342 last result of "parse".
1343 This returns a true value if the data in the indicated column contained
1345 any byte in the range "[\x00-\x08,\x10-\x1F,\x7F-\xFF]".
1346 This method is only valid when "keep_meta_info" is set to a true value.
1348 is_missing
1350 my $missing = $csv->is_missing ($column_idx);
1351 Where $column_idx is the (zero-based) index of the column in the
1353 last result of "getline_hr".
1354 $csv->keep_meta_info (1);
1356 while (my $hr = $csv->getline_hr ($fh)) {
1357 $csv->is_missing (0) and next; # This was an empty line
1358 }
1359 When using "getline_hr", it is impossible to tell if the parsed
1361 fields are "undef" because they where not filled in the "CSV" stream
1362 or because they were not read at all, as all the fields defined by
1363 "column_names" are set in the hash-ref. If you still need to know if
1364 all fields in each row are provided, you should enable "keep_meta_info"
1365 so you can check the flags.
1366 If "keep_meta_info" is "false", "is_missing" will always return
1368 "undef", regardless of $column_idx being valid or not. If this
1369 attribute is "true" it will return either 0 (the field is present) or 1
1370 (the field is missing).
1371 A special case is the empty line. If the line is completely empty -
1373 after dealing with the flags - this is still a valid CSV line: it is a
1374 record of just one single empty field. However, if "keep_meta_info" is
1375 set, invoking "is_missing" with index 0 will now return true.
1376 status
1378 $status = $csv->status ();
1379 This method returns the status of the last invoked "combine" or "parse"
1381 call. Status is success (true: 1) or failure (false: "undef" or 0).
1382 error_input
1384 $bad_argument = $csv->error_input ();
1385 This method returns the erroneous argument (if it exists) of "combine"
1387 or "parse", whichever was called more recently. If the last
1388 invocation was successful, "error_input" will return "undef".
1389 error_diag
1391 Text::CSV_PP->error_diag ();
1392 $csv->error_diag ();
1393 $error_code = 0 + $csv->error_diag ();
1394 $error_str = "" . $csv->error_diag ();
1395 ($cde, $str, $pos, $rec, $fld) = $csv->error_diag ();
1396 If (and only if) an error occurred, this function returns the
1398 diagnostics of that error.
1399 If called in void context, this will print the internal error code and
1401 the associated error message to STDERR.
1402 If called in list context, this will return the error code and the
1404 error message in that order. If the last error was from parsing, the
1405 rest of the values returned are a best guess at the location within
1406 the line that was being parsed. Their values are 1-based. The
1407 position currently is index of the byte at which the parsing failed in
1408 the current record. It might change to be the index of the current
1409 character in a later release. The records is the index of the record
1410 parsed by the csv instance. The field number is the index of the field
1411 the parser thinks it is currently trying to parse. See
1412 examples/csv-check for how this can be used.
1413 If called in scalar context, it will return the diagnostics in a
1415 single scalar, a-la $!. It will contain the error code in numeric
1416 context, and the diagnostics message in string context.
1417 When called as a class method or a direct function call, the
1419 diagnostics are that of the last "new" call.
1420 record_number
1422 $recno = $csv->record_number ();
1423 Returns the records parsed by this csv instance. This value should be
1425 more accurate than $. when embedded newlines come in play. Records
1426 written by this instance are not counted.
1427 SetDiag
1429 $csv->SetDiag (0);
1430 Use to reset the diagnostics if you are dealing with errors.
1432
1434 This section is also taken from Text::CSV_XS.
1435 csv
1437 This function is not exported by default and should be explicitly
1438 requested:
1439 use Text::CSV_PP qw( csv );
1441 This is an high-level function that aims at simple (user) interfaces.
1443 This can be used to read/parse a "CSV" file or stream (the default
1444 behavior) or to produce a file or write to a stream (define the "out"
1445 attribute). It returns an array- or hash-reference on parsing (or
1446 "undef" on fail) or the numeric value of "error_diag" on writing.
1447 When this function fails you can get to the error using the class call
1448 to "error_diag"
1449 my $aoa = csv (in => "test.csv") or
1451 die Text::CSV_PP->error_diag;
1452 This function takes the arguments as key-value pairs. This can be
1454 passed as a list or as an anonymous hash:
1455 my $aoa = csv ( in => "test.csv", sep_char => ";");
1457 my $aoh = csv ({ in => $fh, headers => "auto" });
1458 The arguments passed consist of two parts: the arguments to "csv"
1460 itself and the optional attributes to the "CSV" object used inside
1461 the function as enumerated and explained in "new".
1462 If not overridden, the default option used for CSV is
1464 auto_diag => 1
1466 escape_null => 0
1467 The option that is always set and cannot be altered is
1469 binary => 1
1471 As this function will likely be used in one-liners, it allows "quote"
1473 to be abbreviated as "quo", and "escape_char" to be abbreviated as
1474 "esc" or "escape".
1475 Alternative invocations:
1477 my $aoa = Text::CSV_PP::csv (in => "file.csv");
1479 my $csv = Text::CSV_PP->new ();
1481 my $aoa = $csv->csv (in => "file.csv");
1482 In the latter case, the object attributes are used from the existing
1484 object and the attribute arguments in the function call are ignored:
1485 my $csv = Text::CSV_PP->new ({ sep_char => ";" });
1487 my $aoh = $csv->csv (in => "file.csv", bom => 1);
1488 will parse using ";" as "sep_char", not ",".
1490 in
1492 Used to specify the source. "in" can be a file name (e.g. "file.csv"),
1494 which will be opened for reading and closed when finished, a file
1495 handle (e.g. $fh or "FH"), a reference to a glob (e.g. "\*ARGV"),
1496 the glob itself (e.g. *STDIN), or a reference to a scalar (e.g.
1497 "\q{1,2,"csv"}").
1498 When used with "out", "in" should be a reference to a CSV structure
1500 (AoA or AoH) or a CODE-ref that returns an array-reference or a hash-
1501 reference. The code-ref will be invoked with no arguments.
1502 my $aoa = csv (in => "file.csv");
1504 open my $fh, "<", "file.csv";
1506 my $aoa = csv (in => $fh);
1507 my $csv = [ [qw( Foo Bar )], [ 1, 2 ], [ 2, 3 ]];
1509 my $err = csv (in => $csv, out => "file.csv");
1510 If called in void context without the "out" attribute, the resulting
1512 ref will be used as input to a subsequent call to csv:
1513 csv (in => "file.csv", filter => { 2 => sub { length > 2 }})
1515 will be a shortcut to
1517 csv (in => csv (in => "file.csv", filter => { 2 => sub { length > 2 }}))
1519 where, in the absence of the "out" attribute, this is a shortcut to
1521 csv (in => csv (in => "file.csv", filter => { 2 => sub { length > 2 }}),
1523 out => *STDOUT)
1524 out
1526 csv (in => $aoa, out => "file.csv");
1528 csv (in => $aoa, out => $fh);
1529 csv (in => $aoa, out => STDOUT);
1530 csv (in => $aoa, out => *STDOUT);
1531 csv (in => $aoa, out => \*STDOUT);
1532 csv (in => $aoa, out => \my $data);
1533 csv (in => $aoa, out => undef);
1534 csv (in => $aoa, out => \"skip");
1535 In output mode, the default CSV options when producing CSV are
1537 eol => "\r\n"
1539 The "fragment" attribute is ignored in output mode.
1541 "out" can be a file name (e.g. "file.csv"), which will be opened for
1543 writing and closed when finished, a file handle (e.g. $fh or "FH"), a
1544 reference to a glob (e.g. "\*STDOUT"), the glob itself (e.g. *STDOUT),
1545 or a reference to a scalar (e.g. "\my $data").
1546 csv (in => sub { $sth->fetch }, out => "dump.csv");
1548 csv (in => sub { $sth->fetchrow_hashref }, out => "dump.csv",
1549 headers => $sth->{NAME_lc});
1550 When a code-ref is used for "in", the output is generated per
1552 invocation, so no buffering is involved. This implies that there is no
1553 size restriction on the number of records. The "csv" function ends when
1554 the coderef returns a false value.
1555 If "out" is set to a reference of the literal string "skip", the output
1557 will be suppressed completely, which might be useful in combination
1558 with a filter for side effects only.
1559 my %cache;
1561 csv (in => "dump.csv",
1562 out => \"skip",
1563 on_in => sub { $cache{$_[1][1]}++ });
1564 Currently, setting "out" to any false value ("undef", "", 0) will be
1566 equivalent to "\"skip"".
1567 encoding
1569 If passed, it should be an encoding accepted by the ":encoding()"
1571 option to "open". There is no default value. This attribute does not
1572 work in perl 5.6.x. "encoding" can be abbreviated to "enc" for ease of
1573 use in command line invocations.
1574 If "encoding" is set to the literal value "auto", the method "header"
1576 will be invoked on the opened stream to check if there is a BOM and set
1577 the encoding accordingly. This is equal to passing a true value in
1578 the option "detect_bom".
1579 detect_bom
1581 If "detect_bom" is given, the method "header" will be invoked on
1583 the opened stream to check if there is a BOM and set the encoding
1584 accordingly.
1585 "detect_bom" can be abbreviated to "bom".
1587 This is the same as setting "encoding" to "auto".
1589 Note that as the method "header" is invoked, its default is to also
1591 set the headers.
1592 headers
1594 If this attribute is not given, the default behavior is to produce an
1596 array of arrays.
1597 If "headers" is supplied, it should be an anonymous list of column
1599 names, an anonymous hashref, a coderef, or a literal flag: "auto",
1600 "lc", "uc", or "skip".
1601 skip
1603 When "skip" is used, the header will not be included in the output.
1604 my $aoa = csv (in => $fh, headers => "skip");
1606 auto
1608 If "auto" is used, the first line of the "CSV" source will be read as
1609 the list of field headers and used to produce an array of hashes.
1610 my $aoh = csv (in => $fh, headers => "auto");
1612 lc
1614 If "lc" is used, the first line of the "CSV" source will be read as
1615 the list of field headers mapped to lower case and used to produce
1616 an array of hashes. This is a variation of "auto".
1617 my $aoh = csv (in => $fh, headers => "lc");
1619 uc
1621 If "uc" is used, the first line of the "CSV" source will be read as
1622 the list of field headers mapped to upper case and used to produce
1623 an array of hashes. This is a variation of "auto".
1624 my $aoh = csv (in => $fh, headers => "uc");
1626 CODE
1628 If a coderef is used, the first line of the "CSV" source will be
1629 read as the list of mangled field headers in which each field is
1630 passed as the only argument to the coderef. This list is used to
1631 produce an array of hashes.
1632 my $aoh = csv (in => $fh,
1634 headers => sub { lc ($_[0]) =~ s/kode/code/gr });
1635 this example is a variation of using "lc" where all occurrences of
1637 "kode" are replaced with "code".
1638 ARRAY
1640 If "headers" is an anonymous list, the entries in the list will be
1641 used as field names. The first line is considered data instead of
1642 headers.
1643 my $aoh = csv (in => $fh, headers => [qw( Foo Bar )]);
1645 csv (in => $aoa, out => $fh, headers => [qw( code description price )]);
1646 HASH
1648 If "headers" is an hash reference, this implies "auto", but header
1649 fields for that exist as key in the hashref will be replaced by the
1650 value for that key. Given a CSV file like
1651 post-kode,city,name,id number,fubble
1653 1234AA,Duckstad,Donald,13,"X313DF"
1654 using
1656 csv (headers => { "post-kode" => "pc", "id number" => "ID" }, ...
1658 will return an entry like
1660 { pc => "1234AA",
1662 city => "Duckstad",
1663 name => "Donald",
1664 ID => "13",
1665 fubble => "X313DF",
1666 }
1667 See also "munge_column_names" and "set_column_names".
1669 munge_column_names
1671 If "munge_column_names" is set, the method "header" is invoked on
1673 the opened stream with all matching arguments to detect and set the
1674 headers.
1675 "munge_column_names" can be abbreviated to "munge".
1677 key
1679 If passed, will default "headers" to "auto" and return a hashref
1681 instead of an array of hashes. Allowed values are simple scalars or
1682 array-references where the first element is the joiner and the rest are
1683 the fields to join to combine the key.
1684 my $ref = csv (in => "test.csv", key => "code");
1686 my $ref = csv (in => "test.csv", key => [ ":" => "code", "color" ]);
1687 with test.csv like
1689 code,product,price,color
1691 1,pc,850,gray
1692 2,keyboard,12,white
1693 3,mouse,5,black
1694 the first example will return
1696 { 1 => {
1698 code => 1,
1699 color => 'gray',
1700 price => 850,
1701 product => 'pc'
1702 },
1703 2 => {
1704 code => 2,
1705 color => 'white',
1706 price => 12,
1707 product => 'keyboard'
1708 },
1709 3 => {
1710 code => 3,
1711 color => 'black',
1712 price => 5,
1713 product => 'mouse'
1714 }
1715 }
1716 the second example will return
1718 { "1:gray" => {
1720 code => 1,
1721 color => 'gray',
1722 price => 850,
1723 product => 'pc'
1724 },
1725 "2:white" => {
1726 code => 2,
1727 color => 'white',
1728 price => 12,
1729 product => 'keyboard'
1730 },
1731 "3:black" => {
1732 code => 3,
1733 color => 'black',
1734 price => 5,
1735 product => 'mouse'
1736 }
1737 }
1738 The "key" attribute can be combined with "headers" for "CSV" date that
1740 has no header line, like
1741 my $ref = csv (
1743 in => "foo.csv",
1744 headers => [qw( c_foo foo bar description stock )],
1745 key => "c_foo",
1746 );
1747 value
1749 Used to create key-value hashes.
1751 Only allowed when "key" is valid. A "value" can be either a single
1753 column label or an anonymous list of column labels. In the first case,
1754 the value will be a simple scalar value, in the latter case, it will be
1755 a hashref.
1756 my $ref = csv (in => "test.csv", key => "code",
1758 value => "price");
1759 my $ref = csv (in => "test.csv", key => "code",
1760 value => [ "product", "price" ]);
1761 my $ref = csv (in => "test.csv", key => [ ":" => "code", "color" ],
1762 value => "price");
1763 my $ref = csv (in => "test.csv", key => [ ":" => "code", "color" ],
1764 value => [ "product", "price" ]);
1765 with test.csv like
1767 code,product,price,color
1769 1,pc,850,gray
1770 2,keyboard,12,white
1771 3,mouse,5,black
1772 the first example will return
1774 { 1 => 850,
1776 2 => 12,
1777 3 => 5,
1778 }
1779 the second example will return
1781 { 1 => {
1783 price => 850,
1784 product => 'pc'
1785 },
1786 2 => {
1787 price => 12,
1788 product => 'keyboard'
1789 },
1790 3 => {
1791 price => 5,
1792 product => 'mouse'
1793 }
1794 }
1795 the third example will return
1797 { "1:gray" => 850,
1799 "2:white" => 12,
1800 "3:black" => 5,
1801 }
1802 the fourth example will return
1804 { "1:gray" => {
1806 price => 850,
1807 product => 'pc'
1808 },
1809 "2:white" => {
1810 price => 12,
1811 product => 'keyboard'
1812 },
1813 "3:black" => {
1814 price => 5,
1815 product => 'mouse'
1816 }
1817 }
1818 keep_headers
1820 When using hashes, keep the column names into the arrayref passed, so
1822 all headers are available after the call in the original order.
1823 my $aoh = csv (in => "file.csv", keep_headers => \my @hdr);
1825 This attribute can be abbreviated to "kh" or passed as
1827 "keep_column_names".
1828 This attribute implies a default of "auto" for the "headers" attribute.
1830 fragment
1832 Only output the fragment as defined in the "fragment" method. This
1834 option is ignored when generating "CSV". See "out".
1835 Combining all of them could give something like
1837 use Text::CSV_PP qw( csv );
1839 my $aoh = csv (
1840 in => "test.txt",
1841 encoding => "utf-8",
1842 headers => "auto",
1843 sep_char => "|",
1844 fragment => "row=3;6-9;15-*",
1845 );
1846 say $aoh->[15]{Foo};
1847 sep_set
1849 If "sep_set" is set, the method "header" is invoked on the opened
1851 stream to detect and set "sep_char" with the given set.
1852 "sep_set" can be abbreviated to "seps".
1854 Note that as the "header" method is invoked, its default is to also
1856 set the headers.
1857 set_column_names
1859 If "set_column_names" is passed, the method "header" is invoked on
1861 the opened stream with all arguments meant for "header".
1862 If "set_column_names" is passed as a false value, the content of the
1864 first row is only preserved if the output is AoA:
1865 With an input-file like
1867 bAr,foo
1869 1,2
1870 3,4,5
1871 This call
1873 my $aoa = csv (in => $file, set_column_names => 0);
1875 will result in
1877 [[ "bar", "foo" ],
1879 [ "1", "2" ],
1880 [ "3", "4", "5" ]]
1881 and
1883 my $aoa = csv (in => $file, set_column_names => 0, munge => "none");
1885 will result in
1887 [[ "bAr", "foo" ],
1889 [ "1", "2" ],
1890 [ "3", "4", "5" ]]
1891 Callbacks
1893 Callbacks enable actions triggered from the inside of Text::CSV_PP.
1894 While most of what this enables can easily be done in an unrolled
1896 loop as described in the "SYNOPSIS" callbacks can be used to meet
1897 special demands or enhance the "csv" function.
1898 error
1900 $csv->callbacks (error => sub { $csv->SetDiag (0) });
1901 the "error" callback is invoked when an error occurs, but only
1903 when "auto_diag" is set to a true value. A callback is invoked with
1904 the values returned by "error_diag":
1905 my ($c, $s);
1907 sub ignore3006
1909 {
1910 my ($err, $msg, $pos, $recno, $fldno) = @_;
1911 if ($err == 3006) {
1912 # ignore this error
1913 ($c, $s) = (undef, undef);
1914 Text::CSV_PP->SetDiag (0);
1915 }
1916 # Any other error
1917 return;
1918 } # ignore3006
1919 $csv->callbacks (error => \&ignore3006);
1921 $csv->bind_columns (\$c, \$s);
1922 while ($csv->getline ($fh)) {
1923 # Error 3006 will not stop the loop
1924 }
1925 after_parse
1927 $csv->callbacks (after_parse => sub { push @{$_[1]}, "NEW" });
1928 while (my $row = $csv->getline ($fh)) {
1929 $row->[-1] eq "NEW";
1930 }
1931 This callback is invoked after parsing with "getline" only if no
1933 error occurred. The callback is invoked with two arguments: the
1934 current "CSV" parser object and an array reference to the fields
1935 parsed.
1936 The return code of the callback is ignored unless it is a reference
1938 to the string "skip", in which case the record will be skipped in
1939 "getline_all".
1940 sub add_from_db
1942 {
1943 my ($csv, $row) = @_;
1944 $sth->execute ($row->[4]);
1945 push @$row, $sth->fetchrow_array;
1946 } # add_from_db
1947 my $aoa = csv (in => "file.csv", callbacks => {
1949 after_parse => \&add_from_db });
1950 This hook can be used for validation:
1952 FAIL
1954 Die if any of the records does not validate a rule:
1955 after_parse => sub {
1957 $_[1][4] =~ m/^[0-9]{4}\s?[A-Z]{2}$/ or
1958 die "5th field does not have a valid Dutch zipcode";
1959 }
1960 DEFAULT
1962 Replace invalid fields with a default value:
1963 after_parse => sub { $_[1][2] =~ m/^\d+$/ or $_[1][2] = 0 }
1965 SKIP
1967 Skip records that have invalid fields (only applies to
1968 "getline_all"):
1969 after_parse => sub { $_[1][0] =~ m/^\d+$/ or return \"skip"; }
1971 before_print
1973 my $idx = 1;
1974 $csv->callbacks (before_print => sub { $_[1][0] = $idx++ });
1975 $csv->print (*STDOUT, [ 0, $_ ]) for @members;
1976 This callback is invoked before printing with "print" only if no
1978 error occurred. The callback is invoked with two arguments: the
1979 current "CSV" parser object and an array reference to the fields
1980 passed.
1981 The return code of the callback is ignored.
1983 sub max_4_fields
1985 {
1986 my ($csv, $row) = @_;
1987 @$row > 4 and splice @$row, 4;
1988 } # max_4_fields
1989 csv (in => csv (in => "file.csv"), out => *STDOUT,
1991 callbacks => { before print => \&max_4_fields });
1992 This callback is not active for "combine".
1994 Callbacks for csv ()
1996 The "csv" allows for some callbacks that do not integrate in XS
1998 internals but only feature the "csv" function.
1999 csv (in => "file.csv",
2001 callbacks => {
2002 filter => { 6 => sub { $_ > 15 } }, # first
2003 after_parse => sub { say "AFTER PARSE"; }, # first
2004 after_in => sub { say "AFTER IN"; }, # second
2005 on_in => sub { say "ON IN"; }, # third
2006 },
2007 );
2008 csv (in => $aoh,
2010 out => "file.csv",
2011 callbacks => {
2012 on_in => sub { say "ON IN"; }, # first
2013 before_out => sub { say "BEFORE OUT"; }, # second
2014 before_print => sub { say "BEFORE PRINT"; }, # third
2015 },
2016 );
2017 filter
2019 This callback can be used to filter records. It is called just after
2020 a new record has been scanned. The callback accepts a:
2021 hashref
2023 The keys are the index to the row (the field name or field number,
2024 1-based) and the values are subs to return a true or false value.
2025 csv (in => "file.csv", filter => {
2027 3 => sub { m/a/ }, # third field should contain an "a"
2028 5 => sub { length > 4 }, # length of the 5th field minimal 5
2029 });
2030 csv (in => "file.csv", filter => { foo => sub { $_ > 4 }});
2032 If the keys to the filter hash contain any character that is not a
2034 digit it will also implicitly set "headers" to "auto" unless
2035 "headers" was already passed as argument. When headers are
2036 active, returning an array of hashes, the filter is not applicable
2037 to the header itself.
2038 All sub results should match, as in AND.
2040 The context of the callback sets $_ localized to the field
2042 indicated by the filter. The two arguments are as with all other
2043 callbacks, so the other fields in the current row can be seen:
2044 filter => { 3 => sub { $_ > 100 ? $_[1][1] =~ m/A/ : $_[1][6] =~ m/B/ }}
2046 If the context is set to return a list of hashes ("headers" is
2048 defined), the current record will also be available in the
2049 localized %_:
2050 filter => { 3 => sub { $_ > 100 && $_{foo} =~ m/A/ && $_{bar} < 1000 }}
2052 If the filter is used to alter the content by changing $_, make
2054 sure that the sub returns true in order not to have that record
2055 skipped:
2056 filter => { 2 => sub { $_ = uc }}
2058 will upper-case the second field, and then skip it if the resulting
2060 content evaluates to false. To always accept, end with truth:
2061 filter => { 2 => sub { $_ = uc; 1 }}
2063 coderef
2065 csv (in => "file.csv", filter => sub { $n++; 0; });
2066 If the argument to "filter" is a coderef, it is an alias or
2068 shortcut to a filter on column 0:
2069 csv (filter => sub { $n++; 0 });
2071 is equal to
2073 csv (filter => { 0 => sub { $n++; 0 });
2075 filter-name
2077 csv (in => "file.csv", filter => "not_blank");
2078 csv (in => "file.csv", filter => "not_empty");
2079 csv (in => "file.csv", filter => "filled");
2080 These are predefined filters
2082 Given a file like (line numbers prefixed for doc purpose only):
2084 1:1,2,3
2086 2:
2087 3:,
2088 4:""
2089 5:,,
2090 6:, ,
2091 7:"",
2092 8:" "
2093 9:4,5,6
2094 not_blank
2096 Filter out the blank lines
2097 This filter is a shortcut for
2099 filter => { 0 => sub { @{$_[1]} > 1 or
2101 defined $_[1][0] && $_[1][0] ne "" } }
2102 Due to the implementation, it is currently impossible to also
2104 filter lines that consists only of a quoted empty field. These
2105 lines are also considered blank lines.
2106 With the given example, lines 2 and 4 will be skipped.
2108 not_empty
2110 Filter out lines where all the fields are empty.
2111 This filter is a shortcut for
2113 filter => { 0 => sub { grep { defined && $_ ne "" } @{$_[1]} } }
2115 A space is not regarded being empty, so given the example data,
2117 lines 2, 3, 4, 5, and 7 are skipped.
2118 filled
2120 Filter out lines that have no visible data
2121 This filter is a shortcut for
2123 filter => { 0 => sub { grep { defined && m/\S/ } @{$_[1]} } }
2125 This filter rejects all lines that not have at least one field
2127 that does not evaluate to the empty string.
2128 With the given example data, this filter would skip lines 2
2130 through 8.
2131 after_in
2133 This callback is invoked for each record after all records have been
2134 parsed but before returning the reference to the caller. The hook is
2135 invoked with two arguments: the current "CSV" parser object and a
2136 reference to the record. The reference can be a reference to a
2137 HASH or a reference to an ARRAY as determined by the arguments.
2138 This callback can also be passed as an attribute without the
2140 "callbacks" wrapper.
2141 before_out
2143 This callback is invoked for each record before the record is
2144 printed. The hook is invoked with two arguments: the current "CSV"
2145 parser object and a reference to the record. The reference can be a
2146 reference to a HASH or a reference to an ARRAY as determined by the
2147 arguments.
2148 This callback can also be passed as an attribute without the
2150 "callbacks" wrapper.
2151 This callback makes the row available in %_ if the row is a hashref.
2153 In this case %_ is writable and will change the original row.
2154 on_in
2156 This callback acts exactly as the "after_in" or the "before_out"
2157 hooks.
2158 This callback can also be passed as an attribute without the
2160 "callbacks" wrapper.
2161 This callback makes the row available in %_ if the row is a hashref.
2163 In this case %_ is writable and will change the original row. So e.g.
2164 with
2165 my $aoh = csv (
2167 in => \"foo\n1\n2\n",
2168 headers => "auto",
2169 on_in => sub { $_{bar} = 2; },
2170 );
2171 $aoh will be:
2173 [ { foo => 1,
2175 bar => 2,
2176 }
2177 { foo => 2,
2178 bar => 2,
2179 }
2180 ]
2181 csv
2183 The function "csv" can also be called as a method or with an
2184 existing Text::CSV_PP object. This could help if the function is to
2185 be invoked a lot of times and the overhead of creating the object
2186 internally over and over again would be prevented by passing an
2187 existing instance.
2188 my $csv = Text::CSV_PP->new ({ binary => 1, auto_diag => 1 });
2190 my $aoa = $csv->csv (in => $fh);
2192 my $aoa = csv (in => $fh, csv => $csv);
2193 both act the same. Running this 20000 times on a 20 lines CSV file,
2195 showed a 53% speedup.
2196
2198 This section is also taken from Text::CSV_XS.
2199 Still under construction ...
2201 If an error occurs, "$csv->error_diag" can be used to get information
2203 on the cause of the failure. Note that for speed reasons the internal
2204 value is never cleared on success, so using the value returned by
2205 "error_diag" in normal cases - when no error occurred - may cause
2206 unexpected results.
2207 If the constructor failed, the cause can be found using "error_diag" as
2209 a class method, like "Text::CSV_PP->error_diag".
2210 The "$csv->error_diag" method is automatically invoked upon error when
2212 the contractor was called with "auto_diag" set to 1 or 2, or when
2213 autodie is in effect. When set to 1, this will cause a "warn" with the
2214 error message, when set to 2, it will "die". "2012 - EOF" is excluded
2215 from "auto_diag" reports.
2216 Errors can be (individually) caught using the "error" callback.
2218 The errors as described below are available. I have tried to make the
2220 error itself explanatory enough, but more descriptions will be added.
2221 For most of these errors, the first three capitals describe the error
2222 category:
2223 • INI
2225 Initialization error or option conflict.
2227 • ECR
2229 Carriage-Return related parse error.
2231 • EOF
2233 End-Of-File related parse error.
2235 • EIQ
2237 Parse error inside quotation.
2239 • EIF
2241 Parse error inside field.
2243 • ECB
2245 Combine error.
2247 • EHR
2249 HashRef parse related error.
2251 And below should be the complete list of error codes that can be
2253 returned:
2254 • 1001 "INI - sep_char is equal to quote_char or escape_char"
2256 The separation character cannot be equal to the quotation
2258 character or to the escape character, as this would invalidate all
2259 parsing rules.
2260 • 1002 "INI - allow_whitespace with escape_char or quote_char SP or
2262 TAB"
2263 Using the "allow_whitespace" attribute when either "quote_char" or
2265 "escape_char" is equal to "SPACE" or "TAB" is too ambiguous to
2266 allow.
2267 • 1003 "INI - \r or \n in main attr not allowed"
2269 Using default "eol" characters in either "sep_char", "quote_char",
2271 or "escape_char" is not allowed.
2272 • 1004 "INI - callbacks should be undef or a hashref"
2274 The "callbacks" attribute only allows one to be "undef" or a hash
2276 reference.
2277 • 1005 "INI - EOL too long"
2279 The value passed for EOL is exceeding its maximum length (16).
2281 • 1006 "INI - SEP too long"
2283 The value passed for SEP is exceeding its maximum length (16).
2285 • 1007 "INI - QUOTE too long"
2287 The value passed for QUOTE is exceeding its maximum length (16).
2289 • 1008 "INI - SEP undefined"
2291 The value passed for SEP should be defined and not empty.
2293 • 1010 "INI - the header is empty"
2295 The header line parsed in the "header" is empty.
2297 • 1011 "INI - the header contains more than one valid separator"
2299 The header line parsed in the "header" contains more than one
2301 (unique) separator character out of the allowed set of separators.
2302 • 1012 "INI - the header contains an empty field"
2304 The header line parsed in the "header" is contains an empty field.
2306 • 1013 "INI - the header contains nun-unique fields"
2308 The header line parsed in the "header" contains at least two
2310 identical fields.
2311 • 1014 "INI - header called on undefined stream"
2313 The header line cannot be parsed from an undefined sources.
2315 • 1500 "PRM - Invalid/unsupported argument(s)"
2317 Function or method called with invalid argument(s) or parameter(s).
2319 • 1501 "PRM - The key attribute is passed as an unsupported type"
2321 The "key" attribute is of an unsupported type.
2323 • 1502 "PRM - The value attribute is passed without the key attribute"
2325 The "value" attribute is only allowed when a valid key is given.
2327 • 1503 "PRM - The value attribute is passed as an unsupported type"
2329 The "value" attribute is of an unsupported type.
2331 • 2010 "ECR - QUO char inside quotes followed by CR not part of EOL"
2333 When "eol" has been set to anything but the default, like
2335 "\r\t\n", and the "\r" is following the second (closing)
2336 "quote_char", where the characters following the "\r" do not make up
2337 the "eol" sequence, this is an error.
2338 • 2011 "ECR - Characters after end of quoted field"
2340 Sequences like "1,foo,"bar"baz,22,1" are not allowed. "bar" is a
2342 quoted field and after the closing double-quote, there should be
2343 either a new-line sequence or a separation character.
2344 • 2012 "EOF - End of data in parsing input stream"
2346 Self-explaining. End-of-file while inside parsing a stream. Can
2348 happen only when reading from streams with "getline", as using
2349 "parse" is done on strings that are not required to have a trailing
2350 "eol".
2351 • 2013 "INI - Specification error for fragments RFC7111"
2353 Invalid specification for URI "fragment" specification.
2355 • 2014 "ENF - Inconsistent number of fields"
2357 Inconsistent number of fields under strict parsing.
2359 • 2021 "EIQ - NL char inside quotes, binary off"
2361 Sequences like "1,"foo\nbar",22,1" are allowed only when the binary
2363 option has been selected with the constructor.
2364 • 2022 "EIQ - CR char inside quotes, binary off"
2366 Sequences like "1,"foo\rbar",22,1" are allowed only when the binary
2368 option has been selected with the constructor.
2369 • 2023 "EIQ - QUO character not allowed"
2371 Sequences like ""foo "bar" baz",qu" and "2023,",2008-04-05,"Foo,
2373 Bar",\n" will cause this error.
2374 • 2024 "EIQ - EOF cannot be escaped, not even inside quotes"
2376 The escape character is not allowed as last character in an input
2378 stream.
2379 • 2025 "EIQ - Loose unescaped escape"
2381 An escape character should escape only characters that need escaping.
2383 Allowing the escape for other characters is possible with the
2385 attribute "allow_loose_escapes".
2386 • 2026 "EIQ - Binary character inside quoted field, binary off"
2388 Binary characters are not allowed by default. Exceptions are
2390 fields that contain valid UTF-8, that will automatically be upgraded
2391 if the content is valid UTF-8. Set "binary" to 1 to accept binary
2392 data.
2393 • 2027 "EIQ - Quoted field not terminated"
2395 When parsing a field that started with a quotation character, the
2397 field is expected to be closed with a quotation character. When the
2398 parsed line is exhausted before the quote is found, that field is not
2399 terminated.
2400 • 2030 "EIF - NL char inside unquoted verbatim, binary off"
2402 • 2031 "EIF - CR char is first char of field, not part of EOL"
2404 • 2032 "EIF - CR char inside unquoted, not part of EOL"
2406 • 2034 "EIF - Loose unescaped quote"
2408 • 2035 "EIF - Escaped EOF in unquoted field"
2410 • 2036 "EIF - ESC error"
2412 • 2037 "EIF - Binary character in unquoted field, binary off"
2414 • 2110 "ECB - Binary character in Combine, binary off"
2416 • 2200 "EIO - print to IO failed. See errno"
2418 • 3001 "EHR - Unsupported syntax for column_names ()"
2420 • 3002 "EHR - getline_hr () called before column_names ()"
2422 • 3003 "EHR - bind_columns () and column_names () fields count
2424 mismatch"
2425 • 3004 "EHR - bind_columns () only accepts refs to scalars"
2427 • 3006 "EHR - bind_columns () did not pass enough refs for parsed
2429 fields"
2430 • 3007 "EHR - bind_columns needs refs to writable scalars"
2432 • 3008 "EHR - unexpected error in bound fields"
2434 • 3009 "EHR - print_hr () called before column_names ()"
2436 • 3010 "EHR - print_hr () called with invalid arguments"
2438
2440 Text::CSV_XS, Text::CSV
2441 Older versions took many regexp from
2443 <http://www.din.or.jp/~ohzaki/perl.htm>
2444
2446 Kenichi Ishigaki, <ishigaki[at]cpan.org> Makamaka Hannyaharamitu,
2447 <makamaka[at]cpan.org>
2448 Text::CSV_XS was written by <joe[at]ispsoft.de> and maintained by
2450 <h.m.brand[at]xs4all.nl>.
2451 Text::CSV was written by <alan[at]mfgrtl.com>.
2453
2455 Copyright 2017- by Kenichi Ishigaki, <ishigaki[at]cpan.org> Copyright
2456 2005-2015 by Makamaka Hannyaharamitu, <makamaka[at]cpan.org>
2457 Most of the code and doc is directly taken from the pure perl part of
2459 Text::CSV_XS.
2460 Copyright (C) 2007-2016 H.Merijn Brand. All rights reserved.
2462 Copyright (C) 1998-2001 Jochen Wiedmann. All rights reserved.
2463 Copyright (C) 1997 Alan Citterman. All rights reserved.
2464 This library is free software; you can redistribute it and/or modify it
2466 under the same terms as Perl itself.
2467perl v5.32.1 2021-01-27 Text::CSV_PP(3)