use Text::CSV_XS qw( csv );
  my $aoa = csv (in => "file.csv");

##</code><code>##

  my $aoa = csv (in => "file.csv", sep_char => ";");

##</code><code>##

  my $aoa = csv (in => "file.csv", sep => ";");

##</code><code>##

  use autodie;
  use Text::CSV_XS;

  my $csv = Text::CSV_XS->new (
      binary    => 1,
      auto_diag => 1,
      sep_char  => ";",
      });
  open my $fh, "<", "file.csv";
  while (my $row = $csv->getline ($fh)) {
      # do something with the row
      }
  close $fh;

##</code><code>##

  # Default: return a list of lists (rows)
  my $aoa = csv (in => "file.csv");

  # Using the header line: return a list of hashes (records)
  my $aoh = csv (in => "file.csv", headers => "auto");

##</code><code>##

  open my $fh, "<", "file.csv";
  my @hdr = @{$csv->getline ($fh)};
  $csv->column_names (@hdr);
  while (my $row = $csv->getline_hr ($fh)) {
      ...

##</code><code>##

  open my $fh, "<", "file.csv";
  my @hdr = @{$csv->getline ($fh)};
  $csv->column_names (@hdr);
  while (my $row = $csv->getline_hr ($fh)) {

##</code><code>##

  open my $fh, "<", "file.csv";
  my @hdr = $csv->header ($fh);
  $csv->column_names (@hdr);
  while (my $row = $csv->getline_hr ($fh)) {

##</code><code>##

sub Text::CSV_XS::header {
    my ($csv, $fh, $seps) = @_;
    my $hdr = lc <$fh> or return;
    foreach my $sep (@{$seps || [ ";", "," ]}) {
        index $hdr, $sep < 0 and next;
        $csv->sep_char ($sep);
        last;
        }
    open my $h, "<", \$hdr;
    my $row = $csv->getline ($h);
    close $h;
    @{$row // []};
    } # Text::CSV_XS::header

##</code><code>##

=head2 $csv->header ($fh)

Return the CSV header and set C<sep_char>.

  my @hdr = $csv->header ($fh);
  my @hdr = $csv->header ($fh, [ ";", ",", "|", "\t" ]);

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, auto-detect whether the header
separates the column names with a character from the allowed separator
list. That list defaults to C<[ ";", "," ]> and can be overruled with
an optional second argument. If any of the allowed separators matches
(checks are done in order), set C<sep_char> to that sequence for the
current CSV_XS instance and use it to parse the first line and return
it as an array where all fields are mapped to lower case:

 my $csv = Text::CSV_XS->new ({ binary => 1, auto_diag => 1 });
 open my $fh, "<:encoding(iso-8859-1)", "file.csv";
 my @hdr = $csv->header ($fh) or die "file.csv has no header line\n";
 # $csv now has the correct sep_char
 while (my $row = $csv->getline ($fh)) {
     ...
     }

##</code><code>##


  #---
  my $data = "foo,bar\r\n1,baz\r\n";
  open my $fh, "<", \$data;

  my @hdr = $csv->header ($fh); # ("foo", "bar")
  while (my $row = $csv->getline ($fh)) {
      # $row = [ "1", "baz" ]

  #---
  my $data = "foo;bar\r\n1;baz\r\n";
  open my $fh, "<", \$data;

  my @hdr = $csv->header ($fh); # ("foo", "bar")
  $csv->column_names (@hdr);
  while (my $row = $csv->getline_hr ($fh)) {
      # $row = { foo => "1", bar => "baz" }

  #---
  my $data = "foo|bar\r\n1|baz\r\n";
  open my $fh, "<", \$data;

  $csv->column_names ($csv->header ($fh, [ ";", ",", "|" ]));
  while (my $row = $csv->getline_hr ($fh)) {
      # $row = { foo => "1", bar => "baz" }