-
Notifications
You must be signed in to change notification settings - Fork 11
/
Copy pathText-CSV.html
2835 lines (1870 loc) · 107 KB
/
Text-CSV.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title></title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:[email protected]" />
</head>
<body>
<ul id="index">
<li><a href="#DISCLAIMER">DISCLAIMER</a></li>
<li><a href="#NAME">NAME</a></li>
<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#DESCRIPTION">DESCRIPTION</a>
<ul>
<li><a href="#Embedded-newlines">Embedded newlines</a></li>
<li><a href="#Binary-data">Binary data</a></li>
</ul>
</li>
<li><a href="#SPECIFICATION">SPECIFICATION</a></li>
<li><a href="#METHODS">METHODS</a>
<ul>
<li><a href="#version">version </a></li>
<li><a href="#new">new </a></li>
<li><a href="#print">print </a></li>
<li><a href="#say">say </a></li>
<li><a href="#combine">combine </a></li>
<li><a href="#string">string </a></li>
<li><a href="#getline">getline </a></li>
<li><a href="#getline_all-head2-getline-all">getline_all =head2 getline-all </a></li>
<li><a href="#getline_hr-head2-getline-hr">getline_hr =head2 getline-hr </a></li>
<li><a href="#getline_hr_all-head2-getline-hr-all">getline_hr_all =head2 getline-hr-all </a></li>
<li><a href="#parse">parse </a></li>
<li><a href="#fragment">fragment </a></li>
<li><a href="#colrange">colrange </a></li>
<li><a href="#rowrange">rowrange </a></li>
<li><a href="#column_names-head2-column-names">column_names =head2 column-names </a></li>
<li><a href="#header">header</a>
<ul>
<li><a href="#return-value">return value</a></li>
<li><a href="#Options">Options</a></li>
</ul>
</li>
<li><a href="#bind_columns-head2-bind-columns">bind_columns =head2 bind-columns </a></li>
<li><a href="#eof">eof </a></li>
<li><a href="#types1">types </a></li>
<li><a href="#row1">row </a></li>
<li><a href="#fields">fields </a></li>
<li><a href="#strings">strings </a></li>
<li><a href="#meta_info">meta_info </a></li>
<li><a href="#meta-info">meta-info </a></li>
<li><a href="#is_quoted">is_quoted </a></li>
<li><a href="#is-quoted">is-quoted </a></li>
<li><a href="#is_binary">is_binary </a></li>
<li><a href="#is-binary">is-binary </a></li>
<li><a href="#is_missing">is_missing </a></li>
<li><a href="#is-missing">is-missing </a></li>
<li><a href="#status">status </a></li>
<li><a href="#error_input">error_input </a></li>
<li><a href="#error-input">error-input </a></li>
</ul>
</li>
<li><a href="#DIAGNOSTICS">DIAGNOSTICS</a>
<ul>
<li><a href="#CSV::Diag">CSV::Diag</a></li>
<li><a href="#error_diag">error_diag </a></li>
<li><a href="#error-diag">error-diag </a></li>
<li><a href="#record_number">record_number </a></li>
<li><a href="#set_diag">set_diag </a></li>
</ul>
</li>
<li><a href="#CSV::Field">CSV::Field</a>
<ul>
<li><a href="#new1">new</a></li>
<li><a href="#Bool">Bool</a></li>
<li><a href="#text-head2-Str">text =head2 Str</a></li>
<li><a href="#Buf">Buf</a></li>
<li><a href="#Numeric">Numeric</a></li>
<li><a href="#gist">gist</a></li>
<li><a href="#add">add</a></li>
<li><a href="#set_quoted">set_quoted</a></li>
<li><a href="#is_quoted1">is_quoted</a></li>
<li><a href="#undefined">undefined</a></li>
<li><a href="#is_binary1">is_binary</a></li>
<li><a href="#is_utf8">is_utf8</a></li>
<li><a href="#is_missing1">is_missing</a></li>
</ul>
</li>
<li><a href="#CSV::Row">CSV::Row </a>
<ul>
<li><a href="#methods">methods</a></li>
</ul>
</li>
<li><a href="#FUNCTIONS">FUNCTIONS</a>
<ul>
<li><a href="#csv1">csv </a>
<ul>
<li><a href="#in">in </a></li>
<li><a href="#out">out </a></li>
<li><a href="#encoding">encoding </a></li>
<li><a href="#detect-bom">detect-bom </a></li>
<li><a href="#headers">headers </a></li>
<li><a href="#munge-column-names1">munge-column-names </a></li>
<li><a href="#key">key </a></li>
<li><a href="#fragment1">fragment </a></li>
<li><a href="#sep-set1">sep-set </a></li>
<li><a href="#set_column_names">set_column_names </a></li>
</ul>
</li>
<li><a href="#Callbacks">Callbacks</a>
<ul>
<li><a href="#Callbacks-for-csv">Callbacks for csv</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#EXAMPLES">EXAMPLES</a>
<ul>
<li><a href="#Reading-a-CSV-file-line-by-line">Reading a CSV file line by line:</a>
<ul>
<li><a href="#Reading-only-a-single-column">Reading only a single column</a></li>
</ul>
</li>
<li><a href="#Parsing-CSV-strings">Parsing CSV strings:</a></li>
<li><a href="#Printing-CSV-data">Printing CSV data</a>
<ul>
<li><a href="#The-fast-way:-using-print">The fast way: using "print"</a></li>
<li><a href="#The-slow-way:-using-combine-and-string">The slow way: using "combine" and "string"</a></li>
</ul>
</li>
<li><a href="#Rewriting-CSV">Rewriting CSV</a></li>
<li><a href="#Dumping-database-tables-to-CSV">Dumping database tables to CSV</a></li>
<li><a href="#The-examples-folder">The examples folder</a></li>
</ul>
</li>
<li><a href="#CAVEATS">CAVEATS</a>
<ul>
<li><a href="#Microsoft-Excel">Microsoft Excel</a></li>
</ul>
</li>
<li><a href="#TODO-WIP-NYI">TODO / WIP / NYI</a></li>
<li><a href="#DIAGNOSTICS1">DIAGNOSTICS</a></li>
<li><a href="#SEE-ALSO">SEE ALSO</a></li>
<li><a href="#AUTHOR">AUTHOR</a></li>
<li><a href="#COPYRIGHT-AND-LICENSE">COPYRIGHT AND LICENSE</a></li>
</ul>
<h1 id="DISCLAIMER">DISCLAIMER</h1>
<p>Note that updating these docs is an ongoing process and some perl5 idioms might not have been translated yet into correct raku idiom. My bad. Sorry. (Feedback welcome)</p>
<h1 id="NAME">NAME</h1>
<p>Text::CSV - comma-separated values manipulation routines</p>
<h1 id="SYNOPSIS">SYNOPSIS</h1>
<pre><code>use Text::CSV;
# Read whole file in memory
my @aoa = csv(in => "data.csv"); # as array of arrays
my @aoh = csv(in => "data.csv",
headers => "auto"); # as array of hashes
# Write array of arrays as csv file
csv(in => @aoa, out => "file.csv", sep => ";");
my @rows;
# Read/parse CSV
my $csv = Text::CSV.new;
my $fh = open "test.csv", :r, :!chomp;
while (my @row = $csv.getline($fh)) {
@row[2] ~~ m/pattern/ or next; # 3rd field should match
@rows.push: @row;
}
$fh.close;
# and write as CSV
$fh = open "new.csv", :w;
$csv.say($fh, $_) for @rows;
$fh.close;</code></pre>
<h1 id="DESCRIPTION">DESCRIPTION</h1>
<p>Text::CSV provides facilities for the composition and decomposition of comma-separated values. An instance of the Text::CSV class will combine fields into a <code>CSV</code> string and parse a <code>CSV</code> string into fields.</p>
<p>The module accepts either strings or files as input and support the use of user-specified characters (or sequences thereof) for delimiters, separators, and escapes.</p>
<p>In all following documentation, <code>WIP</code> stands for "Work In Progress" and <code>NYI</code> for "Not Yet Implemented". The goal is to get rid of all of those.</p>
<h2 id="Embedded-newlines">Embedded newlines</h2>
<p><b>Important Note</b>: The default behavior is to accept only UTF-8 characters.</p>
<p>But you still have the problem that you have to pass a correct line to the <a href="#parse">"parse"</a> method, which is more complicated from the usual point of usage:</p>
<pre><code>my $csv = Text::CSV.new;
for lines() : eager { # WRONG!
$csv.parse($_);
my @fields = $csv.fields;
}</code></pre>
<p>this will break for several reasons. The default open mode is to <code>chomp</code> lines, which will also remove the newline sequence if that sequence is not (part of) the newline at all. As the <code>for</code> might read broken lines: it does not care about the quoting. If you need to support embedded newlines, the way to go is to <b>not</b> pass <a href="#eol"><code>eol</code></a> in the parser (it accepts <code>\n</code>, <code>\r</code>, <b>and</b> <code>\r\n</code> by default) and then</p>
<pre><code>my $csv = Text::CSV.new;
my $io = open $file, :r, :!chomp;
while (my $row = $csv.getline($io)) {
my @fields = @$row;
}</code></pre>
<h2 id="Binary-data">Binary data</h2>
<p>For now, Text::CSV only accepts Unicode. Binary data is planned.</p>
<h1 id="SPECIFICATION">SPECIFICATION</h1>
<p>While no formal specification for CSV exists, <a href="https://datatracker.ietf.org/doc/html/rfc4180">RFC 4180</a> (<i>1</i>) describes the common format and establishes <code>text/csv</code> as the MIME type registered with the IANA. <a href="https://datatracker.ietf.org/doc/html/rfc7111">RFC 7111</a> (<i>2</i>) adds fragments to CSV.</p>
<p>Many informal documents exist that describe the <code>CSV</code> format. <a>"How To: The Comma Separated Value (CSV) File Format"</a> (<i>3</i>) provides an overview of the <code>CSV</code> format in the most widely used applications and explains how it can best be used and supported.</p>
<pre><code>1) https://datatracker.ietf.org/doc/html/rfc4180
2) https://datatracker.ietf.org/doc/html/rfc7111
3) http://creativyst.com/Doc/Articles/CSV/CSV01.shtml</code></pre>
<p>The basic rules are as follows:</p>
<p><b>CSV</b> is a delimited data format that has fields/columns separated by the comma character and records/rows separated by newlines. Fields that contain a special character (comma, newline, or double quote), must be enclosed in double quotes. However, if a line contains a single entry that is the empty string, it may be enclosed in double quotes. If a field's value contains a double quote character it is escaped by placing another double quote character next to it. The <code>CSV</code> file format does not require a specific character encoding, byte order, or line terminator format.</p>
<ul>
<li><p>Each record is a single line ended by a line feed (ASCII/<code>LF</code>=<code>0x0A</code>) or a carriage return and line feed pair (ASCII/<code>CRLF</code>=<code>0x0D 0x0A</code>), however, line-breaks may be embedded.</p>
</li>
<li><p>Fields are separated by commas.</p>
</li>
<li><p>Allowable characters within a <code>CSV</code> field include <code>0x09</code> (<code>TAB</code>) and the inclusive range of <code>0x20</code> (space) through <code>0x7E</code> (tilde). In binary mode all characters are accepted, at least in quoted fields.</p>
</li>
<li><p>A field within <code>CSV</code> must be surrounded by double-quotes to contain a separator character (comma).</p>
</li>
</ul>
<p>Though this is the most clear and restrictive definition, Text::CSV is way more liberal than this, and allows extension:</p>
<ul>
<li><p>Line termination by a single carriage return is accepted by default</p>
</li>
<li><p>The separation, escape, and escape can be any valid Unicode sequence.</p>
</li>
<li><p>A field in <code>CSV</code> must be surrounded by double-quotes to make an embedded double-quote, represented by a pair of consecutive double-quotes, valid. You may additionally use the sequence <code>"0</code> for representation of a NULL byte. Using <code>0x00</code> is just as valid.</p>
</li>
<li><p>Several violations of the above specification may be lifted by passing some options as attributes to the object constructor.</p>
</li>
</ul>
<h1 id="METHODS">METHODS</h1>
<h2 id="version">version </h2>
<p>Returns the current module version.</p>
<h2 id="new">new </h2>
<p>Returns a new instance of class Text::CSV. The attributes are described by the optional named parameters</p>
<pre><code>my $csv = Text::CSV.new(attributes ...);</code></pre>
<p>The following attributes are available:</p>
<dl>
<dt id="eol">eol </dt>
<dd>
<pre><code>my $csv = Text::CSV.new(eol => "\r\n");
$csv.eol(Str);
my $eol = $csv.eol;</code></pre>
<p>The end-of-line string to add to rows for <a href="#print">"print"</a> or the record separator for <a href="#getline">"getline"</a>.</p>
<p>When not set in a <b>parser</b> instance, the default behavior is to accept <code>\n</code>, <code>\r</code>, and <code>\r\n</code>, so it is probably safer to not specify <code>eol</code> at all. Passing <code>Str</code> or the empty string behave the same.</p>
<p>As raku interprets <code>\r\n</code> as a single grapheme in input, it is dissuaded to use <code>\r\n</code> as <code>eol</code> when parsing. Please choose <code>Str</code> instead.</p>
<p>When not passed in a <b>generating</b> instance, records are not terminated at all, so it is probably wise to pass something you expect. A safe choice for <code>eol</code> on output is either <code>\n</code> or <code>\r\n</code>.</p>
<p>Common values for <code>eol</code> are <code>"\012"</code> (<code>\n</code> or Line Feed), <code>"\015\012"</code> (<code>\r\n</code> or Carriage Return, Line Feed), and <code>"\015"</code> (<code>\r</code> or Carriage Return).</p>
</dd>
<dt id="sep">sep </dt>
<dd>
</dd>
<dt id="sep_char">sep_char </dt>
<dd>
</dd>
<dt id="sep-char">sep-char </dt>
<dd>
</dd>
<dt id="separator">separator </dt>
<dd>
<pre><code>my $csv = Text::CSV.new(sep => ";");
$csv.sep("\x[ff0c]"); # FULLWIDTH COMMA
my $sep = $csv.sep;</code></pre>
<p>The sequence used to separate fields, by default a comma: (<code>,</code>). This sequence is required and cannot be disabled.</p>
<p>The separation sequence can not be equal to the quote sequence, the escape sequence or the newline sequence.</p>
<p>See also <a href="#CAVEATS">"CAVEATS"</a></p>
</dd>
<dt id="quote">quote </dt>
<dd>
</dd>
<dt id="quote_char">quote_char </dt>
<dd>
</dd>
<dt id="quote-char">quote-char </dt>
<dd>
<pre><code>my $csv = Text::CSV.new(quote => "'");
$csv.quote("\x[ff02]); # FULLWIDTH QUOTATION MARK
$csv.quote(Str);
my $quo = $csv.quote;</code></pre>
<p>The sequence to quote fields containing blanks or binary data, by default the double quote character (<code>"</code>). A value of <code>Str</code> disables quotation (for simple cases only).</p>
<p>The quotation sequence can not be equal to the separation sequence or the newline sequence.</p>
<p>See also <a href="#CAVEATS">"CAVEATS"</a></p>
</dd>
<dt id="escape">escape </dt>
<dd>
</dd>
<dt id="escape_char">escape_char </dt>
<dd>
</dd>
<dt id="escape-char">escape-char </dt>
<dd>
<pre><code>my $csv = Text::CSV.new(escape => "\\");
$csv.escape("\x[241b]"); # SYMBOL FOR ESCAPE
$csv.escape(Str);
my $esc = $csv.escape;</code></pre>
<p>The sequence to escape certain characters inside quoted fields.</p>
<p>The <code>escape</code> defaults to being the double-quote mark (<code>"</code>). In other words the same as the default sequence for <a href="#quote"><code>quote</code></a>. This means that doubling the quote mark in a field escapes it:</p>
<pre><code>"foo","bar","Escape ""quote mark"" with two ""quote marks""","baz"</code></pre>
<p>If you change <a href="#quote"><code>quote</code></a> without changing <code>escape</code>, <code>escape</code> will still be the double-quote (<code>"</code>). If instead you want to escape <a href="#quote"><code>quote</code></a> by doubling it you will need to also change <code>escape</code> to be the same as what you have changed <a href="#quote"><code>quote</code></a> to.</p>
<p>The escape sequence can not be equal to the separation sequence.</p>
</dd>
<dt id="binary">binary </dt>
<dd>
<p>WIP: Default is True. Non-UTF-8 real binary (Blob) does not yet parse. Opening the resource with encoding utf8-c8 is most likely the way to go.</p>
<pre><code>my $csv = Text::CSV.new(:binary);
$csv.binary(False);
my $bin = $csv.binary;</code></pre>
<p>If this attribute is <code>True</code>, you may use binary data in quoted fields, including line feeds, carriage returns and <code>NULL</code> bytes. (The latter could be escaped as <code>"0</code>.) By default this feature is on.</p>
<p>Note that valid Unicode (UTF-8) is not considered binary.</p>
</dd>
<dt id="strict">strict </dt>
<dd>
<pre><code>my $csv = Text::CSV.new(:strict);
$csv.strict(False);
my $flg = $csv.strict;</code></pre>
<p>If set to True, any row that parses to a different number of columns than the previous row will cause the parser to throw error 2014.</p>
</dd>
<dt id="formula-handling">formula-handling </dt>
<dd>
</dd>
<dt id="formula_handling">formula_handling </dt>
<dd>
</dd>
<dt id="formula">formula </dt>
<dd>
<pre><code>my $csv = Text::CSV.new(formula => "none");
$csv.formula("none");
my $f = $csv.formula;</code></pre>
<p>This defines the behavior of fields containing <i>formulas</i>. As formulas are considered dangerous in spreadsheets, this attribute can define an optional action to be taken if a field starts with an equal sign (<code>=</code>).</p>
<p>For purpose of code-readability, this can also be written as</p>
<pre><code>my $csv = Text::CSV_XS.new(formula-handling => "none"});
$csv.formula-handling("none");
my $f = $csv.formula-handling;</code></pre>
<p>or</p>
<pre><code>my $csv = Text::CSV_XS.new(formula_handling => "none"});
$csv.formula_handling("none");
my $f = $csv.formula_handling;</code></pre>
<p>Possible values for this attribute are</p>
<dl>
<dt id="none">none</dt>
<dd>
<p>Take no specific action. This is the default.</p>
<pre><code>$csv.formula("none");</code></pre>
</dd>
<dt id="die">die</dt>
<dd>
<p>Cause the process to <code>die</code> whenever a leading <code>=</code> is encountered.</p>
<pre><code>$csv.formula("die");</code></pre>
</dd>
<dt id="croak">croak</dt>
<dd>
<p>Cause the process to <code>die</code> whenever a leading <code>=</code> is encountered.</p>
<pre><code>$csv.formula("croak");</code></pre>
<p>This option just exists for perl5 compatibility.</p>
</dd>
<dt id="diag">diag</dt>
<dd>
<p>Report position and content of the field whenever a leading <code>=</code> is found. The value of the field is unchanged.</p>
<pre><code>$csv.formula("diag");</code></pre>
</dd>
<dt id="empty">empty</dt>
<dd>
<p>Replace the content of fields that start with a <code>=</code> with the empty string.</p>
<pre><code>$csv.formula("empty");
$csv.formula("");</code></pre>
</dd>
<dt id="undef">undef</dt>
<dd>
<p>Replace the content of fields that start with a <code>=</code> with <code>Str</code>.</p>
<pre><code>$csv.formula("undef");
$csv.formula(Str);</code></pre>
</dd>
</dl>
<p>All other values will throw an exception with error code 1500.</p>
</dd>
<dt id="auto_diag">auto_diag </dt>
<dd>
</dd>
<dt id="auto-diag">auto-diag </dt>
<dd>
<pre><code>my $csv = Text::CSV.new(auto_diag => False);
$csv.auto_diag(True);
my $a-d = $csv.auto_diag;</code></pre>
<p>Set this attribute to a number between <code>1</code> and <code>9</code> causes <a href="#error_diag">"error_diag"</a> to be automatically called in void context upon errors. The value <code>True</code> evaluates to <code>1</code>.</p>
<p>In case of error <code>2012 - EOF</code>, this call will be void.</p>
<p>If <code>auto_diag</code> is set to a numeric value greater than <code>1</code>, it will <code>die</code> on errors instead of <code>warn</code>.</p>
</dd>
<dt id="diag_verbose">diag_verbose </dt>
<dd>
</dd>
<dt id="diag-verbose">diag-verbose </dt>
<dd>
<pre><code>my $csv = Text::CSV.new(diag_verbose => 1);
$csv.diag_verbose(2);
my $d-v = $csv.diag_verbose;</code></pre>
<p>Set the verbosity of the output triggered by <code>auto_diag</code>.</p>
<p>WIP: Does not add any information yet.</p>
</dd>
<dt id="blank_is_undef">blank_is_undef </dt>
<dd>
</dd>
<dt id="blank-is-undef">blank-is-undef </dt>
<dd>
<pre><code>my $csv = Text::CSV.new(:blank_is_undef);
$csv.blank_is_undef(False);
my $biu = $csv.blank_is_undef;</code></pre>
<p>Under normal circumstances, <code>CSV</code> data makes no distinction between quoted- and unquoted empty fields. These both end up in an empty string field once read, thus</p>
<pre><code>1,"",," ",2</code></pre>
<p>is read as</p>
<pre><code>[ "1", "", "", " ", "2" ]</code></pre>
<p>When <i>writing</i> <code>CSV</code> files with <a href="#always_quote"><code>always_quote</code></a> set, the unquoted <i>empty</i> field is the result of an undefined value. To enable this distinction when <i>reading</i> <code>CSV</code> data, the <code>blank_is_undef</code> attribute will cause unquoted empty fields to be set to <code>Str</code>, causing the above to be parsed as</p>
<pre><code>[ "1", "", Str, " ", "2" ]</code></pre>
</dd>
<dt id="empty_is_undef">empty_is_undef </dt>
<dd>
</dd>
<dt id="empty-is-undef">empty-is-undef </dt>
<dd>
<pre><code>my $csv = Text::CSV.new(:empty_is_undef);
$csv.empty_is_undef(False);
my $eiu = $csv.empty_is_undef;</code></pre>
<p>Going one step further than <a href="#blank_is_undef"><code>blank_is_undef</code></a>, this attribute causes all empty fields to return as <code>Str</code>, so</p>
<pre><code>1,"",," ",2</code></pre>
<p>is read as</p>
<pre><code>[ 1, Str, Str, " ", 2 ]</code></pre>
<p>Note that this effects only fields that are originally empty, not fields that are empty after stripping allowed whitespace. YMMV.</p>
</dd>
<dt id="allow_whitespace">allow_whitespace </dt>
<dd>
</dd>
<dt id="allow-whitespace">allow-whitespace </dt>
<dd>
<pre><code>my $csv = Text::CSV.new(:allow_whitespace);
$csv.allow_whitespace(False);
my $a-w = $csv.allow_whitespace;</code></pre>
<p>When this option is set to <code>True</code>, the whitespace (<code>TAB</code>'s and <code>SPACE</code>'s) surrounding the separation sequence is removed when parsing. If either <code>TAB</code> or <code>SPACE</code> is one of the three major sequences <a href="#sep"><code>sep</code></a>, <a href="#quote"><code>quote</code></a>, or <a href="#escape"><code>escape</code></a> it will not be considered whitespace.</p>
<p>Now lines like:</p>
<pre><code>1 , "foo" , bar , 3 , zapp</code></pre>
<p>are parsed as valid <code>CSV</code>, even though it violates the <code>CSV</code> specs.</p>
<p>Note that <b>all</b> whitespace is stripped from both start and end of each field. That would make it <i>more</i> than a <i>feature</i> to enable parsing bad <code>CSV</code> lines, as</p>
<pre><code>1, 2.0, 3, ape , monkey</code></pre>
<p>will now be parsed as</p>
<pre><code>[ "1", "2.0", "3", "ape", "monkey" ]</code></pre>
<p>even if the original line was perfectly acceptable <code>CSV</code>.</p>
</dd>
<dt id="allow_loose_quotes">allow_loose_quotes </dt>
<dd>
</dd>
<dt id="allow-loose-quotes">allow-loose-quotes </dt>
<dd>
<pre><code>my $csv = Text::CSV.new(:allow_loose_quotes);
$csv.allow_loose_quotes(False);
my $alq = $csv.allow_loose_quotes;</code></pre>
<p>By default, parsing unquoted fields containing <a href="#quote"><code>quote</code></a>'s like</p>
<pre><code>1,foo "bar" baz,42</code></pre>
<p>would result in parse error 2034. Though it is still bad practice to allow this format, we cannot help the fact that some vendors make their applications spit out lines styled this way.</p>
<p>If there is <b>really</b> bad <code>CSV</code> data, like</p>
<pre><code>1,"foo "bar" baz",42</code></pre>
<p>or</p>
<pre><code>1,""foo bar baz"",42</code></pre>
<p>there is a way to get this data-line parsed and leave the quotes inside the quoted field as-is. This can be achieved by setting <code>allow_loose_quotes</code> <b>AND</b> making sure that the <a href="#escape"><code>escape</code></a> is <i>not</i> equal to <a href="#quote"><code>quote</code></a>.</p>
</dd>
<dt id="allow_loose_escapes">allow_loose_escapes </dt>
<dd>
</dd>
<dt id="allow-loose-escapes">allow-loose-escapes </dt>
<dd>
<pre><code>my $csv = Text::CSV.new(:allow_loose_escapes);
$csv.allow_loose_escapes(False);
my $ale = $csv.allow_loose_escapes;</code></pre>
<p>Parsing fields that have <a href="#escape"><code>escape</code></a> sequences that escape characters that do not need to be escaped, like:</p>
<pre><code>my $csv = Text::CSV.new(escape_char => "\\");
$csv.parse(q{1,"my bar\'s",baz,42});</code></pre>
<p>would result in parse returning <code>False</code> with reason 2025. Though it is bad practice to allow this format, this attribute enables you to treat all escape sequences equal.</p>
</dd>
<dt id="allow_unquoted_escape">allow_unquoted_escape </dt>
<dd>
</dd>
<dt id="allow-unquoted-escape">allow-unquoted-escape </dt>
<dd>
<pre><code>my $csv = Text::CSV.new(:allow_unquoted_escape);
$csv.allow_unquoted_escape(False);
my $aue = $csv.allow_unquoted_escape;</code></pre>
<p>A backward compatibility issue where <a href="#escape"><code>escape</code></a> differs from <a href="#quote"><code>quote</code></a> prevents <a href="#escape"><code>escape</code></a> to be in the first position of a field. If <a href="#quote"><code>quote</code></a> is equal to the default <code>"</code> and <a href="#escape"><code>escape</code></a> is set to <code>\</code>, this would be illegal:</p>
<pre><code>1,\0,2</code></pre>
<p>Setting this attribute to <code>True</code> might help to overcome issues with backward compatibility and allow this style.</p>
</dd>
<dt id="always_quote">always_quote </dt>
<dd>
</dd>
<dt id="always-quote">always-quote </dt>
<dd>
<pre><code>my $csv = Text::CSV.new(:always_quote);
$csv.always_quote(False);
my $f = $csv.always_quote;</code></pre>
<p>By default the generated fields are quoted only if they <i>need</i> to be. For example, if they contain the separator sequence. If you set this attribute to <code>1</code> then <i>all</i> defined fields will be quoted. (undefined (<code>Str</code>) fields are not quoted, see <a href="#blank_is_undef">"blank_is_undef"</a>). This makes it quite often easier to handle exported data in external applications. (Poor creatures who are better to use Text::CSV. :)</p>
</dd>
<dt id="quote_empty">quote_empty </dt>
<dd>
</dd>
<dt id="quote-empty">quote-empty </dt>
<dd>
<pre><code>my $csv = Text::CSV.new(:quote_empty);
$csv.quote_empty(False);
my $q-s = $csv.quote_empty;</code></pre>
<p>By default the generated fields are quoted only if they <i>need</i> to be. An empty defined field does not need quotation. If you set this attribute to <code>True</code> then empty defined fields will be quoted. See also <a href="#always_quote"><code>always_quote</code></a>.</p>
</dd>
<dt id="quote_space">quote_space </dt>
<dd>
</dd>
<dt id="quote-space">quote-space </dt>
<dd>
<pre><code>my $csv = Text::CSV.new(:quote_space);
$csv.quote_space(False);
my $q-s = $csv.quote_space;</code></pre>
<p>By default, a space in a field would trigger quotation. As no rule exists this to be forced in <code>CSV</code>, nor any for the opposite, the default is <code>True</code> for safety. You can exclude the space from this trigger by setting this attribute to <code>False</code>.</p>
</dd>
<dt id="escape_null">escape_null </dt>
<dd>
</dd>
<dt id="quote-null">quote-null </dt>
<dd>
<pre><code>my $csv = Text::CSV.new(:escape_null);
$csv.escape_null(False);
my $q-n = $csv.escape_null;</code></pre>
<p>By default, a <code>NULL</code> byte in a field would be escaped. This option enables you to treat the <code>NULL</code> byte as a simple binary character in binary mode (the <code>binary => True</code> is set). The default is <code>True</code>. You can prevent <code>NULL</code> escapes by setting this attribute to <code>False</code>.</p>
</dd>
<dt id="quote_binary">quote_binary </dt>
<dd>
</dd>
<dt id="quote-binary">quote-binary </dt>
<dd>
<pre><code>my $csv = Text::CSV.new(:quote_binary);
$csv.quote_binary(False);
my $q-b = $csv.quote_binary;</code></pre>
<p>By default, all "unsafe" bytes inside a string cause the combined field to be quoted. By setting this attribute to <code>False</code>, you can disable that trigger for bytes >= <code>0x7F</code>. (WIP)</p>
</dd>
<dt id="keep_meta">keep_meta </dt>
<dd>
</dd>
<dt id="keep-meta">keep-meta </dt>
<dd>
<pre><code>my $csv = Text::CSV.new(:keep_meta);
$csv.keep_meta(False);
my $k-m = $csv.keep_meta_info;</code></pre>
<p>By default, the parsing of input records is as simple and fast as possible. However, some parsing information - like quotation of the original field - is lost in that process. Setting this flag to true enables retrieving that information after parsing with the methods <a href="#meta_info">"meta_info"</a>, <a href="#is_quoted">"is_quoted"</a>, and <a href="#is_binary">"is_binary"</a> described below. Default is <code>False</code> for ease of use.</p>
<p>If <code>keep-meta</code> is set to <code>True</code>, the returned fields are not of type <code>Str</code> but of type <a href="#CSV::Field"><code>CSV::Field</code></a>.</p>
</dd>
<dt id="undef_str">undef_str </dt>
<dd>
</dd>
<dt id="undef-str">undef-str </dt>
<dd>
<p>NYI - this should replace undefined values in generating CSV</p>
</dd>
<dt id="comment_str">comment_str </dt>
<dd>
</dd>
<dt id="comment-str">comment-str </dt>
<dd>
<pre><code>my $csv = Text::CSV.new(comment_str => "#");
$csv.comment_str (Str);
my $s = $csv.comment_str;</code></pre>
<p>This attribute optionally defines a string to be recognized as comment. If this attribute is defined, all lines starting with this sequence will not be parsed as CSV but skipped as comment.</p>
<p>This attribute has no meaning when generating CSV.</p>
</dd>
<dt id="types">types</dt>
<dd>
<p>NYI</p>
<p>A set of column types; the attribute is immediately passed to the <a href="#types">"types"</a> method.</p>
</dd>
<dt id="callbacks">callbacks </dt>
<dd>
<p>See the <a href="#Callbacks">"Callbacks"</a> section below.</p>
</dd>
</dl>
<p>To sum it up,</p>
<pre><code>$csv = Text::CSV.new;</code></pre>
<p>is equivalent to</p>
<pre><code>$csv = Text::CSV.new(
eol => Nil, # \r, \n, or \r\n
sep => ',',
quote => '"',
escape => '"',
binary => True,
auto-diag => False,
diag-verbose => 0,
blank-is-undef => False,
empty-is-undef => False,
allow-whitespace => False,
allow-loose-quotes => False,
allow-loose-escapes => False,
allow-unquoted-escape => False,
always-quote => False,
quote-space => True,
escape-null => True,
quote-binary => True,
keep-meta => False,
strict => False,
formula => "none",
undef-str => Str,
comment-str => Str,
types => Nil,
callbacks => Nil,
});</code></pre>
<p>For all of the above mentioned flags, an accessor method is available where you can inquire the current value, or change the value</p>
<pre><code>my $quote = $csv.quote;
$csv.binary(True);</code></pre>
<p>It is not wise to change these settings halfway through writing <code>CSV</code> data to a stream. If however you want to create a new stream using the available <code>CSV</code> object, there is no harm in changing them.</p>
<p>If the <a href="#new">"new"</a> constructor call fails, an exception of type <code>CSV::Diac</code> is thrown with the reason like the <a href="#error_diag">"error_diag"</a> method would return:</p>
<pre><code>my $e;
{ $csv = Text::CSV.new(ecs_char => ":") or
CATCH { default { $e = $_; }}
}
$e and $e.message.say;</code></pre>
<p>The message will be a string like</p>
<pre><code>"INI - Unknown attribute 'ecs_char'"</code></pre>
<h2 id="print">print </h2>
<pre><code>$status = $csv.print($io, $fld, ... );
$status = $csv.print($io, ($fld, ...));
$status = $csv.print($io, [$fld, ...]);
$status = $csv.print($io, @fld );
$csv.column_names(%fld.keys); # or use a subset
$status = $csv.print($io, %fld );</code></pre>
<p>Similar to <a href="#combine">"combine"</a> + <a href="#string">"string"</a> + <a href="#print">"print"</a>, but much more efficient. It takes an IO object and any number of arguments interpreted as fields. The resulting string is immediately written to the <code>$io</code> stream.</p>
<p>NYI: no fields in combination with <a href="#bind_columns">"bind_columns"</a>, like</p>
<pre><code>$csv.bind_columns(\($foo, $bar));
$status = $csv.print($fh);</code></pre>
<p>A benchmark showed this order of preference, but the difference is within noise range:</p>
<pre><code>my @data = ^20;
$csv.print($io, @data ); # 2.6 sec
$csv.print($io, [ @data ]); # 2.7 sec
$csv.print($io, ^20 ); # 2.7 sec
$csv.print($io, \@data ); # 2.8 sec</code></pre>
<h2 id="say">say </h2>
<p>Is the same a s<a href="#print">"print"</a> where <a href="#eol"><code>eol</code></a> defaults to <code>$*OUT.nl</code>.</p>
<pre><code>$status = $csv.say($io, $fld, ... );
$status = $csv.say($io, ($fld, ...));
$status = $csv.say($io, [$fld, ...]);
$status = $csv.say($io, @fld );
$csv.column_names(%fld.keys); # or use a subset
$status = $csv.say($io, %fld );</code></pre>
<h2 id="combine">combine </h2>
<pre><code>$status = $csv.combine(@fields);
$status = $csv.combine($fld, ...);
$status = $csv.combine(\@fields);</code></pre>
<p>This method constructs a <code>CSV</code> row from <code>@fields</code>, returning success or failure. Failure can result from lack of arguments or an argument that contains invalid data. Upon success, <a href="#string">"string"</a> can be called to retrieve the resultant <code>CSV</code> string. Upon failure, the value returned by <a href="#string">"string"</a> is undefined and <a href="#error_input">"error_input"</a> could be called to retrieve the invalid argument. (WIP)</p>
<h2 id="string">string </h2>
<pre><code>$line = $csv.string;</code></pre>
<p>This method returns the input to <a href="#parse">"parse"</a> or the resultant <code>CSV</code> string of <a href="#combine">"combine"</a>, whichever was called more recently. If <a href="#eol"><code>eol</code></a> is defined, it is added to the string.</p>
<h2 id="getline">getline </h2>
<pre><code>@row = $csv.getline($io);
@row = $csv.getline($io, :meta);
@row = $csv.getline($str);
@row = $csv.getline($str, :meta);</code></pre>
<p>This is the counterpart to <a href="#print">"print"</a>, as <a href="#parse">"parse"</a> is the counterpart to <a href="#combine">"combine"</a>: it parses a row from the <code>$io</code> handle or <code>$str</code> using the <a href="#getline">"getline"</a> method associated with <code>$io</code> (or the internal temporary IO handle used to read from the string as if it were an IO handle) and parses this row into an array. This array is returned by the function or <code>Array</code> for failure. When <code>$io</code> does not support <code>getline</code>, you are likely to hit errors.</p>
<p>NYI: When fields are bound with <a href="#bind_columns">"bind_columns"</a> the return value is a reference to an empty list.</p>
<h2 id="getline_all-head2-getline-all">getline_all =head2 getline-all </h2>
<pre><code>@rows = $csv.getline_all($io);
@rows = $csv.getline_all($io, :meta);
@rows = $csv.getline_all($io, $offset);
@rows = $csv.getline_all($io, $offset, :meta);
@rows = $csv.getline_all($io, $offset, $length);
@rows = $csv.getline_all($io, $offset, $length, :meta);</code></pre>
<p>This will return a list of <a href="#getline">getline($io)</a> results. If <code>$offset</code> is negative, as with <code>splice</code>, only the last <code>abs($offset)</code> records of <code>$io</code> are taken into consideration.</p>
<p>Given a CSV file with 10 lines:</p>
<pre><code>lines call
----- ---------------------------------------------------------
0..9 $csv.getline_all($io) # all
0..9 $csv.getline_all($io, 0) # all
8..9 $csv.getline_all($io, 8) # start at 8
- $csv.getline_all($io, 0, 0) # start at 0 first 0 rows
0..4 $csv.getline_all($io, 0, 5) # start at 0 first 5 rows
4..5 $csv.getline_all($io, 4, 2) # start at 4 first 2 rows
8..9 $csv.getline_all($io, -2) # last 2 rows
6..7 $csv.getline_all($io, -4, 2) # first 2 of last 4 rows</code></pre>
<h2 id="getline_hr-head2-getline-hr">getline_hr =head2 getline-hr </h2>
<p>The <a href="#getline_hr">"getline_hr"</a> and <a href="#column_names">"column_names"</a> methods work together to allow you to have rows returned as hashes instead of arrays. You must invoke <a href="#column_names">"column_names"</a> first to declare your column names.</p>
<pre><code>$csv.column_names(< code name price description >);
%hr = $csv.getline_hr($str, :meta);
%hr = $csv.getline_hr($io);
say "Price for %hr<name> is %hr<price> \c[EURO SIGN]";</code></pre>
<p><a href="#getline_hr">"getline_hr"</a> will fail if invoked before <a href="#column_names">"column_names"</a>.</p>
<h2 id="getline_hr_all-head2-getline-hr-all">getline_hr_all =head2 getline-hr-all </h2>
<pre><code>@rows = $csv.getline_hr_all($io);
@rows = $csv.getline_hr_all($io, :meta);
@rows = $csv.getline_hr_all($io, $offset);
@rows = $csv.getline_hr_all($io, $offset, :meta);
@rows = $csv.getline_hr_all($io, $offset, $length);
@rows = $csv.getline_hr_all($io, $offset, $length, :meta);</code></pre>
<p>This will return a list of <a href="#getline_hr">getline_hr($io)</a> results.</p>
<h2 id="parse">parse </h2>
<pre><code>$status = $csv.parse($line);</code></pre>
<p>This method decomposes a <code>CSV</code> string into fields, returning success or failure. Failure can result from a lack of argument or improper format in the given <code>CSV</code> string. Upon success, invoke <a href="#fields">"fields"</a> or <a href="#strings">"strings"</a> to get the decomposed fields. Upon failure these methods shall not be trusted to return reliable data.</p>
<p>NYI: You may use the <a href="#types">"types"</a> method for setting column types. See <a href="#types">"types"</a>' description below.</p>
<h2 id="fragment">fragment </h2>
<p>This function implements <a href="https://datatracker.ietf.org/doc/html/rfc7111">RFC7111</a> (URI Fragment Identifiers for the text/csv Media Type).</p>
<pre><code>my @rows = $csv.fragment($io, $spec);</code></pre>
<p>In specifications, <code>*</code> is used to specify the <i>last</i> item, a dash (<code>-</code>) to indicate a range. All indices are <code>1</code>-based: the first row or column has index <code>1</code>. Selections can be combined with the semi-colon (<code>;</code>).</p>
<p>When using this method in combination with <a href="#column_names">"column_names"</a>, the returned array will be a list of hashes instead of an array of arrays. A disjointed cell-based combined selection might return rows with different number of columns making the use of hashes unpredictable.</p>
<pre><code>$csv.column_names(< Name Age >);
my @rows = $csv.fragment($io, "row=3;8");</code></pre>
<p>Note that for <code>col=".."</code>, the column names are the names for <i>before</i> the selection is taken to make it more consistent with reading possible headers from the first line of the CSV datastream.</p>
<pre><code>$csv,column_names(< foo bar >); # WRONG
$csv.fragment($io, "col=3");</code></pre>
<p>would set the column names for the first two columns that are then skipped in the fragment. To skip the unwanted columns, use placeholders.</p>
<pre><code>$csv.column_names(< x x Name >);
$csv.fragment($io, "col=3");</code></pre>
<p>WIP: If the <a href="#after_parse">"after_parse"</a> callback is active, it is also called on every line parsed and skipped before the fragment.</p>
<dl>
<dt id="row">row</dt>
<dd>
<pre><code>row=4
row=5-7
row=6-*
row=1-2;4;6-*</code></pre>
</dd>
<dt id="col">col</dt>
<dd>