1Text::CSV_PP(3)       User Contributed Perl Documentation      Text::CSV_PP(3)
2
3
4

NAME

6       Text::CSV_PP - Text::CSV_XS compatible pure-Perl module
7

SYNOPSIS

9       This section is taken from Text::CSV_XS.
10
11        # Functional interface
12        use Text::CSV_PP qw( csv );
13
14        # 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
19        # Write array of arrays as csv file
20        csv (in => $aoa, out => "file.csv", sep_char=> ";");
21
22        # Only show lines where "code" is odd
23        csv (in => "data.csv", filter => { code => sub { $_ % 2 }});
24
25        # Object interface
26        use Text::CSV_PP;
27
28        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
38        # 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

DESCRIPTION

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
53       The following caveats are taken from the doc of Text::CSV_XS.
54
55   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
64       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
68        my $csv = Text::CSV_PP->new ({ binary => 1, eol => $/ });
69        while (<>) {           #  WRONG!
70            $csv->parse ($_);
71            my @fields = $csv->fields ();
72            }
73
74       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
79        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
85       The old(er) way of using global file handles is still supported
86
87        while (my $row = $csv->getline (*ARGV)) { ... }
88
89   Unicode
90       Unicode is only tested to work with perl-5.8.2 and up.
91
92       See also "BOM".
93
94       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
98        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
102        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
106       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
110       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
119        $csv->print ($fh, [ map { utf8::upgrade (my $x = $_); $x } @data ]);
120
121       For complete control over encoding, please use Text::CSV::Encoded:
122
123        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
129        $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
133        $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
137   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
144       If a file has a BOM, the easiest way to deal with that is
145
146        my $aoh = csv (in => $file, detect_bom => 1);
147
148       All records will be encoded based on the detected BOM.
149
150       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
153        my $aoh = csv (in => $file, headers => "auto");
154
155       which only reads the first record to set  "column_names"  but ignores
156       any meaning of possible present BOM.
157

METHODS

