view release on metacpan or  search on metacpan

lib/File/Text/CSV.pm  view on Meta::CPAN

  $out->write( [ '13:21', 'root', 24 ] );
  $out->write( { Time => '15:43', User => 'me', Amount => 42 } );
  $out->close;

=head1 DESCRIPTION

File::Text::CSV is like many other CSV processing modules, but it
focuses on the file side.

CSV data is a file data format, so in practice one has to work with a
file, reading lines, then unpacking the data from the lines using some
other module, and so on. This module combines all that.

It uses Text::CSV_XS to handle the CSV details.

File::Text::CSV requires all rows of the CSV data to have the same
number of columns.

=cut

package File::Text::CSV;

use strict;
use warnings;
use Carp;
use Encode;

our $VERSION = "0.02";

use parent qw( Text::CSV_XS );	# it's safe to use Text::CSV instead

=head1 METHODS

=over

=item open

  $csv = File::Text::CSV::->open( $file, $opts )

B<open> creates a new File::CSV object associated with an input file.

The named file is opened and available for further processing.

The second parameter is a hashref with options. You can pass all
Text::CSV options here.

Additional options specific to this function:

=over

=item header

If present, it must be either an arrayref with column names, or a
truth value. If the latter value is true, the column names are read
from the first row of the CSV file.

=item encoding

Encoding to open the file with. Default encoding is UTF-8, unless
header processing is enabled and the file starts with a byte order
mark (BOM).

=item append

If true, new records written will be appended to the file.

=back

=cut

sub open {
    my ( $pkg, $file, $opts ) = @_;

    # Private options.
    my $header = delete $opts->{header};
    my $append = delete $opts->{append};
    my $encoding = delete $opts->{encoding};

    # Default options.
    $opts->{binary} = 1 unless exists $opts->{binary};

    # Create the object.
    my $self = $pkg->SUPER::new( $opts );
    croak( $pkg->SUPER::error_diag ) unless $self;

    # Open the file.
    if ( $file eq "-" ) {
	croak("Cannot append to standard input") if $append;
	$self->{_fh} = \*STDIN;
    }
    else {
	my $mode = $append ? '+<' : '<';
	CORE::open( $self->{_fh}, $mode, $file )
	  or croak( "$file: $!" );
	$self->{_append} = $append;
    }

    # If header is an aref, it should contain the fields.
    my $encset;
    if ( $header ) {
	if ( eval { $header->[0] || 1 } ) {
	    $self->{_column_names} = $header;
	    $self->{_columns} = @$header;
	    $self->column_names( @$header );
	}
	# Otherwise, if set, a file header is mandatory.
	elsif ( $encoding ) {
	    $self->{_fh}->binmode("encoding($encoding)");
	    $encset++;
	    my $res = $self->getline( $self->{_fh} );
	    croak( "Incomplete or missing header line" ) unless $res;
	    croak( "Incomplete or missing header line" )
	      if @$res == 1 && $res->[0] eq '';	# empty line
	    $self->{_column_names} = $res;
	    $self->{_columns} = @$res;
	    $self->column_names( @$res );
	}
	else {
	    my $line = readline($self->{_fh});
	    if ( $line ) {
		if ( $line =~ /^\x{ff}\x{fe}\0\0(.*)/s ) {