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 This method does not support "undef". Use "quote_char" to disable
248 quotation.
249 escape_char
251 my $csv = Text::CSV_PP->new ({ escape_char => "\\" });
253 $csv->escape_char (":");
254 my $c = $csv->escape_char;
255 The character to escape certain characters inside quoted fields.
257 This is limited to a single-byte character, usually in the range
258 from 0x20 (space) to 0x7E (tilde).
259 The "escape_char" defaults to being the double-quote mark ("""). In
261 other words the same as the default "quote_char". This means that
262 doubling the quote mark in a field escapes it:
263 "foo","bar","Escape ""quote mark"" with two ""quote marks""","baz"
265 If you change the "quote_char" without changing the
267 "escape_char", the "escape_char" will still be the double-quote
268 ("""). If instead you want to escape the "quote_char" by doubling it
269 you will need to also change the "escape_char" to be the same as what
270 you have changed the "quote_char" to.
271 Setting "escape_char" to <undef> or "" will disable escaping completely
273 and is greatly discouraged. This will also disable "escape_null".
274 The escape character can not be equal to the separation character.
276 binary
278 my $csv = Text::CSV_PP->new ({ binary => 1 });
280 $csv->binary (0);
281 my $f = $csv->binary;
282 If this attribute is 1, you may use binary characters in quoted
284 fields, including line feeds, carriage returns and "NULL" bytes. (The
285 latter could be escaped as ""0".) By default this feature is off.
286 If a string is marked UTF8, "binary" will be turned on automatically
288 when binary characters other than "CR" and "NL" are encountered. Note
289 that a simple string like "\x{00a0}" might still be binary, but not
290 marked UTF8, so setting "{ binary => 1 }" is still a wise option.
291 strict
293 my $csv = Text::CSV_PP->new ({ strict => 1 });
295 $csv->strict (0);
296 my $f = $csv->strict;
297 If this attribute is set to 1, any row that parses to a different
299 number of fields than the previous row will cause the parser to throw
300 error 2014.
301 skip_empty_rows
303 my $csv = Text::CSV_PP->new ({ skip_empty_rows => 1 });
305 $csv->skip_empty_rows (0);
306 my $f = $csv->skip_empty_rows;
307 If this attribute is set to 1, any row that has an "eol" immediately
309 following the start of line will be skipped. Default behavior is to
310 return one single empty field.
311 This attribute is only used in parsing.
313 formula_handling
315 formula
317 my $csv = Text::CSV_PP->new ({ formula => "none" });
319 $csv->formula ("none");
320 my $f = $csv->formula;
321 This defines the behavior of fields containing formulas. As formulas
323 are considered dangerous in spreadsheets, this attribute can define an
324 optional action to be taken if a field starts with an equal sign ("=").
325 For purpose of code-readability, this can also be written as
327 my $csv = Text::CSV_PP->new ({ formula_handling => "none" });
329 $csv->formula_handling ("none");
330 my $f = $csv->formula_handling;
331 Possible values for this attribute are
333 none
335 Take no specific action. This is the default.
336 $csv->formula ("none");
338 die
340 Cause the process to "die" whenever a leading "=" is encountered.
341 $csv->formula ("die");
343 croak
345 Cause the process to "croak" whenever a leading "=" is encountered.
346 (See Carp)
347 $csv->formula ("croak");
349 diag
351 Report position and content of the field whenever a leading "=" is
352 found. The value of the field is unchanged.
353 $csv->formula ("diag");
355 empty
357 Replace the content of fields that start with a "=" with the empty
358 string.
359 $csv->formula ("empty");
361 $csv->formula ("");
362 undef
364 Replace the content of fields that start with a "=" with "undef".
365 $csv->formula ("undef");
367 $csv->formula (undef);
368 a callback
370 Modify the content of fields that start with a "=" with the return-
371 value of the callback. The original content of the field is
372 available inside the callback as $_;
373 # Replace all formula's with 42
375 $csv->formula (sub { 42; });
376 # same as $csv->formula ("empty") but slower
378 $csv->formula (sub { "" });
379 # Allow =4+12
381 $csv->formula (sub { s/^=(\d+\+\d+)$/$1/eer });
382 # Allow more complex calculations
384 $csv->formula (sub { eval { s{^=([-+*/0-9()]+)$}{$1}ee }; $_ });
385 All other values will give a warning and then fallback to "diag".
387 decode_utf8
389 my $csv = Text::CSV_PP->new ({ decode_utf8 => 1 });
391 $csv->decode_utf8 (0);
392 my $f = $csv->decode_utf8;
393 This attributes defaults to TRUE.
395 While parsing, fields that are valid UTF-8, are automatically set to
397 be UTF-8, so that
398 $csv->parse ("\xC4\xA8\n");
400 results in
402 PV("\304\250"\0) [UTF8 "\x{128}"]
404 Sometimes it might not be a desired action. To prevent those upgrades,
406 set this attribute to false, and the result will be
407 PV("\304\250"\0)
409 auto_diag
411 my $csv = Text::CSV_PP->new ({ auto_diag => 1 });
413 $csv->auto_diag (2);
414 my $l = $csv->auto_diag;
415 Set this attribute to a number between 1 and 9 causes "error_diag" to
417 be automatically called in void context upon errors.
418 In case of error "2012 - EOF", this call will be void.
420 If "auto_diag" is set to a numeric value greater than 1, it will "die"
422 on errors instead of "warn". If set to anything unrecognized, it will
423 be silently ignored.
424 Future extensions to this feature will include more reliable auto-
426 detection of "autodie" being active in the scope of which the error
427 occurred which will increment the value of "auto_diag" with 1 the
428 moment the error is detected.
429 diag_verbose
431 my $csv = Text::CSV_PP->new ({ diag_verbose => 1 });
433 $csv->diag_verbose (2);
434 my $l = $csv->diag_verbose;
435 Set the verbosity of the output triggered by "auto_diag". Currently
437 only adds the current input-record-number (if known) to the
438 diagnostic output with an indication of the position of the error.
439 blank_is_undef
441 my $csv = Text::CSV_PP->new ({ blank_is_undef => 1 });
443 $csv->blank_is_undef (0);
444 my $f = $csv->blank_is_undef;
445 Under normal circumstances, "CSV" data makes no distinction between
447 quoted- and unquoted empty fields. These both end up in an empty
448 string field once read, thus
449 1,"",," ",2
451 is read as
453 ("1", "", "", " ", "2")
455 When writing "CSV" files with either "always_quote" or "quote_empty"
457 set, the unquoted empty field is the result of an undefined value.
458 To enable this distinction when reading "CSV" data, the
459 "blank_is_undef" attribute will cause unquoted empty fields to be set
460 to "undef", causing the above to be parsed as
461 ("1", "", undef, " ", "2")
463 Note that this is specifically important when loading "CSV" fields
465 into a database that allows "NULL" values, as the perl equivalent for
466 "NULL" is "undef" in DBI land.
467 empty_is_undef
469 my $csv = Text::CSV_PP->new ({ empty_is_undef => 1 });
471 $csv->empty_is_undef (0);
472 my $f = $csv->empty_is_undef;
473 Going one step further than "blank_is_undef", this attribute
475 converts all empty fields to "undef", so
476 1,"",," ",2
478 is read as
480 (1, undef, undef, " ", 2)
482 Note that this affects only fields that are originally empty, not
484 fields that are empty after stripping allowed whitespace. YMMV.
485 allow_whitespace
487 my $csv = Text::CSV_PP->new ({ allow_whitespace => 1 });
489 $csv->allow_whitespace (0);
490 my $f = $csv->allow_whitespace;
491 When this option is set to true, the whitespace ("TAB"'s and
493 "SPACE"'s) surrounding the separation character is removed when
494 parsing. If either "TAB" or "SPACE" is one of the three characters
495 "sep_char", "quote_char", or "escape_char" it will not be considered
496 whitespace.
497 Now lines like:
499 1 , "foo" , bar , 3 , zapp
501 are parsed as valid "CSV", even though it violates the "CSV" specs.
503 Note that all whitespace is stripped from both start and end of
505 each field. That would make it more than a feature to enable parsing
506 bad "CSV" lines, as
507 1, 2.0, 3, ape , monkey
509 will now be parsed as
511 ("1", "2.0", "3", "ape", "monkey")
513 even if the original line was perfectly acceptable "CSV".
515 allow_loose_quotes
517 my $csv = Text::CSV_PP->new ({ allow_loose_quotes => 1 });
519 $csv->allow_loose_quotes (0);
520 my $f = $csv->allow_loose_quotes;
521 By default, parsing unquoted fields containing "quote_char" characters
523 like
524 1,foo "bar" baz,42
526 would result in parse error 2034. Though it is still bad practice to
528 allow this format, we cannot help the fact that some vendors
529 make their applications spit out lines styled this way.
530 If there is really bad "CSV" data, like
532 1,"foo "bar" baz",42
534 or
536 1,""foo bar baz"",42
538 there is a way to get this data-line parsed and leave the quotes inside
540 the quoted field as-is. This can be achieved by setting
541 "allow_loose_quotes" AND making sure that the "escape_char" is not
542 equal to "quote_char".
543 allow_loose_escapes
545 my $csv = Text::CSV_PP->new ({ allow_loose_escapes => 1 });
547 $csv->allow_loose_escapes (0);
548 my $f = $csv->allow_loose_escapes;
549 Parsing fields that have "escape_char" characters that escape
551 characters that do not need to be escaped, like:
552 my $csv = Text::CSV_PP->new ({ escape_char => "\\" });
554 $csv->parse (qq{1,"my bar\'s",baz,42});
555 would result in parse error 2025. Though it is bad practice to allow
557 this format, this attribute enables you to treat all escape character
558 sequences equal.
559 allow_unquoted_escape
561 my $csv = Text::CSV_PP->new ({ allow_unquoted_escape => 1 });
563 $csv->allow_unquoted_escape (0);
564 my $f = $csv->allow_unquoted_escape;
565 A backward compatibility issue where "escape_char" differs from
567 "quote_char" prevents "escape_char" to be in the first position of a
568 field. If "quote_char" is equal to the default """ and "escape_char"
569 is set to "\", this would be illegal:
570 1,\0,2
572 Setting this attribute to 1 might help to overcome issues with
574 backward compatibility and allow this style.
575 always_quote
577 my $csv = Text::CSV_PP->new ({ always_quote => 1 });
579 $csv->always_quote (0);
580 my $f = $csv->always_quote;
581 By default the generated fields are quoted only if they need to be.
583 For example, if they contain the separator character. If you set this
584 attribute to 1 then all defined fields will be quoted. ("undef" fields
585 are not quoted, see "blank_is_undef"). This makes it quite often easier
586 to handle exported data in external applications.
587 quote_space
589 my $csv = Text::CSV_PP->new ({ quote_space => 1 });
591 $csv->quote_space (0);
592 my $f = $csv->quote_space;
593 By default, a space in a field would trigger quotation. As no rule
595 exists this to be forced in "CSV", nor any for the opposite, the
596 default is true for safety. You can exclude the space from this
597 trigger by setting this attribute to 0.
598 quote_empty
600 my $csv = Text::CSV_PP->new ({ quote_empty => 1 });
602 $csv->quote_empty (0);
603 my $f = $csv->quote_empty;
604 By default the generated fields are quoted only if they need to be.
606 An empty (defined) field does not need quotation. If you set this
607 attribute to 1 then empty defined fields will be quoted. ("undef"
608 fields are not quoted, see "blank_is_undef"). See also "always_quote".
609 quote_binary
611 my $csv = Text::CSV_PP->new ({ quote_binary => 1 });
613 $csv->quote_binary (0);
614 my $f = $csv->quote_binary;
615 By default, all "unsafe" bytes inside a string cause the combined
617 field to be quoted. By setting this attribute to 0, you can disable
618 that trigger for bytes >= 0x7F.
619 escape_null
621 my $csv = Text::CSV_PP->new ({ escape_null => 1 });
623 $csv->escape_null (0);
624 my $f = $csv->escape_null;
625 By default, a "NULL" byte in a field would be escaped. This option
627 enables you to treat the "NULL" byte as a simple binary character in
628 binary mode (the "{ binary => 1 }" is set). The default is true. You
629 can prevent "NULL" escapes by setting this attribute to 0.
630 When the "escape_char" attribute is set to undefined, this attribute
632 will be set to false.
633 The default setting will encode "=\x00=" as
635 "="0="
637 With "escape_null" set, this will result in
639 "=\x00="
641 The default when using the "csv" function is "false".
643 For backward compatibility reasons, the deprecated old name
645 "quote_null" is still recognized.
646 keep_meta_info
648 my $csv = Text::CSV_PP->new ({ keep_meta_info => 1 });
650 $csv->keep_meta_info (0);
651 my $f = $csv->keep_meta_info;
652 By default, the parsing of input records is as simple and fast as
654 possible. However, some parsing information - like quotation of the
655 original field - is lost in that process. Setting this flag to true
656 enables retrieving that information after parsing with the methods
657 "meta_info", "is_quoted", and "is_binary" described below. Default is
658 false for performance.
659 If you set this attribute to a value greater than 9, then you can
661 control output quotation style like it was used in the input of the the
662 last parsed record (unless quotation was added because of other
663 reasons).
664 my $csv = Text::CSV_PP->new ({
666 binary => 1,
667 keep_meta_info => 1,
668 quote_space => 0,
669 });
670 my $row = $csv->parse (q{1,,"", ," ",f,"g","h""h",help,"help"});
672 $csv->print (*STDOUT, \@row);
674 # 1,,, , ,f,g,"h""h",help,help
675 $csv->keep_meta_info (11);
676 $csv->print (*STDOUT, \@row);
677 # 1,,"", ," ",f,"g","h""h",help,"help"
678 undef_str
680 my $csv = Text::CSV_PP->new ({ undef_str => "\\N" });
682 $csv->undef_str (undef);
683 my $s = $csv->undef_str;
684 This attribute optionally defines the output of undefined fields. The
686 value passed is not changed at all, so if it needs quotation, the
687 quotation needs to be included in the value of the attribute. Use with
688 caution, as passing a value like ",",,,,""" will for sure mess up
689 your output. The default for this attribute is "undef", meaning no
690 special treatment.
691 This attribute is useful when exporting CSV data to be imported in
693 custom loaders, like for MySQL, that recognize special sequences for
694 "NULL" data.
695 This attribute has no meaning when parsing CSV data.
697 comment_str
699 my $csv = Text::CSV_PP->new ({ comment_str => "#" });
701 $csv->comment_str (undef);
702 my $s = $csv->comment_str;
703 This attribute optionally defines a string to be recognized as comment.
705 If this attribute is defined, all lines starting with this sequence
706 will not be parsed as CSV but skipped as comment.
707 This attribute has no meaning when generating CSV.
709 Comment strings that start with any of the special characters/sequences
711 are not supported (so it cannot start with any of "sep_char",
712 "quote_char", "escape_char", "sep", "quote", or "eol").
713 For convenience, "comment" is an alias for "comment_str".
715 verbatim
717 my $csv = Text::CSV_PP->new ({ verbatim => 1 });
719 $csv->verbatim (0);
720 my $f = $csv->verbatim;
721 This is a quite controversial attribute to set, but makes some hard
723 things possible.
724 The rationale behind this attribute is to tell the parser that the
726 normally special characters newline ("NL") and Carriage Return ("CR")
727 will not be special when this flag is set, and be dealt with as being
728 ordinary binary characters. This will ease working with data with
729 embedded newlines.
730 When "verbatim" is used with "getline", "getline" auto-"chomp"'s
732 every line.
733 Imagine a file format like
735 M^^Hans^Janssen^Klas 2\n2A^Ja^11-06-2007#\r\n
737 where, the line ending is a very specific "#\r\n", and the sep_char is
739 a "^" (caret). None of the fields is quoted, but embedded binary
740 data is likely to be present. With the specific line ending, this
741 should not be too hard to detect.
742 By default, Text::CSV_PP' parse function is instructed to only know
744 about "\n" and "\r" to be legal line endings, and so has to deal with
745 the embedded newline as a real "end-of-line", so it can scan the next
746 line if binary is true, and the newline is inside a quoted field. With
747 this option, we tell "parse" to parse the line as if "\n" is just
748 nothing more than a binary character.
749 For "parse" this means that the parser has no more idea about line
751 ending and "getline" "chomp"s line endings on reading.
752 types
754 A set of column types; the attribute is immediately passed to the
756 "types" method.
757 callbacks
759 See the "Callbacks" section below.
761 accessors
763 To sum it up,
765 $csv = Text::CSV_PP->new ();
767 is equivalent to
769 $csv = Text::CSV_PP->new ({
771 eol => undef, # \r, \n, or \r\n
772 sep_char => ',',
773 sep => undef,
774 quote_char => '"',
775 quote => undef,
776 escape_char => '"',
777 binary => 0,
778 decode_utf8 => 1,
779 auto_diag => 0,
780 diag_verbose => 0,
781 blank_is_undef => 0,
782 empty_is_undef => 0,
783 allow_whitespace => 0,
784 allow_loose_quotes => 0,
785 allow_loose_escapes => 0,
786 allow_unquoted_escape => 0,
787 always_quote => 0,
788 quote_empty => 0,
789 quote_space => 1,
790 escape_null => 1,
791 quote_binary => 1,
792 keep_meta_info => 0,
793 strict => 0,
794 skip_empty_rows => 0,
795 formula => 0,
796 verbatim => 0,
797 undef_str => undef,
798 comment_str => undef,
799 types => undef,
800 callbacks => undef,
801 });
802 For all of the above mentioned flags, an accessor method is available
804 where you can inquire the current value, or change the value
805 my $quote = $csv->quote_char;
807 $csv->binary (1);
808 It is not wise to change these settings halfway through writing "CSV"
810 data to a stream. If however you want to create a new stream using the
811 available "CSV" object, there is no harm in changing them.
812 If the "new" constructor call fails, it returns "undef", and makes
814 the fail reason available through the "error_diag" method.
815 $csv = Text::CSV_PP->new ({ ecs_char => 1 }) or
817 die "".Text::CSV_PP->error_diag ();
818 "error_diag" will return a string like
820 "INI - Unknown attribute 'ecs_char'"
822 known_attributes
824 @attr = Text::CSV_PP->known_attributes;
825 @attr = Text::CSV_PP::known_attributes;
826 @attr = $csv->known_attributes;
827 This method will return an ordered list of all the supported
829 attributes as described above. This can be useful for knowing what
830 attributes are valid in classes that use or extend Text::CSV_PP.
831 print
833 $status = $csv->print ($fh, $colref);
834 Similar to "combine" + "string" + "print", but much more efficient.
836 It expects an array ref as input (not an array!) and the resulting
837 string is not really created, but immediately written to the $fh
838 object, typically an IO handle or any other object that offers a
839 "print" method.
840 For performance reasons "print" does not create a result string, so
842 all "string", "status", "fields", and "error_input" methods will return
843 undefined information after executing this method.
844 If $colref is "undef" (explicit, not through a variable argument) and
846 "bind_columns" was used to specify fields to be printed, it is
847 possible to make performance improvements, as otherwise data would have
848 to be copied as arguments to the method call:
849 $csv->bind_columns (\($foo, $bar));
851 $status = $csv->print ($fh, undef);
852 A short benchmark
854 my @data = ("aa" .. "zz");
856 $csv->bind_columns (\(@data));
857 $csv->print ($fh, [ @data ]); # 11800 recs/sec
859 $csv->print ($fh, \@data ); # 57600 recs/sec
860 $csv->print ($fh, undef ); # 48500 recs/sec
861 say
863 $status = $csv->say ($fh, $colref);
864 Like "print", but "eol" defaults to "$\".
866 print_hr
868 $csv->print_hr ($fh, $ref);
869 Provides an easy way to print a $ref (as fetched with "getline_hr")
871 provided the column names are set with "column_names".
872 It is just a wrapper method with basic parameter checks over
874 $csv->print ($fh, [ map { $ref->{$_} } $csv->column_names ]);
876 combine
878 $status = $csv->combine (@fields);
879 This method constructs a "CSV" record from @fields, returning success
881 or failure. Failure can result from lack of arguments or an argument
882 that contains an invalid character. Upon success, "string" can be
883 called to retrieve the resultant "CSV" string. Upon failure, the
884 value returned by "string" is undefined and "error_input" could be
885 called to retrieve the invalid argument.
886 string
888 $line = $csv->string ();
889 This method returns the input to "parse" or the resultant "CSV"
891 string of "combine", whichever was called more recently.
892 getline
894 $colref = $csv->getline ($fh);
895 This is the counterpart to "print", as "parse" is the counterpart to
897 "combine": it parses a row from the $fh handle using the "getline"
898 method associated with $fh and parses this row into an array ref.
899 This array ref is returned by the function or "undef" for failure.
900 When $fh does not support "getline", you are likely to hit errors.
901 When fields are bound with "bind_columns" the return value is a
903 reference to an empty list.
904 The "string", "fields", and "status" methods are meaningless again.
906 getline_all
908 $arrayref = $csv->getline_all ($fh);
909 $arrayref = $csv->getline_all ($fh, $offset);
910 $arrayref = $csv->getline_all ($fh, $offset, $length);
911 This will return a reference to a list of getline ($fh) results. In
913 this call, "keep_meta_info" is disabled. If $offset is negative, as
914 with "splice", only the last "abs ($offset)" records of $fh are taken
915 into consideration.
916 Given a CSV file with 10 lines:
918 lines call
920 ----- ---------------------------------------------------------
921 0..9 $csv->getline_all ($fh) # all
922 0..9 $csv->getline_all ($fh, 0) # all
923 8..9 $csv->getline_all ($fh, 8) # start at 8
924 - $csv->getline_all ($fh, 0, 0) # start at 0 first 0 rows
925 0..4 $csv->getline_all ($fh, 0, 5) # start at 0 first 5 rows
926 4..5 $csv->getline_all ($fh, 4, 2) # start at 4 first 2 rows
927 8..9 $csv->getline_all ($fh, -2) # last 2 rows
928 6..7 $csv->getline_all ($fh, -4, 2) # first 2 of last 4 rows
929 getline_hr
931 The "getline_hr" and "column_names" methods work together to allow you
932 to have rows returned as hashrefs. You must call "column_names" first
933 to declare your column names.
934 $csv->column_names (qw( code name price description ));
936 $hr = $csv->getline_hr ($fh);
937 print "Price for $hr->{name} is $hr->{price} EUR\n";
938 "getline_hr" will croak if called before "column_names".
940 Note that "getline_hr" creates a hashref for every row and will be
942 much slower than the combined use of "bind_columns" and "getline" but
943 still offering the same easy to use hashref inside the loop:
944 my @cols = @{$csv->getline ($fh)};
946 $csv->column_names (@cols);
947 while (my $row = $csv->getline_hr ($fh)) {
948 print $row->{price};
949 }
950 Could easily be rewritten to the much faster:
952 my @cols = @{$csv->getline ($fh)};
954 my $row = {};
955 $csv->bind_columns (\@{$row}{@cols});
956 while ($csv->getline ($fh)) {
957 print $row->{price};
958 }
959 Your mileage may vary for the size of the data and the number of rows.
961 With perl-5.14.2 the comparison for a 100_000 line file with 14
962 columns:
963 Rate hashrefs getlines
965 hashrefs 1.00/s -- -76%
966 getlines 4.15/s 313% --
967 getline_hr_all
969 $arrayref = $csv->getline_hr_all ($fh);
970 $arrayref = $csv->getline_hr_all ($fh, $offset);
971 $arrayref = $csv->getline_hr_all ($fh, $offset, $length);
972 This will return a reference to a list of getline_hr ($fh) results.
974 In this call, "keep_meta_info" is disabled.
975 parse
977 $status = $csv->parse ($line);
978 This method decomposes a "CSV" string into fields, returning success
980 or failure. Failure can result from a lack of argument or the given
981 "CSV" string is improperly formatted. Upon success, "fields" can be
982 called to retrieve the decomposed fields. Upon failure calling "fields"
983 will return undefined data and "error_input" can be called to
984 retrieve the invalid argument.
985 You may use the "types" method for setting column types. See "types"'
987 description below.
988 The $line argument is supposed to be a simple scalar. Everything else
990 is supposed to croak and set error 1500.
991 fragment
993 This function tries to implement RFC7111 (URI Fragment Identifiers for
994 the text/csv Media Type) - http://tools.ietf.org/html/rfc7111
995 my $AoA = $csv->fragment ($fh, $spec);
997 In specifications, "*" is used to specify the last item, a dash ("-")
999 to indicate a range. All indices are 1-based: the first row or
1000 column has index 1. Selections can be combined with the semi-colon
1001 (";").
1002 When using this method in combination with "column_names", the
1004 returned reference will point to a list of hashes instead of a list
1005 of lists. A disjointed cell-based combined selection might return
1006 rows with different number of columns making the use of hashes
1007 unpredictable.
1008 $csv->column_names ("Name", "Age");
1010 my $AoH = $csv->fragment ($fh, "col=3;8");
1011 If the "after_parse" callback is active, it is also called on every
1013 line parsed and skipped before the fragment.
1014 row
1016 row=4
1017 row=5-7
1018 row=6-*
1019 row=1-2;4;6-*
1020 col
1022 col=2
1023 col=1-3
1024 col=4-*
1025 col=1-2;4;7-*
1026 cell
1028 In cell-based selection, the comma (",") is used to pair row and
1029 column
1030 cell=4,1
1032 The range operator ("-") using "cell"s can be used to define top-left
1034 and bottom-right "cell" location
1035 cell=3,1-4,6
1037 The "*" is only allowed in the second part of a pair
1039 cell=3,2-*,2 # row 3 till end, only column 2
1041 cell=3,2-3,* # column 2 till end, only row 3
1042 cell=3,2-*,* # strip row 1 and 2, and column 1
1043 Cells and cell ranges may be combined with ";", possibly resulting in
1045 rows with different numbers of columns
1046 cell=1,1-2,2;3,3-4,4;1,4;4,1
1048 Disjointed selections will only return selected cells. The cells
1050 that are not specified will not be included in the returned
1051 set, not even as "undef". As an example given a "CSV" like
1052 11,12,13,...19
1054 21,22,...28,29
1055 : :
1056 91,...97,98,99
1057 with "cell=1,1-2,2;3,3-4,4;1,4;4,1" will return:
1059 11,12,14
1061 21,22
1062 33,34
1063 41,43,44
1064 Overlapping cell-specs will return those cells only once, So
1066 "cell=1,1-3,3;2,2-4,4;2,3;4,2" will return:
1067 11,12,13
1069 21,22,23,24
1070 31,32,33,34
1071 42,43,44
1072 RFC7111 <http://tools.ietf.org/html/rfc7111> does not allow different
1074 types of specs to be combined (either "row" or "col" or "cell").
1075 Passing an invalid fragment specification will croak and set error
1076 2013.
1077 column_names
1079 Set the "keys" that will be used in the "getline_hr" calls. If no
1080 keys (column names) are passed, it will return the current setting as a
1081 list.
1082 "column_names" accepts a list of scalars (the column names) or a
1084 single array_ref, so you can pass the return value from "getline" too:
1085 $csv->column_names ($csv->getline ($fh));
1087 "column_names" does no checking on duplicates at all, which might lead
1089 to unexpected results. Undefined entries will be replaced with the
1090 string "\cAUNDEF\cA", so
1091 $csv->column_names (undef, "", "name", "name");
1093 $hr = $csv->getline_hr ($fh);
1094 will set "$hr->{"\cAUNDEF\cA"}" to the 1st field, "$hr->{""}" to the
1096 2nd field, and "$hr->{name}" to the 4th field, discarding the 3rd
1097 field.
1098 "column_names" croaks on invalid arguments.
1100 header
1102 This method does NOT work in perl-5.6.x
1103 Parse the CSV header and set "sep", column_names and encoding.
1105 my @hdr = $csv->header ($fh);
1107 $csv->header ($fh, { sep_set => [ ";", ",", "|", "\t" ] });
1108 $csv->header ($fh, { detect_bom => 1, munge_column_names => "lc" });
1109 The first argument should be a file handle.
1111 This method resets some object properties, as it is supposed to be
1113 invoked only once per file or stream. It will leave attributes
1114 "column_names" and "bound_columns" alone if setting column names is
1115 disabled. Reading headers on previously process objects might fail on
1116 perl-5.8.0 and older.
1117 Assuming that the file opened for parsing has a header, and the header
1119 does not contain problematic characters like embedded newlines, read
1120 the first line from the open handle then auto-detect whether the header
1121 separates the column names with a character from the allowed separator
1122 list.
1123 If any of the allowed separators matches, and none of the other
1125 allowed separators match, set "sep" to that separator for the
1126 current CSV_PP instance and use it to parse the first line, map those
1127 to lowercase, and use that to set the instance "column_names":
1128 my $csv = Text::CSV_PP->new ({ binary => 1, auto_diag => 1 });
1130 open my $fh, "<", "file.csv";
1131 binmode $fh; # for Windows
1132 $csv->header ($fh);
1133 while (my $row = $csv->getline_hr ($fh)) {
1134 ...
1135 }
1136 If the header is empty, contains more than one unique separator out of
1138 the allowed set, contains empty fields, or contains identical fields
1139 (after folding), it will croak with error 1010, 1011, 1012, or 1013
1140 respectively.
1141 If the header contains embedded newlines or is not valid CSV in any
1143 other way, this method will croak and leave the parse error untouched.
1144 A successful call to "header" will always set the "sep" of the $csv
1146 object. This behavior can not be disabled.
1147 return value
1149 On error this method will croak.
1151 In list context, the headers will be returned whether they are used to
1153 set "column_names" or not.
1154 In scalar context, the instance itself is returned. Note: the values
1156 as found in the header will effectively be lost if "set_column_names"
1157 is false.
1158 Options
1160 sep_set
1162 $csv->header ($fh, { sep_set => [ ";", ",", "|", "\t" ] });
1163 The list of legal separators defaults to "[ ";", "," ]" and can be
1165 changed by this option. As this is probably the most often used
1166 option, it can be passed on its own as an unnamed argument:
1167 $csv->header ($fh, [ ";", ",", "|", "\t", "::", "\x{2063}" ]);
1169 Multi-byte sequences are allowed, both multi-character and
1171 Unicode. See "sep".
1172 detect_bom
1174 $csv->header ($fh, { detect_bom => 1 });
1175 The default behavior is to detect if the header line starts with a
1177 BOM. If the header has a BOM, use that to set the encoding of $fh.
1178 This default behavior can be disabled by passing a false value to
1179 "detect_bom".
1180 Supported encodings from BOM are: UTF-8, UTF-16BE, UTF-16LE,
1182 UTF-32BE, and UTF-32LE. BOM also supports UTF-1, UTF-EBCDIC, SCSU,
1183 BOCU-1, and GB-18030 but Encode does not (yet). UTF-7 is not
1184 supported.
1185 If a supported BOM was detected as start of the stream, it is stored
1187 in the object attribute "ENCODING".
1188 my $enc = $csv->{ENCODING};
1190 The encoding is used with "binmode" on $fh.
1192 If the handle was opened in a (correct) encoding, this method will
1194 not alter the encoding, as it checks the leading bytes of the first
1195 line. In case the stream starts with a decoded BOM ("U+FEFF"),
1196 "{ENCODING}" will be "" (empty) instead of the default "undef".
1197 munge_column_names
1199 This option offers the means to modify the column names into
1200 something that is most useful to the application. The default is to
1201 map all column names to lower case.
1202 $csv->header ($fh, { munge_column_names => "lc" });
1204 The following values are available:
1206 lc - lower case
1208 uc - upper case
1209 db - valid DB field names
1210 none - do not change
1211 \%hash - supply a mapping
1212 \&cb - supply a callback
1213 Lower case
1215 $csv->header ($fh, { munge_column_names => "lc" });
1216 The header is changed to all lower-case
1218 $_ = lc;
1220 Upper case
1222 $csv->header ($fh, { munge_column_names => "uc" });
1223 The header is changed to all upper-case
1225 $_ = uc;
1227 Literal
1229 $csv->header ($fh, { munge_column_names => "none" });
1230 Hash
1232 $csv->header ($fh, { munge_column_names => { foo => "sombrero" });
1233 if a value does not exist, the original value is used unchanged
1235 Database
1237 $csv->header ($fh, { munge_column_names => "db" });
1238 - lower-case
1240 - all sequences of non-word characters are replaced with an
1242 underscore
1243 - all leading underscores are removed
1245 $_ = lc (s/\W+/_/gr =~ s/^_+//r);
1247 Callback
1249 $csv->header ($fh, { munge_column_names => sub { fc } });
1250 $csv->header ($fh, { munge_column_names => sub { "column_".$col++ } });
1251 $csv->header ($fh, { munge_column_names => sub { lc (s/\W+/_/gr) } });
1252 As this callback is called in a "map", you can use $_ directly.
1254 set_column_names
1256 $csv->header ($fh, { set_column_names => 1 });
1257 The default is to set the instances column names using
1259 "column_names" if the method is successful, so subsequent calls to
1260 "getline_hr" can return a hash. Disable setting the header can be
1261 forced by using a false value for this option.
1262 As described in "return value" above, content is lost in scalar
1264 context.
1265 Validation
1267 When receiving CSV files from external sources, this method can be
1269 used to protect against changes in the layout by restricting to known
1270 headers (and typos in the header fields).
1271 my %known = (
1273 "record key" => "c_rec",
1274 "rec id" => "c_rec",
1275 "id_rec" => "c_rec",
1276 "kode" => "code",
1277 "code" => "code",
1278 "vaule" => "value",
1279 "value" => "value",
1280 );
1281 my $csv = Text::CSV_PP->new ({ binary => 1, auto_diag => 1 });
1282 open my $fh, "<", $source or die "$source: $!";
1283 $csv->header ($fh, { munge_column_names => sub {
1284 s/\s+$//;
1285 s/^\s+//;
1286 $known{lc $_} or die "Unknown column '$_' in $source";
1287 }});
1288 while (my $row = $csv->getline_hr ($fh)) {
1289 say join "\t", $row->{c_rec}, $row->{code}, $row->{value};
1290 }
1291 bind_columns
1293 Takes a list of scalar references to be used for output with "print"
1294 or to store in the fields fetched by "getline". When you do not pass
1295 enough references to store the fetched fields in, "getline" will fail
1296 with error 3006. If you pass more than there are fields to return,
1297 the content of the remaining references is left untouched.
1298 $csv->bind_columns (\$code, \$name, \$price, \$description);
1300 while ($csv->getline ($fh)) {
1301 print "The price of a $name is \x{20ac} $price\n";
1302 }
1303 To reset or clear all column binding, call "bind_columns" with the
1305 single argument "undef". This will also clear column names.
1306 $csv->bind_columns (undef);
1308 If no arguments are passed at all, "bind_columns" will return the list
1310 of current bindings or "undef" if no binds are active.
1311 Note that in parsing with "bind_columns", the fields are set on the
1313 fly. That implies that if the third field of a row causes an error
1314 (or this row has just two fields where the previous row had more), the
1315 first two fields already have been assigned the values of the current
1316 row, while the rest of the fields will still hold the values of the
1317 previous row. If you want the parser to fail in these cases, use the
1318 "strict" attribute.
1319 eof
1321 $eof = $csv->eof ();
1322 If "parse" or "getline" was used with an IO stream, this method will
1324 return true (1) if the last call hit end of file, otherwise it will
1325 return false (''). This is useful to see the difference between a
1326 failure and end of file.
1327 Note that if the parsing of the last line caused an error, "eof" is
1329 still true. That means that if you are not using "auto_diag", an idiom
1330 like
1331 while (my $row = $csv->getline ($fh)) {
1333 # ...
1334 }
1335 $csv->eof or $csv->error_diag;
1336 will not report the error. You would have to change that to
1338 while (my $row = $csv->getline ($fh)) {
1340 # ...
1341 }
1342 +$csv->error_diag and $csv->error_diag;
1343 types
1345 $csv->types (\@tref);
1346 This method is used to force that (all) columns are of a given type.
1348 For example, if you have an integer column, two columns with
1349 doubles and a string column, then you might do a
1350 $csv->types ([Text::CSV_PP::IV (),
1352 Text::CSV_PP::NV (),
1353 Text::CSV_PP::NV (),
1354 Text::CSV_PP::PV ()]);
1355 Column types are used only for decoding columns while parsing, in
1357 other words by the "parse" and "getline" methods.
1358 You can unset column types by doing a
1360 $csv->types (undef);
1362 or fetch the current type settings with
1364 $types = $csv->types ();
1366 IV Set field type to integer.
1368 NV Set field type to numeric/float.
1370 PV Set field type to string.
1372 fields
1374 @columns = $csv->fields ();
1375 This method returns the input to "combine" or the resultant
1377 decomposed fields of a successful "parse", whichever was called more
1378 recently.
1379 Note that the return value is undefined after using "getline", which
1381 does not fill the data structures returned by "parse".
1382 meta_info
1384 @flags = $csv->meta_info ();
1385 This method returns the "flags" of the input to "combine" or the flags
1387 of the resultant decomposed fields of "parse", whichever was called
1388 more recently.
1389 For each field, a meta_info field will hold flags that inform
1391 something about the field returned by the "fields" method or
1392 passed to the "combine" method. The flags are bit-wise-"or"'d like:
1393 " "0x0001
1395 The field was quoted.
1396 " "0x0002
1398 The field was binary.
1399 See the "is_***" methods below.
1401 is_quoted
1403 my $quoted = $csv->is_quoted ($column_idx);
1404 where $column_idx is the (zero-based) index of the column in the
1406 last result of "parse".
1407 This returns a true value if the data in the indicated column was
1409 enclosed in "quote_char" quotes. This might be important for fields
1410 where content ",20070108," is to be treated as a numeric value, and
1411 where ","20070108"," is explicitly marked as character string data.
1412 This method is only valid when "keep_meta_info" is set to a true value.
1414 is_binary
1416 my $binary = $csv->is_binary ($column_idx);
1417 where $column_idx is the (zero-based) index of the column in the
1419 last result of "parse".
1420 This returns a true value if the data in the indicated column contained
1422 any byte in the range "[\x00-\x08,\x10-\x1F,\x7F-\xFF]".
1423 This method is only valid when "keep_meta_info" is set to a true value.
1425 is_missing
1427 my $missing = $csv->is_missing ($column_idx);
1428 where $column_idx is the (zero-based) index of the column in the
1430 last result of "getline_hr".
1431 $csv->keep_meta_info (1);
1433 while (my $hr = $csv->getline_hr ($fh)) {
1434 $csv->is_missing (0) and next; # This was an empty line
1435 }
1436 When using "getline_hr", it is impossible to tell if the parsed
1438 fields are "undef" because they where not filled in the "CSV" stream
1439 or because they were not read at all, as all the fields defined by
1440 "column_names" are set in the hash-ref. If you still need to know if
1441 all fields in each row are provided, you should enable "keep_meta_info"
1442 so you can check the flags.
1443 If "keep_meta_info" is "false", "is_missing" will always return
1445 "undef", regardless of $column_idx being valid or not. If this
1446 attribute is "true" it will return either 0 (the field is present) or 1
1447 (the field is missing).
1448 A special case is the empty line. If the line is completely empty -
1450 after dealing with the flags - this is still a valid CSV line: it is a
1451 record of just one single empty field. However, if "keep_meta_info" is
1452 set, invoking "is_missing" with index 0 will now return true.
1453 status
1455 $status = $csv->status ();
1456 This method returns the status of the last invoked "combine" or "parse"
1458 call. Status is success (true: 1) or failure (false: "undef" or 0).
1459 Note that as this only keeps track of the status of above mentioned
1461 methods, you are probably looking for "error_diag" instead.
1462 error_input
1464 $bad_argument = $csv->error_input ();
1465 This method returns the erroneous argument (if it exists) of "combine"
1467 or "parse", whichever was called more recently. If the last
1468 invocation was successful, "error_input" will return "undef".
1469 Depending on the type of error, it might also hold the data for the
1471 last error-input of "getline".
1472 error_diag
1474 Text::CSV_PP->error_diag ();
1475 $csv->error_diag ();
1476 $error_code = 0 + $csv->error_diag ();
1477 $error_str = "" . $csv->error_diag ();
1478 ($cde, $str, $pos, $rec, $fld) = $csv->error_diag ();
1479 If (and only if) an error occurred, this function returns the
1481 diagnostics of that error.
1482 If called in void context, this will print the internal error code and
1484 the associated error message to STDERR.
1485 If called in list context, this will return the error code and the
1487 error message in that order. If the last error was from parsing, the
1488 rest of the values returned are a best guess at the location within
1489 the line that was being parsed. Their values are 1-based. The
1490 position currently is index of the byte at which the parsing failed in
1491 the current record. It might change to be the index of the current
1492 character in a later release. The records is the index of the record
1493 parsed by the csv instance. The field number is the index of the field
1494 the parser thinks it is currently trying to parse. See
1495 examples/csv-check for how this can be used.
1496 If called in scalar context, it will return the diagnostics in a
1498 single scalar, a-la $!. It will contain the error code in numeric
1499 context, and the diagnostics message in string context.
1500 When called as a class method or a direct function call, the
1502 diagnostics are that of the last "new" call.
1503 record_number
1505 $recno = $csv->record_number ();
1506 Returns the records parsed by this csv instance. This value should be
1508 more accurate than $. when embedded newlines come in play. Records
1509 written by this instance are not counted.
1510 SetDiag
1512 $csv->SetDiag (0);
1513 Use to reset the diagnostics if you are dealing with errors.
1515
1517 This section is also taken from Text::CSV_XS.
1518 csv
1520 This function is not exported by default and should be explicitly
1521 requested:
1522 use Text::CSV_PP qw( csv );
1524 This is a high-level function that aims at simple (user) interfaces.
1526 This can be used to read/parse a "CSV" file or stream (the default
1527 behavior) or to produce a file or write to a stream (define the "out"
1528 attribute). It returns an array- or hash-reference on parsing (or
1529 "undef" on fail) or the numeric value of "error_diag" on writing.
1530 When this function fails you can get to the error using the class call
1531 to "error_diag"
1532 my $aoa = csv (in => "test.csv") or
1534 die Text::CSV_PP->error_diag;
1535 This function takes the arguments as key-value pairs. This can be
1537 passed as a list or as an anonymous hash:
1538 my $aoa = csv ( in => "test.csv", sep_char => ";");
1540 my $aoh = csv ({ in => $fh, headers => "auto" });
1541 The arguments passed consist of two parts: the arguments to "csv"
1543 itself and the optional attributes to the "CSV" object used inside
1544 the function as enumerated and explained in "new".
1545 If not overridden, the default option used for CSV is
1547 auto_diag => 1
1549 escape_null => 0
1550 The option that is always set and cannot be altered is
1552 binary => 1
1554 As this function will likely be used in one-liners, it allows "quote"
1556 to be abbreviated as "quo", and "escape_char" to be abbreviated as
1557 "esc" or "escape".
1558 Alternative invocations:
1560 my $aoa = Text::CSV_PP::csv (in => "file.csv");
1562 my $csv = Text::CSV_PP->new ();
1564 my $aoa = $csv->csv (in => "file.csv");
1565 In the latter case, the object attributes are used from the existing
1567 object and the attribute arguments in the function call are ignored:
1568 my $csv = Text::CSV_PP->new ({ sep_char => ";" });
1570 my $aoh = $csv->csv (in => "file.csv", bom => 1);
1571 will parse using ";" as "sep_char", not ",".
1573 in
1575 Used to specify the source. "in" can be a file name (e.g. "file.csv"),
1577 which will be opened for reading and closed when finished, a file
1578 handle (e.g. $fh or "FH"), a reference to a glob (e.g. "\*ARGV"),
1579 the glob itself (e.g. *STDIN), or a reference to a scalar (e.g.
1580 "\q{1,2,"csv"}").
1581 When used with "out", "in" should be a reference to a CSV structure
1583 (AoA or AoH) or a CODE-ref that returns an array-reference or a hash-
1584 reference. The code-ref will be invoked with no arguments.
1585 my $aoa = csv (in => "file.csv");
1587 open my $fh, "<", "file.csv";
1589 my $aoa = csv (in => $fh);
1590 my $csv = [ [qw( Foo Bar )], [ 1, 2 ], [ 2, 3 ]];
1592 my $err = csv (in => $csv, out => "file.csv");
1593 If called in void context without the "out" attribute, the resulting
1595 ref will be used as input to a subsequent call to csv:
1596 csv (in => "file.csv", filter => { 2 => sub { length > 2 }})
1598 will be a shortcut to
1600 csv (in => csv (in => "file.csv", filter => { 2 => sub { length > 2 }}))
1602 where, in the absence of the "out" attribute, this is a shortcut to
1604 csv (in => csv (in => "file.csv", filter => { 2 => sub { length > 2 }}),
1606 out => *STDOUT)
1607 out
1609 csv (in => $aoa, out => "file.csv");
1611 csv (in => $aoa, out => $fh);
1612 csv (in => $aoa, out => STDOUT);
1613 csv (in => $aoa, out => *STDOUT);
1614 csv (in => $aoa, out => \*STDOUT);
1615 csv (in => $aoa, out => \my $data);
1616 csv (in => $aoa, out => undef);
1617 csv (in => $aoa, out => \"skip");
1618 csv (in => $fh, out => \@aoa);
1620 csv (in => $fh, out => \@aoh, bom => 1);
1621 csv (in => $fh, out => \%hsh, key => "key");
1622 In output mode, the default CSV options when producing CSV are
1624 eol => "\r\n"
1626 The "fragment" attribute is ignored in output mode.
1628 "out" can be a file name (e.g. "file.csv"), which will be opened for
1630 writing and closed when finished, a file handle (e.g. $fh or "FH"), a
1631 reference to a glob (e.g. "\*STDOUT"), the glob itself (e.g. *STDOUT),
1632 or a reference to a scalar (e.g. "\my $data").
1633 csv (in => sub { $sth->fetch }, out => "dump.csv");
1635 csv (in => sub { $sth->fetchrow_hashref }, out => "dump.csv",
1636 headers => $sth->{NAME_lc});
1637 When a code-ref is used for "in", the output is generated per
1639 invocation, so no buffering is involved. This implies that there is no
1640 size restriction on the number of records. The "csv" function ends when
1641 the coderef returns a false value.
1642 If "out" is set to a reference of the literal string "skip", the output
1644 will be suppressed completely, which might be useful in combination
1645 with a filter for side effects only.
1646 my %cache;
1648 csv (in => "dump.csv",
1649 out => \"skip",
1650 on_in => sub { $cache{$_[1][1]}++ });
1651 Currently, setting "out" to any false value ("undef", "", 0) will be
1653 equivalent to "\"skip"".
1654 If the "in" argument point to something to parse, and the "out" is set
1656 to a reference to an "ARRAY" or a "HASH", the output is appended to the
1657 data in the existing reference. The result of the parse should match
1658 what exists in the reference passed. This might come handy when you
1659 have to parse a set of files with similar content (like data stored per
1660 period) and you want to collect that into a single data structure:
1661 my %hash;
1663 csv (in => $_, out => \%hash, key => "id") for sort glob "foo-[0-9]*.csv";
1664 my @list; # List of arrays
1666 csv (in => $_, out => \@list) for sort glob "foo-[0-9]*.csv";
1667 my @list; # List of hashes
1669 csv (in => $_, out => \@list, bom => 1) for sort glob "foo-[0-9]*.csv";
1670 encoding
1672 If passed, it should be an encoding accepted by the ":encoding()"
1674 option to "open". There is no default value. This attribute does not
1675 work in perl 5.6.x. "encoding" can be abbreviated to "enc" for ease of
1676 use in command line invocations.
1677 If "encoding" is set to the literal value "auto", the method "header"
1679 will be invoked on the opened stream to check if there is a BOM and set
1680 the encoding accordingly. This is equal to passing a true value in
1681 the option "detect_bom".
1682 Encodings can be stacked, as supported by "binmode":
1684 # Using PerlIO::via::gzip
1686 csv (in => \@csv,
1687 out => "test.csv:via.gz",
1688 encoding => ":via(gzip):encoding(utf-8)",
1689 );
1690 $aoa = csv (in => "test.csv:via.gz", encoding => ":via(gzip)");
1691 # Using PerlIO::gzip
1693 csv (in => \@csv,
1694 out => "test.csv:via.gz",
1695 encoding => ":gzip:encoding(utf-8)",
1696 );
1697 $aoa = csv (in => "test.csv:gzip.gz", encoding => ":gzip");
1698 detect_bom
1700 If "detect_bom" is given, the method "header" will be invoked on
1702 the opened stream to check if there is a BOM and set the encoding
1703 accordingly.
1704 "detect_bom" can be abbreviated to "bom".
1706 This is the same as setting "encoding" to "auto".
1708 Note that as the method "header" is invoked, its default is to also
1710 set the headers.
1711 headers
1713 If this attribute is not given, the default behavior is to produce an
1715 array of arrays.
1716 If "headers" is supplied, it should be an anonymous list of column
1718 names, an anonymous hashref, a coderef, or a literal flag: "auto",
1719 "lc", "uc", or "skip".
1720 skip
1722 When "skip" is used, the header will not be included in the output.
1723 my $aoa = csv (in => $fh, headers => "skip");
1725 auto
1727 If "auto" is used, the first line of the "CSV" source will be read as
1728 the list of field headers and used to produce an array of hashes.
1729 my $aoh = csv (in => $fh, headers => "auto");
1731 lc
1733 If "lc" is used, the first line of the "CSV" source will be read as
1734 the list of field headers mapped to lower case and used to produce
1735 an array of hashes. This is a variation of "auto".
1736 my $aoh = csv (in => $fh, headers => "lc");
1738 uc
1740 If "uc" is used, the first line of the "CSV" source will be read as
1741 the list of field headers mapped to upper case and used to produce
1742 an array of hashes. This is a variation of "auto".
1743 my $aoh = csv (in => $fh, headers => "uc");
1745 CODE
1747 If a coderef is used, the first line of the "CSV" source will be
1748 read as the list of mangled field headers in which each field is
1749 passed as the only argument to the coderef. This list is used to
1750 produce an array of hashes.
1751 my $aoh = csv (in => $fh,
1753 headers => sub { lc ($_[0]) =~ s/kode/code/gr });
1754 this example is a variation of using "lc" where all occurrences of
1756 "kode" are replaced with "code".
1757 ARRAY
1759 If "headers" is an anonymous list, the entries in the list will be
1760 used as field names. The first line is considered data instead of
1761 headers.
1762 my $aoh = csv (in => $fh, headers => [qw( Foo Bar )]);
1764 csv (in => $aoa, out => $fh, headers => [qw( code description price )]);
1765 HASH
1767 If "headers" is a hash reference, this implies "auto", but header
1768 fields that exist as key in the hashref will be replaced by the value
1769 for that key. Given a CSV file like
1770 post-kode,city,name,id number,fubble
1772 1234AA,Duckstad,Donald,13,"X313DF"
1773 using
1775 csv (headers => { "post-kode" => "pc", "id number" => "ID" }, ...
1777 will return an entry like
1779 { pc => "1234AA",
1781 city => "Duckstad",
1782 name => "Donald",
1783 ID => "13",
1784 fubble => "X313DF",
1785 }
1786 See also "munge_column_names" and "set_column_names".
1788 munge_column_names
1790 If "munge_column_names" is set, the method "header" is invoked on
1792 the opened stream with all matching arguments to detect and set the
1793 headers.
1794 "munge_column_names" can be abbreviated to "munge".
1796 key
1798 If passed, will default "headers" to "auto" and return a hashref
1800 instead of an array of hashes. Allowed values are simple scalars or
1801 array-references where the first element is the joiner and the rest are
1802 the fields to join to combine the key.
1803 my $ref = csv (in => "test.csv", key => "code");
1805 my $ref = csv (in => "test.csv", key => [ ":" => "code", "color" ]);
1806 with test.csv like
1808 code,product,price,color
1810 1,pc,850,gray
1811 2,keyboard,12,white
1812 3,mouse,5,black
1813 the first example will return
1815 { 1 => {
1817 code => 1,
1818 color => 'gray',
1819 price => 850,
1820 product => 'pc'
1821 },
1822 2 => {
1823 code => 2,
1824 color => 'white',
1825 price => 12,
1826 product => 'keyboard'
1827 },
1828 3 => {
1829 code => 3,
1830 color => 'black',
1831 price => 5,
1832 product => 'mouse'
1833 }
1834 }
1835 the second example will return
1837 { "1:gray" => {
1839 code => 1,
1840 color => 'gray',
1841 price => 850,
1842 product => 'pc'
1843 },
1844 "2:white" => {
1845 code => 2,
1846 color => 'white',
1847 price => 12,
1848 product => 'keyboard'
1849 },
1850 "3:black" => {
1851 code => 3,
1852 color => 'black',
1853 price => 5,
1854 product => 'mouse'
1855 }
1856 }
1857 The "key" attribute can be combined with "headers" for "CSV" date that
1859 has no header line, like
1860 my $ref = csv (
1862 in => "foo.csv",
1863 headers => [qw( c_foo foo bar description stock )],
1864 key => "c_foo",
1865 );
1866 value
1868 Used to create key-value hashes.
1870 Only allowed when "key" is valid. A "value" can be either a single
1872 column label or an anonymous list of column labels. In the first case,
1873 the value will be a simple scalar value, in the latter case, it will be
1874 a hashref.
1875 my $ref = csv (in => "test.csv", key => "code",
1877 value => "price");
1878 my $ref = csv (in => "test.csv", key => "code",
1879 value => [ "product", "price" ]);
1880 my $ref = csv (in => "test.csv", key => [ ":" => "code", "color" ],
1881 value => "price");
1882 my $ref = csv (in => "test.csv", key => [ ":" => "code", "color" ],
1883 value => [ "product", "price" ]);
1884 with test.csv like
1886 code,product,price,color
1888 1,pc,850,gray
1889 2,keyboard,12,white
1890 3,mouse,5,black
1891 the first example will return
1893 { 1 => 850,
1895 2 => 12,
1896 3 => 5,
1897 }
1898 the second example will return
1900 { 1 => {
1902 price => 850,
1903 product => 'pc'
1904 },
1905 2 => {
1906 price => 12,
1907 product => 'keyboard'
1908 },
1909 3 => {
1910 price => 5,
1911 product => 'mouse'
1912 }
1913 }
1914 the third example will return
1916 { "1:gray" => 850,
1918 "2:white" => 12,
1919 "3:black" => 5,
1920 }
1921 the fourth example will return
1923 { "1:gray" => {
1925 price => 850,
1926 product => 'pc'
1927 },
1928 "2:white" => {
1929 price => 12,
1930 product => 'keyboard'
1931 },
1932 "3:black" => {
1933 price => 5,
1934 product => 'mouse'
1935 }
1936 }
1937 keep_headers
1939 When using hashes, keep the column names into the arrayref passed, so
1941 all headers are available after the call in the original order.
1942 my $aoh = csv (in => "file.csv", keep_headers => \my @hdr);
1944 This attribute can be abbreviated to "kh" or passed as
1946 "keep_column_names".
1947 This attribute implies a default of "auto" for the "headers" attribute.
1949 fragment
1951 Only output the fragment as defined in the "fragment" method. This
1953 option is ignored when generating "CSV". See "out".
1954 Combining all of them could give something like
1956 use Text::CSV_PP qw( csv );
1958 my $aoh = csv (
1959 in => "test.txt",
1960 encoding => "utf-8",
1961 headers => "auto",
1962 sep_char => "|",
1963 fragment => "row=3;6-9;15-*",
1964 );
1965 say $aoh->[15]{Foo};
1966 sep_set
1968 If "sep_set" is set, the method "header" is invoked on the opened
1970 stream to detect and set "sep_char" with the given set.
1971 "sep_set" can be abbreviated to "seps".
1973 Note that as the "header" method is invoked, its default is to also
1975 set the headers.
1976 set_column_names
1978 If "set_column_names" is passed, the method "header" is invoked on
1980 the opened stream with all arguments meant for "header".
1981 If "set_column_names" is passed as a false value, the content of the
1983 first row is only preserved if the output is AoA:
1984 With an input-file like
1986 bAr,foo
1988 1,2
1989 3,4,5
1990 This call
1992 my $aoa = csv (in => $file, set_column_names => 0);
1994 will result in
1996 [[ "bar", "foo" ],
1998 [ "1", "2" ],
1999 [ "3", "4", "5" ]]
2000 and
2002 my $aoa = csv (in => $file, set_column_names => 0, munge => "none");
2004 will result in
2006 [[ "bAr", "foo" ],
2008 [ "1", "2" ],
2009 [ "3", "4", "5" ]]
2010 Callbacks
2012 Callbacks enable actions triggered from the inside of Text::CSV_PP.
2013 While most of what this enables can easily be done in an unrolled
2015 loop as described in the "SYNOPSIS" callbacks can be used to meet
2016 special demands or enhance the "csv" function.
2017 error
2019 $csv->callbacks (error => sub { $csv->SetDiag (0) });
2020 the "error" callback is invoked when an error occurs, but only
2022 when "auto_diag" is set to a true value. A callback is invoked with
2023 the values returned by "error_diag":
2024 my ($c, $s);
2026 sub ignore3006 {
2028 my ($err, $msg, $pos, $recno, $fldno) = @_;
2029 if ($err == 3006) {
2030 # ignore this error
2031 ($c, $s) = (undef, undef);
2032 Text::CSV_PP->SetDiag (0);
2033 }
2034 # Any other error
2035 return;
2036 } # ignore3006
2037 $csv->callbacks (error => \&ignore3006);
2039 $csv->bind_columns (\$c, \$s);
2040 while ($csv->getline ($fh)) {
2041 # Error 3006 will not stop the loop
2042 }
2043 after_parse
2045 $csv->callbacks (after_parse => sub { push @{$_[1]}, "NEW" });
2046 while (my $row = $csv->getline ($fh)) {
2047 $row->[-1] eq "NEW";
2048 }
2049 This callback is invoked after parsing with "getline" only if no
2051 error occurred. The callback is invoked with two arguments: the
2052 current "CSV" parser object and an array reference to the fields
2053 parsed.
2054 The return code of the callback is ignored unless it is a reference
2056 to the string "skip", in which case the record will be skipped in
2057 "getline_all".
2058 sub add_from_db {
2060 my ($csv, $row) = @_;
2061 $sth->execute ($row->[4]);
2062 push @$row, $sth->fetchrow_array;
2063 } # add_from_db
2064 my $aoa = csv (in => "file.csv", callbacks => {
2066 after_parse => \&add_from_db });
2067 This hook can be used for validation:
2069 FAIL
2071 Die if any of the records does not validate a rule:
2072 after_parse => sub {
2074 $_[1][4] =~ m/^[0-9]{4}\s?[A-Z]{2}$/ or
2075 die "5th field does not have a valid Dutch zipcode";
2076 }
2077 DEFAULT
2079 Replace invalid fields with a default value:
2080 after_parse => sub { $_[1][2] =~ m/^\d+$/ or $_[1][2] = 0 }
2082 SKIP
2084 Skip records that have invalid fields (only applies to
2085 "getline_all"):
2086 after_parse => sub { $_[1][0] =~ m/^\d+$/ or return \"skip"; }
2088 before_print
2090 my $idx = 1;
2091 $csv->callbacks (before_print => sub { $_[1][0] = $idx++ });
2092 $csv->print (*STDOUT, [ 0, $_ ]) for @members;
2093 This callback is invoked before printing with "print" only if no
2095 error occurred. The callback is invoked with two arguments: the
2096 current "CSV" parser object and an array reference to the fields
2097 passed.
2098 The return code of the callback is ignored.
2100 sub max_4_fields {
2102 my ($csv, $row) = @_;
2103 @$row > 4 and splice @$row, 4;
2104 } # max_4_fields
2105 csv (in => csv (in => "file.csv"), out => *STDOUT,
2107 callbacks => { before_print => \&max_4_fields });
2108 This callback is not active for "combine".
2110 Callbacks for csv ()
2112 The "csv" allows for some callbacks that do not integrate in XS
2114 internals but only feature the "csv" function.
2115 csv (in => "file.csv",
2117 callbacks => {
2118 filter => { 6 => sub { $_ > 15 } }, # first
2119 after_parse => sub { say "AFTER PARSE"; }, # first
2120 after_in => sub { say "AFTER IN"; }, # second
2121 on_in => sub { say "ON IN"; }, # third
2122 },
2123 );
2124 csv (in => $aoh,
2126 out => "file.csv",
2127 callbacks => {
2128 on_in => sub { say "ON IN"; }, # first
2129 before_out => sub { say "BEFORE OUT"; }, # second
2130 before_print => sub { say "BEFORE PRINT"; }, # third
2131 },
2132 );
2133 filter
2135 This callback can be used to filter records. It is called just after
2136 a new record has been scanned. The callback accepts a:
2137 hashref
2139 The keys are the index to the row (the field name or field number,
2140 1-based) and the values are subs to return a true or false value.
2141 csv (in => "file.csv", filter => {
2143 3 => sub { m/a/ }, # third field should contain an "a"
2144 5 => sub { length > 4 }, # length of the 5th field minimal 5
2145 });
2146 csv (in => "file.csv", filter => { foo => sub { $_ > 4 }});
2148 If the keys to the filter hash contain any character that is not a
2150 digit it will also implicitly set "headers" to "auto" unless
2151 "headers" was already passed as argument. When headers are
2152 active, returning an array of hashes, the filter is not applicable
2153 to the header itself.
2154 All sub results should match, as in AND.
2156 The context of the callback sets $_ localized to the field
2158 indicated by the filter. The two arguments are as with all other
2159 callbacks, so the other fields in the current row can be seen:
2160 filter => { 3 => sub { $_ > 100 ? $_[1][1] =~ m/A/ : $_[1][6] =~ m/B/ }}
2162 If the context is set to return a list of hashes ("headers" is
2164 defined), the current record will also be available in the
2165 localized %_:
2166 filter => { 3 => sub { $_ > 100 && $_{foo} =~ m/A/ && $_{bar} < 1000 }}
2168 If the filter is used to alter the content by changing $_, make
2170 sure that the sub returns true in order not to have that record
2171 skipped:
2172 filter => { 2 => sub { $_ = uc }}
2174 will upper-case the second field, and then skip it if the resulting
2176 content evaluates to false. To always accept, end with truth:
2177 filter => { 2 => sub { $_ = uc; 1 }}
2179 coderef
2181 csv (in => "file.csv", filter => sub { $n++; 0; });
2182 If the argument to "filter" is a coderef, it is an alias or
2184 shortcut to a filter on column 0:
2185 csv (filter => sub { $n++; 0 });
2187 is equal to
2189 csv (filter => { 0 => sub { $n++; 0 });
2191 filter-name
2193 csv (in => "file.csv", filter => "not_blank");
2194 csv (in => "file.csv", filter => "not_empty");
2195 csv (in => "file.csv", filter => "filled");
2196 These are predefined filters
2198 Given a file like (line numbers prefixed for doc purpose only):
2200 1:1,2,3
2202 2:
2203 3:,
2204 4:""
2205 5:,,
2206 6:, ,
2207 7:"",
2208 8:" "
2209 9:4,5,6
2210 not_blank
2212 Filter out the blank lines
2213 This filter is a shortcut for
2215 filter => { 0 => sub { @{$_[1]} > 1 or
2217 defined $_[1][0] && $_[1][0] ne "" } }
2218 Due to the implementation, it is currently impossible to also
2220 filter lines that consists only of a quoted empty field. These
2221 lines are also considered blank lines.
2222 With the given example, lines 2 and 4 will be skipped.
2224 not_empty
2226 Filter out lines where all the fields are empty.
2227 This filter is a shortcut for
2229 filter => { 0 => sub { grep { defined && $_ ne "" } @{$_[1]} } }
2231 A space is not regarded being empty, so given the example data,
2233 lines 2, 3, 4, 5, and 7 are skipped.
2234 filled
2236 Filter out lines that have no visible data
2237 This filter is a shortcut for
2239 filter => { 0 => sub { grep { defined && m/\S/ } @{$_[1]} } }
2241 This filter rejects all lines that not have at least one field
2243 that does not evaluate to the empty string.
2244 With the given example data, this filter would skip lines 2
2246 through 8.
2247 One could also use modules like Types::Standard:
2249 use Types::Standard -types;
2251 my $type = Tuple[Str, Str, Int, Bool, Optional[Num]];
2253 my $check = $type->compiled_check;
2254 # filter with compiled check and warnings
2256 my $aoa = csv (
2257 in => \$data,
2258 filter => {
2259 0 => sub {
2260 my $ok = $check->($_[1]) or
2261 warn $type->get_message ($_[1]), "\n";
2262 return $ok;
2263 },
2264 },
2265 );
2266 after_in
2268 This callback is invoked for each record after all records have been
2269 parsed but before returning the reference to the caller. The hook is
2270 invoked with two arguments: the current "CSV" parser object and a
2271 reference to the record. The reference can be a reference to a
2272 HASH or a reference to an ARRAY as determined by the arguments.
2273 This callback can also be passed as an attribute without the
2275 "callbacks" wrapper.
2276 before_out
2278 This callback is invoked for each record before the record is
2279 printed. The hook is invoked with two arguments: the current "CSV"
2280 parser object and a reference to the record. The reference can be a
2281 reference to a HASH or a reference to an ARRAY as determined by the
2282 arguments.
2283 This callback can also be passed as an attribute without the
2285 "callbacks" wrapper.
2286 This callback makes the row available in %_ if the row is a hashref.
2288 In this case %_ is writable and will change the original row.
2289 on_in
2291 This callback acts exactly as the "after_in" or the "before_out"
2292 hooks.
2293 This callback can also be passed as an attribute without the
2295 "callbacks" wrapper.
2296 This callback makes the row available in %_ if the row is a hashref.
2298 In this case %_ is writable and will change the original row. So e.g.
2299 with
2300 my $aoh = csv (
2302 in => \"foo\n1\n2\n",
2303 headers => "auto",
2304 on_in => sub { $_{bar} = 2; },
2305 );
2306 $aoh will be:
2308 [ { foo => 1,
2310 bar => 2,
2311 }
2312 { foo => 2,
2313 bar => 2,
2314 }
2315 ]
2316 csv
2318 The function "csv" can also be called as a method or with an
2319 existing Text::CSV_PP object. This could help if the function is to
2320 be invoked a lot of times and the overhead of creating the object
2321 internally over and over again would be prevented by passing an
2322 existing instance.
2323 my $csv = Text::CSV_PP->new ({ binary => 1, auto_diag => 1 });
2325 my $aoa = $csv->csv (in => $fh);
2327 my $aoa = csv (in => $fh, csv => $csv);
2328 both act the same. Running this 20000 times on a 20 lines CSV file,
2330 showed a 53% speedup.
2331
2333 This section is also taken from Text::CSV_XS.
2334 Still under construction ...
2336 If an error occurs, "$csv->error_diag" can be used to get information
2338 on the cause of the failure. Note that for speed reasons the internal
2339 value is never cleared on success, so using the value returned by
2340 "error_diag" in normal cases - when no error occurred - may cause
2341 unexpected results.
2342 If the constructor failed, the cause can be found using "error_diag" as
2344 a class method, like "Text::CSV_PP->error_diag".
2345 The "$csv->error_diag" method is automatically invoked upon error when
2347 the contractor was called with "auto_diag" set to 1 or 2, or when
2348 autodie is in effect. When set to 1, this will cause a "warn" with the
2349 error message, when set to 2, it will "die". "2012 - EOF" is excluded
2350 from "auto_diag" reports.
2351 Errors can be (individually) caught using the "error" callback.
2353 The errors as described below are available. I have tried to make the
2355 error itself explanatory enough, but more descriptions will be added.
2356 For most of these errors, the first three capitals describe the error
2357 category:
2358 • INI
2360 Initialization error or option conflict.
2362 • ECR
2364 Carriage-Return related parse error.
2366 • EOF
2368 End-Of-File related parse error.
2370 • EIQ
2372 Parse error inside quotation.
2374 • EIF
2376 Parse error inside field.
2378 • ECB
2380 Combine error.
2382 • EHR
2384 HashRef parse related error.
2386 And below should be the complete list of error codes that can be
2388 returned:
2389 • 1001 "INI - sep_char is equal to quote_char or escape_char"
2391 The separation character cannot be equal to the quotation
2393 character or to the escape character, as this would invalidate all
2394 parsing rules.
2395 • 1002 "INI - allow_whitespace with escape_char or quote_char SP or
2397 TAB"
2398 Using the "allow_whitespace" attribute when either "quote_char" or
2400 "escape_char" is equal to "SPACE" or "TAB" is too ambiguous to
2401 allow.
2402 • 1003 "INI - \r or \n in main attr not allowed"
2404 Using default "eol" characters in either "sep_char", "quote_char",
2406 or "escape_char" is not allowed.
2407 • 1004 "INI - callbacks should be undef or a hashref"
2409 The "callbacks" attribute only allows one to be "undef" or a hash
2411 reference.
2412 • 1005 "INI - EOL too long"
2414 The value passed for EOL is exceeding its maximum length (16).
2416 • 1006 "INI - SEP too long"
2418 The value passed for SEP is exceeding its maximum length (16).
2420 • 1007 "INI - QUOTE too long"
2422 The value passed for QUOTE is exceeding its maximum length (16).
2424 • 1008 "INI - SEP undefined"
2426 The value passed for SEP should be defined and not empty.
2428 • 1010 "INI - the header is empty"
2430 The header line parsed in the "header" is empty.
2432 • 1011 "INI - the header contains more than one valid separator"
2434 The header line parsed in the "header" contains more than one
2436 (unique) separator character out of the allowed set of separators.
2437 • 1012 "INI - the header contains an empty field"
2439 The header line parsed in the "header" contains an empty field.
2441 • 1013 "INI - the header contains nun-unique fields"
2443 The header line parsed in the "header" contains at least two
2445 identical fields.
2446 • 1014 "INI - header called on undefined stream"
2448 The header line cannot be parsed from an undefined source.
2450 • 1500 "PRM - Invalid/unsupported argument(s)"
2452 Function or method called with invalid argument(s) or parameter(s).
2454 • 1501 "PRM - The key attribute is passed as an unsupported type"
2456 The "key" attribute is of an unsupported type.
2458 • 1502 "PRM - The value attribute is passed without the key attribute"
2460 The "value" attribute is only allowed when a valid key is given.
2462 • 1503 "PRM - The value attribute is passed as an unsupported type"
2464 The "value" attribute is of an unsupported type.
2466 • 2010 "ECR - QUO char inside quotes followed by CR not part of EOL"
2468 When "eol" has been set to anything but the default, like
2470 "\r\t\n", and the "\r" is following the second (closing)
2471 "quote_char", where the characters following the "\r" do not make up
2472 the "eol" sequence, this is an error.
2473 • 2011 "ECR - Characters after end of quoted field"
2475 Sequences like "1,foo,"bar"baz,22,1" are not allowed. "bar" is a
2477 quoted field and after the closing double-quote, there should be
2478 either a new-line sequence or a separation character.
2479 • 2012 "EOF - End of data in parsing input stream"
2481 Self-explaining. End-of-file while inside parsing a stream. Can
2483 happen only when reading from streams with "getline", as using
2484 "parse" is done on strings that are not required to have a trailing
2485 "eol".
2486 • 2013 "INI - Specification error for fragments RFC7111"
2488 Invalid specification for URI "fragment" specification.
2490 • 2014 "ENF - Inconsistent number of fields"
2492 Inconsistent number of fields under strict parsing.
2494 • 2021 "EIQ - NL char inside quotes, binary off"
2496 Sequences like "1,"foo\nbar",22,1" are allowed only when the binary
2498 option has been selected with the constructor.
2499 • 2022 "EIQ - CR char inside quotes, binary off"
2501 Sequences like "1,"foo\rbar",22,1" are allowed only when the binary
2503 option has been selected with the constructor.
2504 • 2023 "EIQ - QUO character not allowed"
2506 Sequences like ""foo "bar" baz",qu" and "2023,",2008-04-05,"Foo,
2508 Bar",\n" will cause this error.
2509 • 2024 "EIQ - EOF cannot be escaped, not even inside quotes"
2511 The escape character is not allowed as last character in an input
2513 stream.
2514 • 2025 "EIQ - Loose unescaped escape"
2516 An escape character should escape only characters that need escaping.
2518 Allowing the escape for other characters is possible with the
2520 attribute "allow_loose_escapes".
2521 • 2026 "EIQ - Binary character inside quoted field, binary off"
2523 Binary characters are not allowed by default. Exceptions are
2525 fields that contain valid UTF-8, that will automatically be upgraded
2526 if the content is valid UTF-8. Set "binary" to 1 to accept binary
2527 data.
2528 • 2027 "EIQ - Quoted field not terminated"
2530 When parsing a field that started with a quotation character, the
2532 field is expected to be closed with a quotation character. When the
2533 parsed line is exhausted before the quote is found, that field is not
2534 terminated.
2535 • 2030 "EIF - NL char inside unquoted verbatim, binary off"
2537 • 2031 "EIF - CR char is first char of field, not part of EOL"
2539 • 2032 "EIF - CR char inside unquoted, not part of EOL"
2541 • 2034 "EIF - Loose unescaped quote"
2543 • 2035 "EIF - Escaped EOF in unquoted field"
2545 • 2036 "EIF - ESC error"
2547 • 2037 "EIF - Binary character in unquoted field, binary off"
2549 • 2110 "ECB - Binary character in Combine, binary off"
2551 • 2200 "EIO - print to IO failed. See errno"
2553 • 3001 "EHR - Unsupported syntax for column_names ()"
2555 • 3002 "EHR - getline_hr () called before column_names ()"
2557 • 3003 "EHR - bind_columns () and column_names () fields count
2559 mismatch"
2560 • 3004 "EHR - bind_columns () only accepts refs to scalars"
2562 • 3006 "EHR - bind_columns () did not pass enough refs for parsed
2564 fields"
2565 • 3007 "EHR - bind_columns needs refs to writable scalars"
2567 • 3008 "EHR - unexpected error in bound fields"
2569 • 3009 "EHR - print_hr () called before column_names ()"
2571 • 3010 "EHR - print_hr () called with invalid arguments"
2573
2575 Text::CSV_XS, Text::CSV
2576 Older versions took many regexp from
2578 <http://www.din.or.jp/~ohzaki/perl.htm>
2579
2581 Kenichi Ishigaki, <ishigaki[at]cpan.org> Makamaka Hannyaharamitu,
2582 <makamaka[at]cpan.org>
2583 Text::CSV_XS was written by <joe[at]ispsoft.de> and maintained by
2585 <h.m.brand[at]xs4all.nl>.
2586 Text::CSV was written by <alan[at]mfgrtl.com>.
2588
2590 Copyright 2017- by Kenichi Ishigaki, <ishigaki[at]cpan.org> Copyright
2591 2005-2015 by Makamaka Hannyaharamitu, <makamaka[at]cpan.org>
2592 Most of the code and doc is directly taken from the pure perl part of
2594 Text::CSV_XS.
2595 Copyright (C) 2007-2016 H.Merijn Brand. All rights reserved.
2597 Copyright (C) 1998-2001 Jochen Wiedmann. All rights reserved.
2598 Copyright (C) 1997 Alan Citterman. All rights reserved.
2599 This library is free software; you can redistribute it and/or modify it
2601 under the same terms as Perl itself.
2602perl v5.34.0 2022-01-21 Text::CSV_PP(3)