159       This section is also taken from Text::CSV_XS.
160
161   version
162       (Class method) Returns the current module version.
163
164   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
168        my $csv = Text::CSV_PP->new ({ attributes ... });
169
170       The following attributes are available:
171
172       eol
173
174        my $csv = Text::CSV_PP->new ({ eol => $/ });
175                  $csv->eol (undef);
176        my $eol = $csv->eol;
177
178       The end-of-line string to add to rows for "print" or the record
179       separator for "getline".
180
181       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
185       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
189       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
193       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
196       sep_char
197
198        my $csv = Text::CSV_PP->new ({ sep_char => ";" });
199                $csv->sep_char (";");
200        my $c = $csv->sep_char;
201
202       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
206       The separation character can not be equal to the quote character  or to
207       the escape character.
208
209       sep
210
211        my $csv = Text::CSV_PP->new ({ sep => "\N{FULLWIDTH COMMA}" });
212                  $csv->sep (";");
213        my $sep = $csv->sep;
214
215       The chars used to separate fields, by default undefined. Limited to 8
216       bytes.
217
218       When set, overrules "sep_char".  If its length is one byte it acts as
219       an alias to "sep_char".
220
221       quote_char
222
223        my $csv = Text::CSV_PP->new ({ quote_char => "'" });
224                $csv->quote_char (undef);
225        my $c = $csv->quote_char;
226
227       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
233       "quote_char" can not be equal to "sep_char".
234
235       quote
236
237        my $csv = Text::CSV_PP->new ({ quote => "\N{FULLWIDTH QUOTATION MARK}" });
238                    $csv->quote ("'");
239        my $quote = $csv->quote;
240
241       The chars used to quote fields, by default undefined. Limited to 8
242       bytes.
243
244       When set, overrules "quote_char". If its length is one byte it acts as
245       an alias to "quote_char".
246
247       This method does not support "undef".  Use "quote_char" to disable
248       quotation.
249
250       escape_char
251
252        my $csv = Text::CSV_PP->new ({ escape_char => "\\" });
253                $csv->escape_char (":");
254        my $c = $csv->escape_char;
255
256       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
260       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
264        "foo","bar","Escape ""quote mark"" with two ""quote marks""","baz"
265
266       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
272       Setting "escape_char" to <undef> or "" will disable escaping completely
273       and is greatly discouraged. This will also disable "escape_null".
274
275       The escape character can not be equal to the separation character.
276
277       binary
278
279        my $csv = Text::CSV_PP->new ({ binary => 1 });
280                $csv->binary (0);
281        my $f = $csv->binary;
282
283       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
287       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
292       strict
293
294        my $csv = Text::CSV_PP->new ({ strict => 1 });
295                $csv->strict (0);
296        my $f = $csv->strict;
297
298       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
302       skip_empty_rows
303
304        my $csv = Text::CSV_PP->new ({ skip_empty_rows => 1 });
305                $csv->skip_empty_rows (0);
306        my $f = $csv->skip_empty_rows;
307
308       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
312       This attribute is only used in parsing.
313
314       formula_handling
315
316       formula
317
318        my $csv = Text::CSV_PP->new ({ formula => "none" });
319                $csv->formula ("none");
320        my $f = $csv->formula;
321
322       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
326       For purpose of code-readability, this can also be written as
327
328        my $csv = Text::CSV_PP->new ({ formula_handling => "none" });
329                $csv->formula_handling ("none");
330        my $f = $csv->formula_handling;
331
332       Possible values for this attribute are
333
334       none
335         Take no specific action. This is the default.
336
337          $csv->formula ("none");
338
339       die
340         Cause the process to "die" whenever a leading "=" is encountered.
341
342          $csv->formula ("die");
343
344       croak
345         Cause the process to "croak" whenever a leading "=" is encountered.
346         (See Carp)
347
348          $csv->formula ("croak");
349
350       diag
351         Report position and content of the field whenever a leading  "=" is
352         found.  The value of the field is unchanged.
353
354          $csv->formula ("diag");
355
356       empty
357         Replace the content of fields that start with a "=" with the empty
358         string.
359
360          $csv->formula ("empty");
361          $csv->formula ("");
362
363       undef
364         Replace the content of fields that start with a "=" with "undef".
365
366          $csv->formula ("undef");
367          $csv->formula (undef);
368
369       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
374          # Replace all formula's with 42
375          $csv->formula (sub { 42; });
376
377          # same as $csv->formula ("empty") but slower
378          $csv->formula (sub { "" });
379
380          # Allow =4+12
381          $csv->formula (sub { s/^=(\d+\+\d+)$/$1/eer });
382
383          # Allow more complex calculations
384          $csv->formula (sub { eval { s{^=([-+*/0-9()]+)$}{$1}ee }; $_ });
385
386       All other values will give a warning and then fallback to "diag".
387
388       decode_utf8
389
390        my $csv = Text::CSV_PP->new ({ decode_utf8 => 1 });
391                $csv->decode_utf8 (0);
392        my $f = $csv->decode_utf8;
393
394       This attributes defaults to TRUE.
395
396       While parsing,  fields that are valid UTF-8, are automatically set to
397       be UTF-8, so that
398
399         $csv->parse ("\xC4\xA8\n");
400
401       results in
402
403         PV("\304\250"\0) [UTF8 "\x{128}"]
404
405       Sometimes it might not be a desired action.  To prevent those upgrades,
406       set this attribute to false, and the result will be
407
408         PV("\304\250"\0)
409
410       auto_diag
411
412        my $csv = Text::CSV_PP->new ({ auto_diag => 1 });
413                $csv->auto_diag (2);
414        my $l = $csv->auto_diag;
415
416       Set this attribute to a number between 1 and 9 causes  "error_diag" to
417       be automatically called in void context upon errors.
418
419       In case of error "2012 - EOF", this call will be void.
420
421       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
425       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
430       diag_verbose
431
432        my $csv = Text::CSV_PP->new ({ diag_verbose => 1 });
433                $csv->diag_verbose (2);
434        my $l = $csv->diag_verbose;
435
436       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
440       blank_is_undef
441
442        my $csv = Text::CSV_PP->new ({ blank_is_undef => 1 });
443                $csv->blank_is_undef (0);
444        my $f = $csv->blank_is_undef;
445
446       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
450        1,"",," ",2
451
452       is read as
453
454        ("1", "", "", " ", "2")
455
456       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
462        ("1", "", undef, " ", "2")
463
464       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
468       empty_is_undef
469
470        my $csv = Text::CSV_PP->new ({ empty_is_undef => 1 });
471                $csv->empty_is_undef (0);
472        my $f = $csv->empty_is_undef;
473
474       Going one  step  further  than  "blank_is_undef",  this attribute
475       converts all empty fields to "undef", so
476
477        1,"",," ",2
478
479       is read as
480
481        (1, undef, undef, " ", 2)
482
483       Note that this affects only fields that are  originally  empty,  not
484       fields that are empty after stripping allowed whitespace. YMMV.
485
486       allow_whitespace
487
488        my $csv = Text::CSV_PP->new ({ allow_whitespace => 1 });
489                $csv->allow_whitespace (0);
490        my $f = $csv->allow_whitespace;
491
492       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
498       Now lines like:
499
500        1 , "foo" , bar , 3 , zapp
501
502       are parsed as valid "CSV", even though it violates the "CSV" specs.
503
504       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
508        1,   2.0,  3,   ape  , monkey
509
510       will now be parsed as
511
512        ("1", "2.0", "3", "ape", "monkey")
513
514       even if the original line was perfectly acceptable "CSV".
515
516       allow_loose_quotes
517
518        my $csv = Text::CSV_PP->new ({ allow_loose_quotes => 1 });
519                $csv->allow_loose_quotes (0);
520        my $f = $csv->allow_loose_quotes;
521
522       By default, parsing unquoted fields containing "quote_char" characters
523       like
524
525        1,foo "bar" baz,42
526
527       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
531       If there is really bad "CSV" data, like
532
533        1,"foo "bar" baz",42
534
535       or
536
537        1,""foo bar baz"",42
538
539       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
544       allow_loose_escapes
545
546        my $csv = Text::CSV_PP->new ({ allow_loose_escapes => 1 });
547                $csv->allow_loose_escapes (0);
548        my $f = $csv->allow_loose_escapes;
549
550       Parsing fields  that  have  "escape_char"  characters that escape
551       characters that do not need to be escaped, like:
552
553        my $csv = Text::CSV_PP->new ({ escape_char => "\\" });
554        $csv->parse (qq{1,"my bar\'s",baz,42});
555
556       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
560       allow_unquoted_escape
561
562        my $csv = Text::CSV_PP->new ({ allow_unquoted_escape => 1 });
563                $csv->allow_unquoted_escape (0);
564        my $f = $csv->allow_unquoted_escape;
565
566       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
571        1,\0,2
572
573       Setting this attribute to 1  might help to overcome issues with
574       backward compatibility and allow this style.
575
576       always_quote
577
578        my $csv = Text::CSV_PP->new ({ always_quote => 1 });
579                $csv->always_quote (0);
580        my $f = $csv->always_quote;
581
582       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
588       quote_space
589
590        my $csv = Text::CSV_PP->new ({ quote_space => 1 });
591                $csv->quote_space (0);
592        my $f = $csv->quote_space;
593
594       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
599       quote_empty
600
601        my $csv = Text::CSV_PP->new ({ quote_empty => 1 });
602                $csv->quote_empty (0);
603        my $f = $csv->quote_empty;
604
605       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
610       quote_binary
611
612        my $csv = Text::CSV_PP->new ({ quote_binary => 1 });
613                $csv->quote_binary (0);
614        my $f = $csv->quote_binary;
615
616       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
620       escape_null
621
622        my $csv = Text::CSV_PP->new ({ escape_null => 1 });
623                $csv->escape_null (0);
624        my $f = $csv->escape_null;
625
626       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
631       When the "escape_char" attribute is set to undefined,  this attribute
632       will be set to false.
633
634       The default setting will encode "=\x00=" as
635
636        "="0="
637
638       With "escape_null" set, this will result in
639
640        "=\x00="
641
642       The default when using the "csv" function is "false".
643
644       For backward compatibility reasons,  the deprecated old name
645       "quote_null" is still recognized.
646
647       keep_meta_info
648
649        my $csv = Text::CSV_PP->new ({ keep_meta_info => 1 });
650                $csv->keep_meta_info (0);
651        my $f = $csv->keep_meta_info;
652
653       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
660       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
665        my $csv = Text::CSV_PP->new ({
666           binary         => 1,
667           keep_meta_info => 1,
668           quote_space    => 0,
669           });
670
671        my $row = $csv->parse (q{1,,"", ," ",f,"g","h""h",help,"help"});
672
673        $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
679       undef_str
680
681        my $csv = Text::CSV_PP->new ({ undef_str => "\\N" });
682                $csv->undef_str (undef);
683        my $s = $csv->undef_str;
684
685       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
692       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
696       This attribute has no meaning when parsing CSV data.
697
698       comment_str
699
700        my $csv = Text::CSV_PP->new ({ comment_str => "#" });
701                $csv->comment_str (undef);
702        my $s = $csv->comment_str;
703
704       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
708       This attribute has no meaning when generating CSV.
709
710       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
714       For convenience, "comment" is an alias for "comment_str".
715
716       verbatim
717
718        my $csv = Text::CSV_PP->new ({ verbatim => 1 });
719                $csv->verbatim (0);
720        my $f = $csv->verbatim;
721
722       This is a quite controversial attribute to set,  but makes some hard
723       things possible.
724
725       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
731       When  "verbatim"  is used with  "getline",  "getline"  auto-"chomp"'s
732       every line.
733
734       Imagine a file format like
735
736        M^^Hans^Janssen^Klas 2\n2A^Ja^11-06-2007#\r\n
737
738       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
743       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
750       For "parse" this means that the parser has no more idea about line
751       ending and "getline" "chomp"s line endings on reading.
752
753       types
754
755       A set of column types; the attribute is immediately passed to the
756       "types" method.
757
758       callbacks
759
760       See the "Callbacks" section below.
761
762       accessors
763
764       To sum it up,
765
766        $csv = Text::CSV_PP->new ();
767
768       is equivalent to
769
770        $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
803       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
806        my $quote = $csv->quote_char;
807        $csv->binary (1);
808
809       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
813       If the "new" constructor call fails,  it returns "undef",  and makes
814       the fail reason available through the "error_diag" method.
815
816        $csv = Text::CSV_PP->new ({ ecs_char => 1 }) or
817            die "".Text::CSV_PP->error_diag ();
818
819       "error_diag" will return a string like
820
821        "INI - Unknown attribute 'ecs_char'"
822
823   known_attributes
824        @attr = Text::CSV_PP->known_attributes;
825        @attr = Text::CSV_PP::known_attributes;
826        @attr = $csv->known_attributes;
827
828       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
832   print
833        $status = $csv->print ($fh, $colref);
834
835       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
841       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
845       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
850        $csv->bind_columns (\($foo, $bar));
851        $status = $csv->print ($fh, undef);
852
853       A short benchmark
854
855        my @data = ("aa" .. "zz");
856        $csv->bind_columns (\(@data));
857
858        $csv->print ($fh, [ @data ]);   # 11800 recs/sec
859        $csv->print ($fh,  \@data  );   # 57600 recs/sec
860        $csv->print ($fh,   undef  );   # 48500 recs/sec
861
862   say
863        $status = $csv->say ($fh, $colref);
864
865       Like "print", but "eol" defaults to "$\".
866
867   print_hr
868        $csv->print_hr ($fh, $ref);
869
870       Provides an easy way  to print a  $ref  (as fetched with "getline_hr")
871       provided the column names are set with "column_names".
872
873       It is just a wrapper method with basic parameter checks over
874
875        $csv->print ($fh, [ map { $ref->{$_} } $csv->column_names ]);
876
877   combine
878        $status = $csv->combine (@fields);
879
880       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
887   string
888        $line = $csv->string ();
889
890       This method returns the input to  "parse"  or the resultant "CSV"
891       string of "combine", whichever was called more recently.
892
893   getline
894        $colref = $csv->getline ($fh);
895
896       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
902       When fields are bound with "bind_columns" the return value is a
903       reference to an empty list.
904
905       The "string", "fields", and "status" methods are meaningless again.
906
907   getline_all
908        $arrayref = $csv->getline_all ($fh);
909        $arrayref = $csv->getline_all ($fh, $offset);
910        $arrayref = $csv->getline_all ($fh, $offset, $length);
911
912       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
917       Given a CSV file with 10 lines:
918
919        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
930   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
935        $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
939       "getline_hr" will croak if called before "column_names".
940
941       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
945        my @cols = @{$csv->getline ($fh)};
946        $csv->column_names (@cols);
947        while (my $row = $csv->getline_hr ($fh)) {
948            print $row->{price};
949            }
950
951       Could easily be rewritten to the much faster:
952
953        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
960       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
964                   Rate hashrefs getlines
965        hashrefs 1.00/s       --     -76%
966        getlines 4.15/s     313%       --
967
968   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
973       This will return a reference to a list of   getline_hr ($fh) results.
974       In this call, "keep_meta_info" is disabled.
975
976   parse
977        $status = $csv->parse ($line);
978
979       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
986       You may use the "types"  method for setting column types.  See "types"'
987       description below.
988
989       The $line argument is supposed to be a simple scalar. Everything else
990       is supposed to croak and set error 1500.
991
992   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
996        my $AoA = $csv->fragment ($fh, $spec);
997
998       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
1003       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
1009        $csv->column_names ("Name", "Age");
1010        my $AoH = $csv->fragment ($fh, "col=3;8");
1011
1012       If the "after_parse" callback is active,  it is also called on every
1013       line parsed and skipped before the fragment.
1014
1015       row
1016          row=4
1017          row=5-7
1018          row=6-*
1019          row=1-2;4;6-*
1020
1021       col
1022          col=2
1023          col=1-3
1024          col=4-*
1025          col=1-2;4;7-*
1026
1027       cell
1028         In cell-based selection, the comma (",") is used to pair row and
1029         column
1030
1031          cell=4,1
1032
1033         The range operator ("-") using "cell"s can be used to define top-left
1034         and bottom-right "cell" location
1035
1036          cell=3,1-4,6
1037
1038         The "*" is only allowed in the second part of a pair
1039
1040          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
1044         Cells and cell ranges may be combined with ";", possibly resulting in
1045         rows with different numbers of columns
1046
1047          cell=1,1-2,2;3,3-4,4;1,4;4,1
1048
1049         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
1053          11,12,13,...19
1054          21,22,...28,29
1055          :            :
1056          91,...97,98,99
1057
1058         with "cell=1,1-2,2;3,3-4,4;1,4;4,1" will return:
1059
1060          11,12,14
1061          21,22
1062          33,34
1063          41,43,44
1064
1065         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
1068          11,12,13
1069          21,22,23,24
1070          31,32,33,34
1071          42,43,44
1072
1073       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
1078   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
1083       "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
1086        $csv->column_names ($csv->getline ($fh));
1087
1088       "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
1092        $csv->column_names (undef, "", "name", "name");
1093        $hr = $csv->getline_hr ($fh);
1094
1095       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
1099       "column_names" croaks on invalid arguments.
1100
1101   header
1102       This method does NOT work in perl-5.6.x
1103
1104       Parse the CSV header and set "sep", column_names and encoding.
1105
1106        my @hdr = $csv->header ($fh);
1107        $csv->header ($fh, { sep_set => [ ";", ",", "|", "\t" ] });
1108        $csv->header ($fh, { detect_bom => 1, munge_column_names => "lc" });
1109
1110       The first argument should be a file handle.
1111
1112       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
1118       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
1124       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
1129        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
1137       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
1142       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
1145       A successful call to "header"  will always set the  "sep"  of the $csv
1146       object. This behavior can not be disabled.
1147
1148       return value
1149
1150       On error this method will croak.
1151
1152       In list context,  the headers will be returned whether they are used to
1153       set "column_names" or not.
1154
1155       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
1159       Options
1160
1161       sep_set
1162          $csv->header ($fh, { sep_set => [ ";", ",", "|", "\t" ] });
1163
1164         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
1168          $csv->header ($fh, [ ";", ",", "|", "\t", "::", "\x{2063}" ]);
1169
1170         Multi-byte  sequences are allowed,  both multi-character and
1171         Unicode.  See "sep".
1172
1173       detect_bom
1174          $csv->header ($fh, { detect_bom => 1 });
1175
1176         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
1181         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
1186         If a supported BOM was detected as start of the stream, it is stored
1187         in the object attribute "ENCODING".
1188
1189          my $enc = $csv->{ENCODING};
1190
1191         The encoding is used with "binmode" on $fh.
1192
1193         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
1198       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
1203          $csv->header ($fh, { munge_column_names => "lc" });
1204
1205         The following values are available:
1206
1207           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
1214         Lower case
1215            $csv->header ($fh, { munge_column_names => "lc" });
1216
1217           The header is changed to all lower-case
1218
1219            $_ = lc;
1220
1221         Upper case
1222            $csv->header ($fh, { munge_column_names => "uc" });
1223
1224           The header is changed to all upper-case
1225
1226            $_ = uc;
1227
1228         Literal
1229            $csv->header ($fh, { munge_column_names => "none" });
1230
1231         Hash
1232            $csv->header ($fh, { munge_column_names => { foo => "sombrero" });
1233
1234           if a value does not exist, the original value is used unchanged
1235
1236         Database
1237            $csv->header ($fh, { munge_column_names => "db" });
1238
1239           - lower-case
1240
1241           - all sequences of non-word characters are replaced with an
1242             underscore
1243
1244           - all leading underscores are removed
1245
1246            $_ = lc (s/\W+/_/gr =~ s/^_+//r);
1247
1248         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
1253           As this callback is called in a "map", you can use $_ directly.
1254
1255       set_column_names
1256          $csv->header ($fh, { set_column_names => 1 });
1257
1258         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
1263         As described in "return value" above, content is lost in scalar
1264         context.
1265
1266       Validation
1267
1268       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
1272        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
1292   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
1299        $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
1304       To reset or clear all column binding, call "bind_columns" with the
1305       single argument "undef". This will also clear column names.
1306
1307        $csv->bind_columns (undef);
1308
1309       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
1312       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
1320   eof
1321        $eof = $csv->eof ();
1322
1323       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
1328       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
1332        while (my $row = $csv->getline ($fh)) {
1333            # ...
1334            }
1335        $csv->eof or $csv->error_diag;
1336
1337       will not report the error. You would have to change that to
1338
1339        while (my $row = $csv->getline ($fh)) {
1340            # ...
1341            }
1342        +$csv->error_diag and $csv->error_diag;
1343
1344   types
1345        $csv->types (\@tref);
1346
1347       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
1351        $csv->types ([Text::CSV_PP::IV (),
1352                      Text::CSV_PP::NV (),
1353                      Text::CSV_PP::NV (),
1354                      Text::CSV_PP::PV ()]);
1355
1356       Column types are used only for decoding columns while parsing,  in
1357       other words by the "parse" and "getline" methods.
1358
1359       You can unset column types by doing a
1360
1361        $csv->types (undef);
1362
1363       or fetch the current type settings with
1364
1365        $types = $csv->types ();
1366
1367       IV  Set field type to integer.
1368
1369       NV  Set field type to numeric/float.
1370
1371       PV  Set field type to string.
1372
1373   fields
1374        @columns = $csv->fields ();
1375
1376       This method returns the input to   "combine"  or the resultant
1377       decomposed fields of a successful "parse", whichever was called more
1378       recently.
1379
1380       Note that the return value is undefined after using "getline", which
1381       does not fill the data structures returned by "parse".
1382
1383   meta_info
1384        @flags = $csv->meta_info ();
1385
1386       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
1390       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
1394       " "0x0001
1395         The field was quoted.
1396
1397       " "0x0002
1398         The field was binary.
1399
1400       See the "is_***" methods below.
1401
1402   is_quoted
1403        my $quoted = $csv->is_quoted ($column_idx);
1404
1405       where  $column_idx is the  (zero-based)  index of the column in the
1406       last result of "parse".
1407
1408       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
1413       This method is only valid when "keep_meta_info" is set to a true value.
1414
1415   is_binary
1416        my $binary = $csv->is_binary ($column_idx);
1417
1418       where  $column_idx is the  (zero-based)  index of the column in the
1419       last result of "parse".
1420
1421       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
1424       This method is only valid when "keep_meta_info" is set to a true value.
1425
1426   is_missing
1427        my $missing = $csv->is_missing ($column_idx);
1428
1429       where  $column_idx is the  (zero-based)  index of the column in the
1430       last result of "getline_hr".
1431
1432        $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
1437       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
1444       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
1449       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
1454   status
1455        $status = $csv->status ();
1456
1457       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
1460       Note that as this only keeps track of the status of above mentioned
1461       methods, you are probably looking for "error_diag" instead.
1462
1463   error_input
1464        $bad_argument = $csv->error_input ();
1465
1466       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
1470       Depending on the type of error, it might also hold the data for the
1471       last error-input of "getline".
1472
1473   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
1480       If (and only if) an error occurred,  this function returns  the
1481       diagnostics of that error.
1482
1483       If called in void context,  this will print the internal error code and
1484       the associated error message to STDERR.
1485
1486       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
1497       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
1501       When called as a class method or a  direct function call,  the
1502       diagnostics are that of the last "new" call.
1503
1504   record_number
1505        $recno = $csv->record_number ();
1506
1507       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
1511   SetDiag
1512        $csv->SetDiag (0);
1513
1514       Use to reset the diagnostics if you are dealing with errors.
1515

FUNCTIONS

1517       This section is also taken from Text::CSV_XS.
1518
1519   csv
1520       This function is not exported by default and should be explicitly
1521       requested:
1522
1523        use Text::CSV_PP qw( csv );
1524
1525       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
1533        my $aoa = csv (in => "test.csv") or
1534            die Text::CSV_PP->error_diag;
1535
1536       This function takes the arguments as key-value pairs. This can be
1537       passed as a list or as an anonymous hash:
1538
1539        my $aoa = csv (  in => "test.csv", sep_char => ";");
1540        my $aoh = csv ({ in => $fh, headers => "auto" });
1541
1542       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
1546       If not overridden, the default option used for CSV is
1547
1548        auto_diag   => 1
1549        escape_null => 0
1550
1551       The option that is always set and cannot be altered is
1552
1553        binary      => 1
1554
1555       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
1559       Alternative invocations:
1560
1561        my $aoa = Text::CSV_PP::csv (in => "file.csv");
1562
1563        my $csv = Text::CSV_PP->new ();
1564        my $aoa = $csv->csv (in => "file.csv");
1565
1566       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
1569        my $csv = Text::CSV_PP->new ({ sep_char => ";" });
1570        my $aoh = $csv->csv (in => "file.csv", bom => 1);
1571
1572       will parse using ";" as "sep_char", not ",".
1573
1574       in
1575
1576       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
1582       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
1586        my $aoa = csv (in => "file.csv");
1587
1588        open my $fh, "<", "file.csv";
1589        my $aoa = csv (in => $fh);
1590
1591        my $csv = [ [qw( Foo Bar )], [ 1, 2 ], [ 2, 3 ]];
1592        my $err = csv (in => $csv, out => "file.csv");
1593
1594       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
1597        csv (in => "file.csv", filter => { 2 => sub { length > 2 }})
1598
1599       will be a shortcut to
1600
1601        csv (in => csv (in => "file.csv", filter => { 2 => sub { length > 2 }}))
1602
1603       where, in the absence of the "out" attribute, this is a shortcut to
1604
1605        csv (in  => csv (in => "file.csv", filter => { 2 => sub { length > 2 }}),
1606             out => *STDOUT)
1607
1608       out
1609
1610        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
1619        csv (in => $fh,  out => \@aoa);
1620        csv (in => $fh,  out => \@aoh, bom => 1);
1621        csv (in => $fh,  out => \%hsh, key => "key");
1622
1623       In output mode, the default CSV options when producing CSV are
1624
1625        eol       => "\r\n"
1626
1627       The "fragment" attribute is ignored in output mode.
1628
1629       "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
1634        csv (in => sub { $sth->fetch },            out => "dump.csv");
1635        csv (in => sub { $sth->fetchrow_hashref }, out => "dump.csv",
1636             headers => $sth->{NAME_lc});
1637
1638       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
1643       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
1647        my %cache;
1648        csv (in    => "dump.csv",
1649             out   => \"skip",
1650             on_in => sub { $cache{$_[1][1]}++ });
1651
1652       Currently,  setting "out" to any false value  ("undef", "", 0) will be
1653       equivalent to "\"skip"".
1654
1655       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
1662        my %hash;
1663        csv (in => $_, out => \%hash, key => "id") for sort glob "foo-[0-9]*.csv";
1664
1665        my @list; # List of arrays
1666        csv (in => $_, out => \@list)              for sort glob "foo-[0-9]*.csv";
1667
1668        my @list; # List of hashes
1669        csv (in => $_, out => \@list, bom => 1)    for sort glob "foo-[0-9]*.csv";
1670
1671       encoding
1672
1673       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
1678       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
1683       Encodings can be stacked, as supported by "binmode":
1684
1685        # 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
1692        # 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
1699       detect_bom
1700
1701       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
1705       "detect_bom" can be abbreviated to "bom".
1706
1707       This is the same as setting "encoding" to "auto".
1708
1709       Note that as the method  "header" is invoked,  its default is to also
1710       set the headers.
1711
1712       headers
1713
1714       If this attribute is not given, the default behavior is to produce an
1715       array of arrays.
1716
1717       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
1721       skip
1722         When "skip" is used, the header will not be included in the output.
1723
1724          my $aoa = csv (in => $fh, headers => "skip");
1725
1726       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
1730          my $aoh = csv (in => $fh, headers => "auto");
1731
1732       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
1737          my $aoh = csv (in => $fh, headers => "lc");
1738
1739       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
1744          my $aoh = csv (in => $fh, headers => "uc");
1745
1746       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
1752          my $aoh = csv (in      => $fh,
1753                         headers => sub { lc ($_[0]) =~ s/kode/code/gr });
1754
1755         this example is a variation of using "lc" where all occurrences of
1756         "kode" are replaced with "code".
1757
1758       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
1763          my $aoh = csv (in => $fh, headers => [qw( Foo Bar )]);
1764          csv (in => $aoa, out => $fh, headers => [qw( code description price )]);
1765
1766       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
1771          post-kode,city,name,id number,fubble
1772          1234AA,Duckstad,Donald,13,"X313DF"
1773
1774         using
1775
1776          csv (headers => { "post-kode" => "pc", "id number" => "ID" }, ...
1777
1778         will return an entry like
1779
1780          { pc     => "1234AA",
1781            city   => "Duckstad",
1782            name   => "Donald",
1783            ID     => "13",
1784            fubble => "X313DF",
1785            }
1786
1787       See also "munge_column_names" and "set_column_names".
1788
1789       munge_column_names
1790
1791       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
1795       "munge_column_names" can be abbreviated to "munge".
1796
1797       key
1798
1799       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
1804        my $ref = csv (in => "test.csv", key => "code");
1805        my $ref = csv (in => "test.csv", key => [ ":" => "code", "color" ]);
1806
1807       with test.csv like
1808
1809        code,product,price,color
1810        1,pc,850,gray
1811        2,keyboard,12,white
1812        3,mouse,5,black
1813
1814       the first example will return
1815
1816         { 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
1836       the second example will return
1837
1838         { "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
1858       The "key" attribute can be combined with "headers" for "CSV" date that
1859       has no header line, like
1860
1861        my $ref = csv (
1862            in      => "foo.csv",
1863            headers => [qw( c_foo foo bar description stock )],
1864            key     =>     "c_foo",
1865            );
1866
1867       value
1868
1869       Used to create key-value hashes.
1870
1871       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
1876        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
1885       with test.csv like
1886
1887        code,product,price,color
1888        1,pc,850,gray
1889        2,keyboard,12,white
1890        3,mouse,5,black
1891
1892       the first example will return
1893
1894         { 1 => 850,
1895           2 =>  12,
1896           3 =>   5,
1897           }
1898
1899       the second example will return
1900
1901         { 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
1915       the third example will return
1916
1917         { "1:gray"    => 850,
1918           "2:white"   =>  12,
1919           "3:black"   =>   5,
1920           }
1921
1922       the fourth example will return
1923
1924         { "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
1938       keep_headers
1939
1940       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
1943        my $aoh = csv (in => "file.csv", keep_headers => \my @hdr);
1944
1945       This attribute can be abbreviated to "kh" or passed as
1946       "keep_column_names".
1947
1948       This attribute implies a default of "auto" for the "headers" attribute.
1949
1950       fragment
1951
1952       Only output the fragment as defined in the "fragment" method. This
1953       option is ignored when generating "CSV". See "out".
1954
1955       Combining all of them could give something like
1956
1957        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
1967       sep_set
1968
1969       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
1972       "sep_set" can be abbreviated to "seps".
1973
1974       Note that as the  "header" method is invoked,  its default is to also
1975       set the headers.
1976
1977       set_column_names
1978
1979       If  "set_column_names" is passed,  the method "header" is invoked on
1980       the opened stream with all arguments meant for "header".
1981
1982       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
1985       With an input-file like
1986
1987        bAr,foo
1988        1,2
1989        3,4,5
1990
1991       This call
1992
1993        my $aoa = csv (in => $file, set_column_names => 0);
1994
1995       will result in
1996
1997        [[ "bar", "foo"     ],
1998         [ "1",   "2"       ],
1999         [ "3",   "4",  "5" ]]
2000
2001       and
2002
2003        my $aoa = csv (in => $file, set_column_names => 0, munge => "none");
2004
2005       will result in
2006
2007        [[ "bAr", "foo"     ],
2008         [ "1",   "2"       ],
2009         [ "3",   "4",  "5" ]]
2010
2011   Callbacks
2012       Callbacks enable actions triggered from the inside of Text::CSV_PP.
2013
2014       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
2018       error
2019          $csv->callbacks (error => sub { $csv->SetDiag (0) });
2020
2021         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
2025          my ($c, $s);
2026
2027          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
2038          $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
2044       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
2050         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
2055         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
2059          sub add_from_db {
2060              my ($csv, $row) = @_;
2061              $sth->execute ($row->[4]);
2062              push @$row, $sth->fetchrow_array;
2063              } # add_from_db
2064
2065          my $aoa = csv (in => "file.csv", callbacks => {
2066              after_parse => \&add_from_db });
2067
2068         This hook can be used for validation:
2069
2070         FAIL
2071           Die if any of the records does not validate a rule:
2072
2073            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
2078         DEFAULT
2079           Replace invalid fields with a default value:
2080
2081            after_parse => sub { $_[1][2] =~ m/^\d+$/ or $_[1][2] = 0 }
2082
2083         SKIP
2084           Skip records that have invalid fields (only applies to
2085           "getline_all"):
2086
2087            after_parse => sub { $_[1][0] =~ m/^\d+$/ or return \"skip"; }
2088
2089       before_print
2090          my $idx = 1;
2091          $csv->callbacks (before_print => sub { $_[1][0] = $idx++ });
2092          $csv->print (*STDOUT, [ 0, $_ ]) for @members;
2093
2094         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
2099         The return code of the callback is ignored.
2100
2101          sub max_4_fields {
2102              my ($csv, $row) = @_;
2103              @$row > 4 and splice @$row, 4;
2104              } # max_4_fields
2105
2106          csv (in => csv (in => "file.csv"), out => *STDOUT,
2107              callbacks => { before_print => \&max_4_fields });
2108
2109         This callback is not active for "combine".
2110
2111       Callbacks for csv ()
2112
2113       The "csv" allows for some callbacks that do not integrate in XS
2114       internals but only feature the "csv" function.
2115
2116         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
2125         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
2134       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
2138         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
2142            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
2147            csv (in => "file.csv", filter => { foo => sub { $_ > 4 }});
2148
2149           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
2155           All sub results should match, as in AND.
2156
2157           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
2161            filter => { 3 => sub { $_ > 100 ? $_[1][1] =~ m/A/ : $_[1][6] =~ m/B/ }}
2162
2163           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
2167            filter => { 3 => sub { $_ > 100 && $_{foo} =~ m/A/ && $_{bar} < 1000  }}
2168
2169           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
2173            filter => { 2 => sub { $_ = uc }}
2174
2175           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
2178            filter => { 2 => sub { $_ = uc; 1 }}
2179
2180         coderef
2181            csv (in => "file.csv", filter => sub { $n++; 0; });
2182
2183           If the argument to "filter" is a coderef,  it is an alias or
2184           shortcut to a filter on column 0:
2185
2186            csv (filter => sub { $n++; 0 });
2187
2188           is equal to
2189
2190            csv (filter => { 0 => sub { $n++; 0 });
2191
2192         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
2197           These are predefined filters
2198
2199           Given a file like (line numbers prefixed for doc purpose only):
2200
2201            1:1,2,3
2202            2:
2203            3:,
2204            4:""
2205            5:,,
2206            6:, ,
2207            7:"",
2208            8:" "
2209            9:4,5,6
2210
2211           not_blank
2212             Filter out the blank lines
2213
2214             This filter is a shortcut for
2215
2216              filter => { 0 => sub { @{$_[1]} > 1 or
2217                          defined $_[1][0] && $_[1][0] ne "" } }
2218
2219             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
2223             With the given example, lines 2 and 4 will be skipped.
2224
2225           not_empty
2226             Filter out lines where all the fields are empty.
2227
2228             This filter is a shortcut for
2229
2230              filter => { 0 => sub { grep { defined && $_ ne "" } @{$_[1]} } }
2231
2232             A space is not regarded being empty, so given the example data,
2233             lines 2, 3, 4, 5, and 7 are skipped.
2234
2235           filled
2236             Filter out lines that have no visible data
2237
2238             This filter is a shortcut for
2239
2240              filter => { 0 => sub { grep { defined && m/\S/ } @{$_[1]} } }
2241
2242             This filter rejects all lines that not have at least one field
2243             that does not evaluate to the empty string.
2244
2245             With the given example data, this filter would skip lines 2
2246             through 8.
2247
2248         One could also use modules like Types::Standard:
2249
2250          use Types::Standard -types;
2251
2252          my $type   = Tuple[Str, Str, Int, Bool, Optional[Num]];
2253          my $check  = $type->compiled_check;
2254
2255          # 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
2267       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
2274         This callback can also be passed as  an attribute without the
2275         "callbacks" wrapper.
2276
2277       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
2284         This callback can also be passed as an attribute  without the
2285         "callbacks" wrapper.
2286
2287         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
2290       on_in
2291         This callback acts exactly as the "after_in" or the "before_out"
2292         hooks.
2293
2294         This callback can also be passed as an attribute  without the
2295         "callbacks" wrapper.
2296
2297         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
2301           my $aoh = csv (
2302               in      => \"foo\n1\n2\n",
2303               headers => "auto",
2304               on_in   => sub { $_{bar} = 2; },
2305               );
2306
2307         $aoh will be:
2308
2309           [ { foo => 1,
2310               bar => 2,
2311               }
2312             { foo => 2,
2313               bar => 2,
2314               }
2315             ]
2316
2317       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
2324          my $csv = Text::CSV_PP->new ({ binary => 1, auto_diag => 1 });
2325
2326          my $aoa = $csv->csv (in => $fh);
2327          my $aoa = csv (in => $fh, csv => $csv);
2328
2329         both act the same. Running this 20000 times on a 20 lines CSV file,
2330         showed a 53% speedup.
2331

DIAGNOSTICS

2333       This section is also taken from Text::CSV_XS.
2334
2335       Still under construction ...
2336
2337       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
2343       If the constructor failed, the cause can be found using "error_diag" as
2344       a class method, like "Text::CSV_PP->error_diag".
2345
2346       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
2352       Errors can be (individually) caught using the "error" callback.
2353
2354       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
2359       • INI
2360
2361         Initialization error or option conflict.
2362
2363       • ECR
2364
2365         Carriage-Return related parse error.
2366
2367       • EOF
2368
2369         End-Of-File related parse error.
2370
2371       • EIQ
2372
2373         Parse error inside quotation.
2374
2375       • EIF
2376
2377         Parse error inside field.
2378
2379       • ECB
2380
2381         Combine error.
2382
2383       • EHR
2384
2385         HashRef parse related error.
2386
2387       And below should be the complete list of error codes that can be
2388       returned:
2389
2390       • 1001 "INI - sep_char is equal to quote_char or escape_char"
2391
2392         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
2396       • 1002 "INI - allow_whitespace with escape_char or quote_char SP or
2397         TAB"
2398
2399         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
2403       • 1003 "INI - \r or \n in main attr not allowed"
2404
2405         Using default "eol" characters in either "sep_char", "quote_char",
2406         or  "escape_char"  is  not allowed.
2407
2408       • 1004 "INI - callbacks should be undef or a hashref"
2409
2410         The "callbacks"  attribute only allows one to be "undef" or a hash
2411         reference.
2412
2413       • 1005 "INI - EOL too long"
2414
2415         The value passed for EOL is exceeding its maximum length (16).
2416
2417       • 1006 "INI - SEP too long"
2418
2419         The value passed for SEP is exceeding its maximum length (16).
2420
2421       • 1007 "INI - QUOTE too long"
2422
2423         The value passed for QUOTE is exceeding its maximum length (16).
2424
2425       • 1008 "INI - SEP undefined"
2426
2427         The value passed for SEP should be defined and not empty.
2428
2429       • 1010 "INI - the header is empty"
2430
2431         The header line parsed in the "header" is empty.
2432
2433       • 1011 "INI - the header contains more than one valid separator"
2434
2435         The header line parsed in the  "header"  contains more than one
2436         (unique) separator character out of the allowed set of separators.
2437
2438       • 1012 "INI - the header contains an empty field"
2439
2440         The header line parsed in the "header" contains an empty field.
2441
2442       • 1013 "INI - the header contains nun-unique fields"
2443
2444         The header line parsed in the  "header"  contains at least  two
2445         identical fields.
2446
2447       • 1014 "INI - header called on undefined stream"
2448
2449         The header line cannot be parsed from an undefined source.
2450
2451       • 1500 "PRM - Invalid/unsupported argument(s)"
2452
2453         Function or method called with invalid argument(s) or parameter(s).
2454
2455       • 1501 "PRM - The key attribute is passed as an unsupported type"
2456
2457         The "key" attribute is of an unsupported type.
2458
2459       • 1502 "PRM - The value attribute is passed without the key attribute"
2460
2461         The "value" attribute is only allowed when a valid key is given.
2462
2463       • 1503 "PRM - The value attribute is passed as an unsupported type"
2464
2465         The "value" attribute is of an unsupported type.
2466
2467       • 2010 "ECR - QUO char inside quotes followed by CR not part of EOL"
2468
2469         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
2474       • 2011 "ECR - Characters after end of quoted field"
2475
2476         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
2480       • 2012 "EOF - End of data in parsing input stream"
2481
2482         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
2487       • 2013 "INI - Specification error for fragments RFC7111"
2488
2489         Invalid specification for URI "fragment" specification.
2490
2491       • 2014 "ENF - Inconsistent number of fields"
2492
2493         Inconsistent number of fields under strict parsing.
2494
2495       • 2021 "EIQ - NL char inside quotes, binary off"
2496
2497         Sequences like "1,"foo\nbar",22,1" are allowed only when the binary
2498         option has been selected with the constructor.
2499
2500       • 2022 "EIQ - CR char inside quotes, binary off"
2501
2502         Sequences like "1,"foo\rbar",22,1" are allowed only when the binary
2503         option has been selected with the constructor.
2504
2505       • 2023 "EIQ - QUO character not allowed"
2506
2507         Sequences like ""foo "bar" baz",qu" and "2023,",2008-04-05,"Foo,
2508         Bar",\n" will cause this error.
2509
2510       • 2024 "EIQ - EOF cannot be escaped, not even inside quotes"
2511
2512         The escape character is not allowed as last character in an input
2513         stream.
2514
2515       • 2025 "EIQ - Loose unescaped escape"
2516
2517         An escape character should escape only characters that need escaping.
2518
2519         Allowing  the escape  for other characters  is possible  with the
2520         attribute "allow_loose_escapes".
2521
2522       • 2026 "EIQ - Binary character inside quoted field, binary off"
2523
2524         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
2529       • 2027 "EIQ - Quoted field not terminated"
2530
2531         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
2536       • 2030 "EIF - NL char inside unquoted verbatim, binary off"
2537
2538       • 2031 "EIF - CR char is first char of field, not part of EOL"
2539
2540       • 2032 "EIF - CR char inside unquoted, not part of EOL"
2541
2542       • 2034 "EIF - Loose unescaped quote"
2543
2544       • 2035 "EIF - Escaped EOF in unquoted field"
2545
2546       • 2036 "EIF - ESC error"
2547
2548       • 2037 "EIF - Binary character in unquoted field, binary off"
2549
2550       • 2110 "ECB - Binary character in Combine, binary off"
2551
2552       • 2200 "EIO - print to IO failed. See errno"
2553
2554       • 3001 "EHR - Unsupported syntax for column_names ()"
2555
2556       • 3002 "EHR - getline_hr () called before column_names ()"
2557
2558       • 3003 "EHR - bind_columns () and column_names () fields count
2559         mismatch"
2560
2561       • 3004 "EHR - bind_columns () only accepts refs to scalars"
2562
2563       • 3006 "EHR - bind_columns () did not pass enough refs for parsed
2564         fields"
2565
2566       • 3007 "EHR - bind_columns needs refs to writable scalars"
2567
2568       • 3008 "EHR - unexpected error in bound fields"
2569
2570       • 3009 "EHR - print_hr () called before column_names ()"
2571
2572       • 3010 "EHR - print_hr () called with invalid arguments"
2573

SEE ALSO

2575       Text::CSV_XS, Text::CSV
2576
2577       Older versions took many regexp from
2578       <http://www.din.or.jp/~ohzaki/perl.htm>
2579

AUTHOR

2581       Kenichi Ishigaki, <ishigaki[at]cpan.org> Makamaka Hannyaharamitu,
2582       <makamaka[at]cpan.org>
2583
2584       Text::CSV_XS was written by <joe[at]ispsoft.de> and maintained by
2585       <h.m.brand[at]xs4all.nl>.
2586
2587       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
2593       Most of the code and doc is directly taken from the pure perl part of
2594       Text::CSV_XS.
2595
2596       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
2600       This library is free software; you can redistribute it and/or modify it
2601       under the same terms as Perl itself.
2602
2603
2604
2605perl v5.34.0                      2021-07-23                   Text::CSV_PP(3)
Impressum