This method does NOT work in perl-5.6.x
Parse the CSV header and set sep, column_names and encoding.
my @hdr = $csv->header ($fh);
$csv->header ($fh, { sep_set => [ ";", ",", "|", "\t" ] });
$csv->header ($fh, { detect_bom => 1, munge_column_names => "lc" });The first argument should be a file handle.
Assuming that the file opened for parsing has a header, and the header does not contain problematic characters like embedded newlines, read the first line from the open handle then auto-detect whether the header separates the column names with a character from the allowed separator list.
If any of the allowed separators matches, and none of the other allowed separators match, set sep to that separator for the current CSV_XS instance and use it to parse the first line, map those to lowercase, and use that to set the instance "column_names":
my $csv = Text::CSV_XS->new ({ binary => 1, auto_diag => 1 });
open my $fh, "<", "file.csv";
binmode $fh; # for Windows
$csv->header ($fh);
while (my $row = $csv->getline_hr ($fh)) {
...
}If the header is empty, contains more than one unique separator out of the allowed set, contains empty fields, or contains identical fields (after folding), it will croak with error 1010, 1011, 1012, or 1013 respectively.
If the header contains embedded newlines or is not valid CSV in any other way, this method will croak and leave the parse error untouched.
A successful call to header will always set the sep of the $csv object. This behavior can not be disabled.
On error this method will croak.
In list context, the headers will be returned whether they are used to set "column_names" or not.
In scalar context, the instance itself is returned. Note: the values as found in the header will effectively be lost if set_column_names is false.
$csv->header ($fh, { sep_set => [ ";", ",", "|", "\t" ] });The list of legal separators defaults to [ ";", "," ] and can be changed by this option. As this is probably the most often used option, it can be passed on its own as an unnamed argument:
$csv->header ($fh, [ ";", ",", "|", "\t", "::", "\x{2063}" ]);Multi-byte sequences are allowed, both multi-character and Unicode. See sep.
$csv->header ($fh, { detect_bom => 1 });The default behavior is to detect if the header line starts with a BOM. If the header has a BOM, use that to set the encoding of $fh. This default behavior can be disabled by passing a false value to detect_bom.
Supported encodings from BOM are: UTF-8, UTF-16BE, UTF-16LE, UTF-32BE, and UTF-32LE. BOM's also support UTF-1, UTF-EBCDIC, SCSU, BOCU-1, and GB-18030 but Encode does not (yet). UTF-7 is not supported.
The encoding is set using binmode on $fh.
If the handle was opened in a (correct) encoding, this method will not alter the encoding, as it checks the leading bytes of the first line.
This option offers the means to modify the column names into something that is most useful to the application. The default is to map all column names to lower case.
$csv->header ($fh, { munge_column_names => "lc" });The following values are available:
lc - lower case
uc - upper case
none - do not change
\&cb - supply a callback
$csv->header ($fh, { munge_column_names => sub { fc } });
$csv->header ($fh, { munge_column_names => sub { "column_".$col++ } });
$csv->header ($fh, { munge_column_names => sub { lc (shift =~ s/\W+/_/gr) } }); $csv->header ($fh, { set_column_names => 1 });The default is to set the instances column names using "column_names" if the method is successful, so subsequent calls to "getline_hr" can return a hash. Disable setting the header can be forced by using a false value for this option.