Linux cli command Text_CSV_XSpm

➡ A Linux man page (short for manual page) is a form of software documentation found on Linux and Unix-like operating systems. This man-page explains the command Text_CSV_XSpm and provides detailed information about the command Text_CSV_XSpm, system calls, library functions, and other aspects of the system, including usage, options, and examples of _. You can access this man page by typing man followed by the Text_CSV_XSpm.

  29 minute read  

NAME 🖥️ Text_CSV_XSpm 🖥️

comma-separated values manipulation routines

SYNOPSIS

# Functional interface use Text::CSV_XS qw( csv ); # Read whole file in memory my $aoa = csv (in => “data.csv”); # as array of array my $aoh = csv (in => “data.csv”, headers => “auto”); # as array of hash # Write array of arrays as csv file csv (in => $aoa, out => “file.csv”, sep_char => “;”); # Only show lines where “code” is odd csv (in => “data.csv”, filter => { code => sub { $_ % 2 }}); # Object interface use Text::CSV_XS; my @rows; # Read/parse CSV my $csv = Text::CSV_XS->new ({ binary => 1, auto_diag => 1 }); open my $fh, “<:encoding(utf8)”, “test.csv” or die “test.csv: $!”; while (my $row = $csv->getline ($fh)) { $row->[2] =~ m/pattern/ or next; # 3rd field should match push @rows, $row; } close $fh; # and write as CSV open $fh, “>:encoding(utf8)”, “new.csv” or die “new.csv: $!”; $csv->say ($fh, $_) for @rows; close $fh or die “new.csv: $!”;

DESCRIPTION

Text::CSV_XS provides facilities for the composition and decomposition of comma-separated values. An instance of the Text::CSV_XS class will combine fields into a CSV string and parse a CSV string into fields.

The module accepts either strings or files as input and support the use of user-specified characters for delimiters, separators, and escapes.

Embedded newlines

Important Note: The default behavior is to accept only ASCII characters in the range from 0x20 (space) to 0x7E (tilde). This means that the fields can not contain newlines. If your data contains newlines embedded in fields, or characters above 0x7E (tilde), or binary data, you must set binary => 1 in the call to “new”. To cover the widest range of parsing options, you will always want to set binary.

But you still have the problem that you have to pass a correct line to the “parse” method, which is more complicated from the usual point of usage:

my $csv = Text::CSV_XS->new ({ binary => 1, eol => $/ }); while (<>) { # WRONG! $csv->parse ($_); my @fields = $csv->fields (); }

this will break, as the while might read broken lines: it does not care about the quoting. If you need to support embedded newlines, the way to go is to not pass eol in the parser (it accepts , , and by default) and then

my $csv = Text::CSV_XS->new ({ binary => 1 }); open my $fh, “<”, $file or die “$file: $!”; while (my $row = $csv->getline ($fh)) { my @fields = @$row; }

The old(er) way of using global file handles is still supported

while (my $row = $csv->getline (*ARGV)) { … }

Unicode

Unicode is only tested to work with perl-5.8.2 and up.

See also “BOM”.

The simplest way to ensure the correct encoding is used for in- and output is by either setting layers on the filehandles, or setting the “encoding” argument for “csv”.

open my $fh, “<:encoding(UTF-8)”, “in.csv” or die “in.csv: $!”; or my $aoa = csv (in => “in.csv”, encoding => “UTF-8”); open my $fh, “>:encoding(UTF-8)”, “out.csv” or die “out.csv: $!”; or csv (in => $aoa, out => “out.csv”, encoding => “UTF-8”);

On parsing (both for “getline” and “parse”), if the source is marked being UTF8, then all fields that are marked binary will also be marked UTF8.

On combining (“print” and “combine”): if any of the combining fields was marked UTF8, the resulting string will be marked as UTF8. Note however that all fields before the first field marked UTF8 and contained 8-bit characters that were not upgraded to UTF8, these will be bytes in the resulting string too, possibly causing unexpected errors. If you pass data of different encoding, or you don’t know if there is different encoding, force it to be upgraded before you pass them on:

$csv->print ($fh, [ map { utf8::upgrade (my $x = $_); $x } @data ]);

For complete control over encoding, please use Text::CSV::Encoded:

use Text::CSV::Encoded; my $csv = Text::CSV::Encoded->new ({ encoding_in => “iso-8859-1”, # the encoding comes into Perl encoding_out => “cp1252”, # the encoding comes out of Perl }); $csv = Text::CSV::Encoded->new ({ encoding => “utf8” }); # combine () and print () accept *literally* utf8 encoded data # parse () and getline () return *literally* utf8 encoded data $csv = Text::CSV::Encoded->new ({ encoding => undef }); # default # combine () and print () accept UTF8 marked data # parse () and getline () return UTF8 marked data

BOM

BOM (or Byte Order Mark) handling is available only inside the “header” method. This method supports the following encodings: utf-8, utf-1, utf-32be, utf-32le, utf-16be, utf-16le, utf-ebcdic, scsu, bocu-1, and gb-18030. See Wikipedia <https://en.wikipedia.org/wiki/Byte_order_mark>.

If a file has a BOM, the easiest way to deal with that is

my $aoh = csv (in => $file, detect_bom => 1);

All records will be encoded based on the detected BOM.

This implies a call to the “header” method, which defaults to also set the “column_names”. So this is not the same as

my $aoh = csv (in => $file, headers => “auto”);

which only reads the first record to set “column_names” but ignores any meaning of possible present BOM.

SPECIFICATION

While no formal specification for CSV exists, RFC 4180 <https://datatracker.ietf.org/doc/html/rfc4180> (1) describes the common format and establishes text/csv as the MIME type registered with the IANA. RFC 7111 <https://datatracker.ietf.org/doc/html/rfc7111> (2) adds fragments to CSV.

Many informal documents exist that describe the CSV format. “How To: The Comma Separated Value (CSV) File Format” <http://creativyst.com/Doc/Articles/CSV/CSV01.shtml> (3) provides an overview of the CSV format in the most widely used applications and explains how it can best be used and supported.

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

The basic rules are as follows:

CSV 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 CSV file format does not require a specific character encoding, byte order, or line terminator format.

  • Each record is a single line ended by a line feed (ASCII/LF=0x0A) or a carriage return and line feed pair (ASCII/CRLF=0x0D 0x0A), however, line-breaks may be embedded.

  • Fields are separated by commas.

  • Allowable characters within a CSV field include 0x09 (TAB) and the inclusive range of 0x20 (space) through 0x7E (tilde). In binary mode all characters are accepted, at least in quoted fields.

  • A field within CSV must be surrounded by double-quotes to contain a separator character (comma).

Though this is the most clear and restrictive definition, Text::CSV_XS is way more liberal than this, and allows extension:

  • Line termination by a single carriage return is accepted by default

  • The separation-, quote-, and escape character(s) can be any ASCII character in the range from 0x20 (space) to 0x7E (tilde). Characters outside this range may or may not work as expected. Multibyte characters, like UTF U+060C (ARABIC COMMA), U+FF0C (FULLWIDTH COMMA), U+241B (SYMBOL FOR ESCAPE), U+2424 (SYMBOL FOR NEWLINE), U+FF02 (FULLWIDTH QUOTATION MARK), and U+201C (LEFT DOUBLE QUOTATION MARK) (to give some examples of what might look promising) work for newer versions of perl for sep_char, and quote_char but not for escape_char. If you use perl-5.8.2 or higher these three attributes are utf8-decoded, to increase the likelihood of success. This way U+00FE will be allowed as a quote character.

  • A field in CSV must be surrounded by double-quotes to make an embedded double-quote, represented by a pair of consecutive double-quotes, valid. In binary mode you may additionally use the sequence "0 for representation of a NULL byte. Using 0x00 in binary mode is just as valid.

  • Several violations of the above specification may be lifted by passing some options as attributes to the object constructor.

METHODS

version

(Class method) Returns the current module version.

new

(Class method) Returns a new instance of class Text::CSV_XS. The attributes are described by the (optional) hash ref \%attr.

my $csv = Text::CSV_XS->new ({ attributes … });

The following attributes are available:

eol

my $csv = Text::CSV_XS->new ({ eol => $/ }); $csv->eol (undef); my $eol = $csv->eol;

The end-of-line string to add to rows for “print” or the record separator for “getline”.

When not passed in a parser instance, the default behavior is to accept , , and , so it is probably safer to not specify eol at all. Passing undef or the empty string behave the same.

When not passed in a generating instance, records are not terminated at all, so it is probably wise to pass something you expect. A safe choice for eol on output is either $/ or .

Common values for eol are " " ( or Line Feed), " " ( or Carriage Return, Line Feed), and " " ( or Carriage Return). The eol attribute cannot exceed 7 (ASCII) characters.

If both $/ and eol equal " ", parsing lines that end on only a Carriage Return without Line Feed, will be “parse"d correct.

sep_char

my $csv = Text::CSV_XS->new ({ sep_char => “;” }); $csv->sep_char (”;"); my $c = $csv->sep_char;

The char used to separate fields, by default a comma. (,). Limited to a single-byte character, usually in the range from 0x20 (space) to 0x7E (tilde). When longer sequences are required, use sep.

The separation character can not be equal to the quote character or to the escape character.

See also “CAVEATS”

sep

my $csv = Text::CSV_XS->new ({ sep => “\N{FULLWIDTH COMMA}” }); $csv->sep (";"); my $sep = $csv->sep;

The chars used to separate fields, by default undefined. Limited to 8 bytes.

When set, overrules sep_char. If its length is one byte it acts as an alias to sep_char.

See also “CAVEATS”

quote_char

my $csv = Text::CSV_XS->new ({ quote_char => "" }); $csv->quote_char (undef); my $c = $csv->quote_char;

The character to quote fields containing blanks or binary data, by default the double quote character ("). A value of undef suppresses quote chars (for simple cases only). Limited to a single-byte character, usually in the range from 0x20 (space) to 0x7E (tilde). When longer sequences are required, use quote.

quote_char can not be equal to sep_char.

quote

my $csv = Text::CSV_XS->new ({ quote => “\N{FULLWIDTH QUOTATION MARK}” }); $csv->quote (""); my $quote = $csv->quote;

The chars used to quote fields, by default undefined. Limited to 8 bytes.

When set, overrules quote_char. If its length is one byte it acts as an alias to quote_char.

This method does not support undef. Use quote_char to disable quotation.

See also “CAVEATS”

escape_char

my $csv = Text::CSV_XS->new ({ escape_char => “" }); $csv->escape_char (”:"); my $c = $csv->escape_char;

The character to escape certain characters inside quoted fields. This is limited to a single-byte character, usually in the range from 0x20 (space) to 0x7E (tilde).

The escape_char defaults to being the double-quote mark ("). In other words the same as the default quote_char. This means that doubling the quote mark in a field escapes it:

“foo”,“bar”,“Escape ““quote mark”” with two ““quote marks”””,“baz”

If you change the quote_char without changing the escape_char, the escape_char will still be the double-quote ("). If instead you want to escape the quote_char by doubling it you will need to also change the escape_char to be the same as what you have changed the quote_char to.

Setting escape_char to undef or "" will completely disable escapes and is greatly discouraged. This will also disable escape_null.

The escape character can not be equal to the separation character.

binary

my $csv = Text::CSV_XS->new ({ binary => 1 }); $csv->binary (0); my $f = $csv->binary;

If this attribute is 1, you may use binary characters in quoted fields, including line feeds, carriage returns and NULL bytes. (The latter could be escaped as "0.) By default this feature is off.

If a string is marked UTF8, binary will be turned on automatically when binary characters other than CR and NL are encountered. Note that a simple string like "\x{00a0}" might still be binary, but not marked UTF8, so setting { binary => 1 } is still a wise option.

strict

my $csv = Text::CSV_XS->new ({ strict => 1 }); $csv->strict (0); my $f = $csv->strict;

If this attribute is set to 1, any row that parses to a different number of fields than the previous row will cause the parser to throw error 2014.

Empty rows or rows that result in no fields (like comment lines) are exempt from these checks.

skip_empty_rows

my $csv = Text::CSV_XS->new ({ skip_empty_rows => 1 }); $csv->skip_empty_rows (“eof”); my $f = $csv->skip_empty_rows;

This attribute defines the behavior for empty rows: an “eol” immediately following the start of line. Default behavior is to return one single empty field.

This attribute is only used in parsing. This attribute is ineffective when using “parse” and “fields”.

Possible values for this attribute are

0 | undef
my $csv = Text::CSV_XS->new ({ skip_empty_rows => 0 }); $csv->skip_empty_rows (undef); No special action is taken. The result will be one single empty field.

1 | “skip”
my $csv = Text::CSV_XS->new ({ skip_empty_rows => 1 }); $csv->skip_empty_rows (“skip”); The row will be skipped.

2 | “eof” | “stop”
my $csv = Text::CSV_XS->new ({ skip_empty_rows => 2 }); $csv->skip_empty_rows (“eof”); The parsing will stop as if an “eof” was detected.

3 | “die”
my $csv = Text::CSV_XS->new ({ skip_empty_rows => 3 }); $csv->skip_empty_rows (“die”); The parsing will stop. The internal error code will be set to 2015 and the parser will die.

4 | “croak”
my $csv = Text::CSV_XS->new ({ skip_empty_rows => 4 }); $csv->skip_empty_rows (“croak”); The parsing will stop. The internal error code will be set to 2015 and the parser will croak.

5 | “error”
my $csv = Text::CSV_XS->new ({ skip_empty_rows => 5 }); $csv->skip_empty_rows (“error”); The parsing will fail. The internal error code will be set to 2015.

callback
my $csv = Text::CSV_XS->new ({ skip_empty_rows => sub { [] } }); $csv->skip_empty_rows (sub { [ 42, $., undef, “empty” ] }); The callback is invoked and its result used instead. If you want the parse to stop after the callback, make sure to return a false value. The returned value from the callback should be an array-ref. Any other type will cause the parse to stop, so these are equivalent in behavior: csv (in => $fh, skip_empty_rows => “stop”); csv (in => $fh. skip_empty_rows => sub { 0; });

Without arguments, the current value is returned: 0, 1, eof, die, croak or the callback.

formula_handling

Alias for “formula”

formula

my $csv = Text::CSV_XS->new ({ formula => “none” }); $csv->formula (“none”); my $f = $csv->formula;

This defines the behavior of fields containing formulas. 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 (=).

For purpose of code-readability, this can also be written as

my $csv = Text::CSV_XS->new ({ formula_handling => “none” }); $csv->formula_handling (“none”); my $f = $csv->formula_handling;

Possible values for this attribute are

none
Take no specific action. This is the default. $csv->formula (“none”);

die
Cause the process to die whenever a leading = is encountered. $csv->formula (“die”);

croak
Cause the process to croak whenever a leading = is encountered. (See Carp) $csv->formula (“croak”);

diag
Report position and content of the field whenever a leading = is found. The value of the field is unchanged. $csv->formula (“diag”);

empty
Replace the content of fields that start with a = with the empty string. $csv->formula (“empty”); $csv->formula ("");

undef
Replace the content of fields that start with a = with undef. $csv->formula (“undef”); $csv->formula (undef);

a callback
Modify the content of fields that start with a = with the return-value of the callback. The original content of the field is available inside the callback as $_; # Replace all formulas with 42 $csv->formula (sub { 42; }); # same as $csv->formula (“empty”) but slower $csv->formula (sub { "" }); # Allow =4+12 $csv->formula (sub { s/^=(\d+\d+)$/$1/eer }); # Allow more complex calculations $csv->formula (sub { eval { s{^=([-+*/0-9()]+)$}{$1}ee }; $_ });

All other values will give a warning and then fallback to diag.

decode_utf8

my $csv = Text::CSV_XS->new ({ decode_utf8 => 1 }); $csv->decode_utf8 (0); my $f = $csv->decode_utf8;

This attributes defaults to TRUE.

While parsing, fields that are valid UTF-8, are automatically set to be UTF-8, so that

$csv->parse (“Ĩ “);

results in

PV("\304\250"�) [UTF8 “\x{128}”]

Sometimes it might not be a desired action. To prevent those upgrades, set this attribute to false, and the result will be

PV("\304\250"�)

auto_diag

my $csv = Text::CSV_XS->new ({ auto_diag => 1 }); $csv->auto_diag (2); my $l = $csv->auto_diag;

Set this attribute to a number between 1 and 9 causes “error_diag” to be automatically called in void context upon errors.

In case of error 2012 - EOF, this call will be void.

If auto_diag is set to a numeric value greater than 1, it will die on errors instead of warn. If set to anything unrecognized, it will be silently ignored.

Future extensions to this feature will include more reliable auto-detection of autodie being active in the scope of which the error occurred which will increment the value of auto_diag with 1 the moment the error is detected.

diag_verbose

my $csv = Text::CSV_XS->new ({ diag_verbose => 1 }); $csv->diag_verbose (2); my $l = $csv->diag_verbose;

Set the verbosity of the output triggered by auto_diag. Currently only adds the current input-record-number (if known) to the diagnostic output with an indication of the position of the error.

blank_is_undef

my $csv = Text::CSV_XS->new ({ blank_is_undef => 1 }); $csv->blank_is_undef (0); my $f = $csv->blank_is_undef;

Under normal circumstances, CSV data makes no distinction between quoted- and unquoted empty fields. These both end up in an empty string field once read, thus

1,””,," “,2

is read as

(“1”, “”, “”, " “, “2”)

When writing CSV files with either always_quote or quote_empty set, the unquoted empty field is the result of an undefined value. To enable this distinction when reading CSV data, the blank_is_undef attribute will cause unquoted empty fields to be set to undef, causing the above to be parsed as

(“1”, “”, undef, " “, “2”)

Note that this is specifically important when loading CSV fields into a database that allows NULL values, as the perl equivalent for NULL is undef in DBI land.

empty_is_undef

my $csv = Text::CSV_XS->new ({ empty_is_undef => 1 }); $csv->empty_is_undef (0); my $f = $csv->empty_is_undef;

Going one step further than blank_is_undef, this attribute converts all empty fields to undef, so

1,””,,” “,2

is read as

(1, undef, undef, " “, 2)

Note that this affects only fields that are originally empty, not fields that are empty after stripping allowed whitespace. YMMV.

allow_whitespace

my $csv = Text::CSV_XS->new ({ allow_whitespace => 1 }); $csv->allow_whitespace (0); my $f = $csv->allow_whitespace;

When this option is set to true, the whitespace (TAB’s and SPACE’s) surrounding the separation character is removed when parsing. If either TAB or SPACE is one of the three characters sep_char, quote_char, or escape_char it will not be considered whitespace.

Now lines like:

1 , “foo” , bar , 3 , zapp

are parsed as valid CSV, even though it violates the CSV specs.

Note that all whitespace is stripped from both start and end of each field. That would make it more than a feature to enable parsing bad CSV lines, as

1, 2.0, 3, ape , monkey

will now be parsed as

(“1”, “2.0”, “3”, “ape”, “monkey”)

even if the original line was perfectly acceptable CSV.

allow_loose_quotes

my $csv = Text::CSV_XS->new ({ allow_loose_quotes => 1 }); $csv->allow_loose_quotes (0); my $f = $csv->allow_loose_quotes;

By default, parsing unquoted fields containing quote_char characters like

1,foo “bar” baz,42

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.

If there is really bad CSV data, like

1,“foo “bar” baz”,42

or

1,““foo bar baz”",42

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 allow_loose_quotes AND making sure that the escape_char is not equal to quote_char.

allow_loose_escapes

my $csv = Text::CSV_XS->new ({ allow_loose_escapes => 1 }); $csv->allow_loose_escapes (0); my $f = $csv->allow_loose_escapes;

Parsing fields that have escape_char characters that escape characters that do not need to be escaped, like:

my $csv = Text::CSV_XS->new ({ escape_char => “" }); $csv->parse (qq{1,“my bar\s”,baz,42});

would result in parse error 2025. Though it is bad practice to allow this format, this attribute enables you to treat all escape character sequences equal.

allow_unquoted_escape

my $csv = Text::CSV_XS->new ({ allow_unquoted_escape => 1 }); $csv->allow_unquoted_escape (0); my $f = $csv->allow_unquoted_escape;

A backward compatibility issue where escape_char differs from quote_char prevents escape_char to be in the first position of a field. If quote_char is equal to the default " and escape_char is set to \, this would be illegal:

1,�,2

Setting this attribute to 1 might help to overcome issues with backward compatibility and allow this style.

always_quote

my $csv = Text::CSV_XS->new ({ always_quote => 1 }); $csv->always_quote (0); my $f = $csv->always_quote;

By default the generated fields are quoted only if they need to be. For example, if they contain the separator character. If you set this attribute to 1 then all defined fields will be quoted. (undef fields are not quoted, see “blank_is_undef”). This makes it quite often easier to handle exported data in external applications. (Poor creatures who are better to use Text::CSV_XS. :)

quote_space

my $csv = Text::CSV_XS->new ({ quote_space => 1 }); $csv->quote_space (0); my $f = $csv->quote_space;

By default, a space in a field would trigger quotation. As no rule exists this to be forced in CSV, nor any for the opposite, the default is true for safety. You can exclude the space from this trigger by setting this attribute to 0.

quote_empty

my $csv = Text::CSV_XS->new ({ quote_empty => 1 }); $csv->quote_empty (0); my $f = $csv->quote_empty;

By default the generated fields are quoted only if they need to be. An empty (defined) field does not need quotation. If you set this attribute to 1 then empty defined fields will be quoted. (undef fields are not quoted, see “blank_is_undef”). See also always_quote.

quote_binary

my $csv = Text::CSV_XS->new ({ quote_binary => 1 }); $csv->quote_binary (0); my $f = $csv->quote_binary;

By default, all “unsafe” bytes inside a string cause the combined field to be quoted. By setting this attribute to 0, you can disable that trigger for bytes >= 0x7F.

escape_null

my $csv = Text::CSV_XS->new ({ escape_null => 1 }); $csv->escape_null (0); my $f = $csv->escape_null;

By default, a NULL byte in a field would be escaped. This option enables you to treat the NULL byte as a simple binary character in binary mode (the { binary => 1 } is set). The default is true. You can prevent NULL escapes by setting this attribute to 0.

When the escape_char attribute is set to undefined, this attribute will be set to false.

The default setting will encode “=�=” as

“=“0=”

With escape_null set, this will result in

“=�=”

The default when using the csv function is false.

For backward compatibility reasons, the deprecated old name quote_null is still recognized.

keep_meta_info

my $csv = Text::CSV_XS->new ({ keep_meta_info => 1 }); $csv->keep_meta_info (0); my $f = $csv->keep_meta_info;

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 “meta_info”, “is_quoted”, and “is_binary” described below. Default is false for performance.

If you set this attribute to a value greater than 9, then you can control output quotation style like it was used in the input of the the last parsed record (unless quotation was added because of other reasons).

my $csv = Text::CSV_XS->new ({ binary => 1, keep_meta_info => 1, quote_space => 0, }); my $row = $csv->parse (q{1,,””, ,” “,f,“g”,“h"“h”,help,“help”}); $csv->print (*STDOUT, \row); # 1,,, , ,f,g,“h"“h”,help,help $csv->keep_meta_info (11); $csv->print (*STDOUT, \row); # 1,,””, ,” “,f,“g”,“h"“h”,help,“help”

undef_str

my $csv = Text::CSV_XS->new ({ undef_str => “\N” }); $csv->undef_str (undef); my $s = $csv->undef_str;

This attribute optionally defines the output of undefined fields. The value passed is not changed at all, so if it needs quotation, the quotation needs to be included in the value of the attribute. Use with caution, as passing a value like ",",,,,""" will for sure mess up your output. The default for this attribute is undef, meaning no special treatment.

This attribute is useful when exporting CSV data to be imported in custom loaders, like for MySQL, that recognize special sequences for NULL data.

This attribute has no meaning when parsing CSV data.

comment_str

my $csv = Text::CSV_XS->new ({ comment_str => “#” }); $csv->comment_str (undef); my $s = $csv->comment_str;

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.

This attribute has no meaning when generating CSV.

Comment strings that start with any of the special characters/sequences are not supported (so it cannot start with any of “sep_char”, “quote_char”, “escape_char”, “sep”, “quote”, or “eol”).

For convenience, comment is an alias for comment_str.

verbatim

my $csv = Text::CSV_XS->new ({ verbatim => 1 }); $csv->verbatim (0); my $f = $csv->verbatim;

This is a quite controversial attribute to set, but makes some hard things possible.

The rationale behind this attribute is to tell the parser that the normally special characters newline (NL) and Carriage Return (CR) will not be special when this flag is set, and be dealt with as being ordinary binary characters. This will ease working with data with embedded newlines.

When verbatim is used with “getline”, “getline” auto-chomp’s every line.

Imagine a file format like

M^^Hans^Janssen^Klas 2 2A^Ja^11-06-2007#

where, the line ending is a very specific "# ", and the sep_char is a ^ (caret). None of the fields is quoted, but embedded binary data is likely to be present. With the specific line ending, this should not be too hard to detect.

By default, Text::CSV_XS’ parse function is instructed to only know about " " and " " to be legal line endings, and so has to deal with the embedded newline as a real end-of-line, so it can scan the next line if binary is true, and the newline is inside a quoted field. With this option, we tell “parse” to parse the line as if " " is just nothing more than a binary character.

For “parse” this means that the parser has no more idea about line ending and “getline” chomps line endings on reading.

types

A set of column types; the attribute is immediately passed to the “types” method.

callbacks

See the “Callbacks” section below.

accessors

To sum it up,

$csv = Text::CSV_XS->new ();

is equivalent to

$csv = Text::CSV_XS->new ({ eol => undef, # , , or sep_char => ,, sep => undef, quote_char => “, quote => undef, escape_char => “, binary => 0, decode_utf8 => 1, auto_diag => 0, diag_verbose => 0, blank_is_undef => 0, empty_is_undef => 0, allow_whitespace => 0, allow_loose_quotes => 0, allow_loose_escapes => 0, allow_unquoted_escape => 0, always_quote => 0, quote_empty => 0, quote_space => 1, escape_null => 1, quote_binary => 1, keep_meta_info => 0, strict => 0, skip_empty_rows => 0, formula => 0, verbatim => 0, undef_str => undef, comment_str => undef, types => undef, callbacks => undef, });

For all of the above mentioned flags, an accessor method is available where you can inquire the current value, or change the value

my $quote = $csv->quote_char; $csv->binary (1);

It is not wise to change these settings halfway through writing CSV data to a stream. If however you want to create a new stream using the available CSV object, there is no harm in changing them.

If the “new” constructor call fails, it returns undef, and makes the fail reason available through the “error_diag” method.

$csv = Text::CSV_XS->new ({ ecs_char => 1 }) or die “".Text::CSV_XS->error_diag ();

“error_diag” will return a string like

“INI - Unknown attribute ecs_char”

known_attributes

@attr = Text::CSV_XS->known_attributes; @attr = Text::CSV_XS::known_attributes; @attr = $csv->known_attributes;

This method will return an ordered list of all the supported attributes as described above. This can be useful for knowing what attributes are valid in classes that use or extend Text::CSV_XS.

print

$status = $csv->print ($fh, $colref);

Similar to “combine” + “string” + “print”, but much more efficient. It expects an array ref as input (not an array!) and the resulting string is not really created, but immediately written to the $fh object, typically an IO handle or any other object that offers a “print” method.

For performance reasons print does not create a result string, so all “string”, “status”, “fields”, and “error_input” methods will return undefined information after executing this method.

If $colref is undef (explicit, not through a variable argument) and “bind_columns” was used to specify fields to be printed, it is possible to make performance improvements, as otherwise data would have to be copied as arguments to the method call:

$csv->bind_columns ($foo, $bar)); $status = $csv->print ($fh, undef);

A short benchmark

my @data = (“aa” .. “zz”); $csv->bind_columns (@data)); $csv->print ($fh, [ @data ]); # 11800 recs/sec $csv->print ($fh, \data ); # 57600 recs/sec $csv->print ($fh, undef ); # 48500 recs/sec

say

$status = $csv->say ($fh, $colref);

Like print, but eol defaults to $\.

$csv->print_hr ($fh, $ref);

Provides an easy way to print a $ref (as fetched with “getline_hr”) provided the column names are set with “column_names”.

It is just a wrapper method with basic parameter checks over

$csv->print ($fh, [ map { $ref->{$_} } $csv->column_names ]);

combine

$status = $csv->combine (@fields);

This method constructs a CSV record from @fields, returning success or failure. Failure can result from lack of arguments or an argument that contains an invalid character. Upon success, “string” can be called to retrieve the resultant CSV string. Upon failure, the value returned by “string” is undefined and “error_input” could be called to retrieve the invalid argument.

string

$line = $csv->string ();

This method returns the input to “parse” or the resultant CSV string of “combine”, whichever was called more recently.

getline

$colref = $csv->getline ($fh);

This is the counterpart to “print”, as “parse” is the counterpart to “combine”: it parses a row from the $fh handle using the “getline” method associated with $fh and parses this row into an array ref. This array ref is returned by the function or undef for failure. When $fh does not support getline, you are likely to hit errors.

When fields are bound with “bind_columns” the return value is a reference to an empty list.

The “string”, “fields”, and “status” methods are meaningless again.

getline_all

$arrayref = $csv->getline_all ($fh); $arrayref = $csv->getline_all ($fh, $offset); $arrayref = $csv->getline_all ($fh, $offset, $length);

This will return a reference to a list of getline ($fh) results. In this call, keep_meta_info is disabled. If $offset is negative, as with splice, only the last abs ($offset) records of $fh are taken into consideration. Parameters $offset and $length are expected to be integers. Non-integer values are interpreted as integer without check.

Given a CSV file with 10 lines:

lines call —– ——————————————————— 0..9 $csv->getline_all ($fh) # all 0..9 $csv->getline_all ($fh, 0) # all 8..9 $csv->getline_all ($fh, 8) # start at 8 - $csv->getline_all ($fh, 0, 0) # start at 0 first 0 rows 0..4 $csv->getline_all ($fh, 0, 5) # start at 0 first 5 rows 4..5 $csv->getline_all ($fh, 4, 2) # start at 4 first 2 rows 8..9 $csv->getline_all ($fh, -2) # last 2 rows 6..7 $csv->getline_all ($fh, -4, 2) # first 2 of last 4 rows

getline_hr

The “getline_hr” and “column_names” methods work together to allow you to have rows returned as hashrefs. You must call “column_names” first to declare your column names.

$csv->column_names (qw( code name price description )); $hr = $csv->getline_hr ($fh); print “Price for $hr->{name} is $hr->{price} EUR “;

“getline_hr” will croak if called before “column_names”.

Note that “getline_hr” creates a hashref for every row and will be much slower than the combined use of “bind_columns” and “getline” but still offering the same easy to use hashref inside the loop:

my @cols = @{$csv->getline ($fh)}; $csv->column_names (@cols); while (my $row = $csv->getline_hr ($fh)) { print $row->{price}; }

Could easily be rewritten to the much faster:

my @cols = @{$csv->getline ($fh)}; my $row = {}; $csv->bind_columns ({$row}{@cols}); while ($csv->getline ($fh)) { print $row->{price}; }

Your mileage may vary for the size of the data and the number of rows. With perl-5.14.2 the comparison for a 100_000 line file with 14 columns:

Rate hashrefs getlines hashrefs 1.00/s – -76% getlines 4.15/s 313% –

getline_hr_all

$arrayref = $csv->getline_hr_all ($fh); $arrayref = $csv->getline_hr_all ($fh, $offset); $arrayref = $csv->getline_hr_all ($fh, $offset, $length);

This will return a reference to a list of getline_hr ($fh) results. In this call, keep_meta_info is disabled.

parse

$status = $csv->parse ($line);

This method decomposes a CSV string into fields, returning success or failure. Failure can result from a lack of argument or the given CSV string is improperly formatted. Upon success, “fields” can be called to retrieve the decomposed fields. Upon failure calling “fields” will return undefined data and “error_input” can be called to retrieve the invalid argument.

You may use the “types” method for setting column types. See “types”’ description below.

The $line argument is supposed to be a simple scalar. Everything else is supposed to croak and set error 1500.

fragment

This function tries to implement RFC7111 (URI Fragment Identifiers for the text/csv Media Type) - https://datatracker.ietf.org/doc/html/rfc7111

my $AoA = $csv->fragment ($fh, $spec);

In specifications, * is used to specify the last item, a dash (-) to indicate a range. All indices are 1-based: the first row or column has index 1. Selections can be combined with the semi-colon (;).

When using this method in combination with “column_names”, the returned reference will point to a list of hashes instead of a list of lists. A disjointed cell-based combined selection might return rows with different number of columns making the use of hashes unpredictable.

$csv->column_names (“Name”, “Age”); my $AoH = $csv->fragment ($fh, “col=3;8”);

If the “after_parse” callback is active, it is also called on every line parsed and skipped before the fragment.

row
row=4 row=5-7 row=6-* row=1-2;4;6-*

col
col=2 col=1-3 col=4-* col=1-2;4;7-*

cell
In cell-based selection, the comma (,) is used to pair row and column cell=4,1 The range operator (-) using cells can be used to define top-left and bottom-right cell location cell=3,1-4,6 The * is only allowed in the second part of a pair cell=3,2-*,2 # row 3 till end, only column 2 cell=3,2-3,* # column 2 till end, only row 3 cell=3,2-*,* # strip row 1 and 2, and column 1 Cells and cell ranges may be combined with ;, possibly resulting in rows with different numbers of columns cell=1,1-2,2;3,3-4,4;1,4;4,1 Disjointed selections will only return selected cells. The cells that are not specified will not be included in the returned set, not even as undef. As an example given a CSV like 11,12,13,…19 21,22,…28,29 : : 91,…97,98,99 with cell=1,1-2,2;3,3-4,4;1,4;4,1 will return: 11,12,14 21,22 33,34 41,43,44 Overlapping cell-specs will return those cells only once, So cell=1,1-3,3;2,2-4,4;2,3;4,2 will return: 11,12,13 21,22,23,24 31,32,33,34 42,43,44

RFC7111 <https://datatracker.ietf.org/doc/html/rfc7111> does not allow different types of specs to be combined (either row or col or cell). Passing an invalid fragment specification will croak and set error 2013.

column_names

Set the “keys” that will be used in the “getline_hr” calls. If no keys (column names) are passed, it will return the current setting as a list.

“column_names” accepts a list of scalars (the column names) or a single array_ref, so you can pass the return value from “getline” too:

$csv->column_names ($csv->getline ($fh));

“column_names” does no checking on duplicates at all, which might lead to unexpected results. Undefined entries will be replaced with the string `”