package Text::CSV;

# Copyright (c) 1997 Alan Citterman. All rights reserved.

# This program is free software; you can redistribute it and/or

# modify it under the same terms as Perl itself.

################################################################################

# HISTORY

#

# Written by:

#    Alan Citterman <alan@mfgrtl.com>

#

# Version 0.01  06/05/1997

#    original version

################################################################################

require 5.002;

use strict;

BEGIN {

  use Exporter   ();

  use AutoLoader qw(AUTOLOAD);

  use vars       qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);

  $VERSION =     '0.01';

  @ISA =         qw(Exporter AutoLoader);

  @EXPORT =      qw();

  @EXPORT_OK =   qw();

  %EXPORT_TAGS = qw();

}

1;

__END__

################################################################################

# version

#

#    class/object method expecting no arguments and returning the version number

#    of Text::CSV.  there are no side-effects.

################################################################################

sub version {

  return $VERSION;

}

################################################################################

# new

#

#    class/object method expecting no arguments and returning a reference to a

#    newly created Text::CSV object.

################################################################################

sub new {

  my $proto = shift;

  my $class = ref($proto) || $proto;

  my $self = {};

  $self->{'_STATUS'} = undef;

  $self->{'_ERROR_INPUT'} = undef;

  $self->{'_STRING'} = undef;

  $self->{'_FIELDS'} = undef;

  bless $self, $class;

  return $self;

}

################################################################################

# status

#

#    object method returning the success or failure of the most recent combine()

#    or parse().  there are no side-effects.

################################################################################

sub status {

  my $self = shift;

  return $self->{'_STATUS'};

}

################################################################################

# error_input

#

#    object method returning the first invalid argument to the most recent

#    combine() or parse().  there are no side-effects.

################################################################################

sub error_input {

  my $self = shift;

  return $self->{'_ERROR_INPUT'};

}

################################################################################

# string

#

#    object method returning the result of the most recent combine() or the

#    input to the most recent parse(), whichever is more recent.  there are no

#    side-effects.

################################################################################

sub string {

  my $self = shift;

  return $self->{'_STRING'};

}

################################################################################

# fields

#

#    object method returning the result of the most recent parse() or the input

#    to the most recent combine(), whichever is more recent.  there are no

#    side-effects.

################################################################################

sub fields {

  my $self = shift;

  if (ref($self->{'_FIELDS'})) {

    return @{$self->{'_FIELDS'}};

  }

  return undef;

}

################################################################################

# combine

#

#    object method returning success or failure.  the given arguments are

#    combined into a single comma-separated value.  failure can be the result of

#    no arguments or an argument containing an invalid character.   side-effects

#    include:

#      setting status()

#      setting fields()

#      setting string()

#      setting error_input()

################################################################################

sub combine {

  my $self = shift;

  my @part = @_;

  $self->{'_FIELDS'} = \@part;

  $self->{'_ERROR_INPUT'} = undef;

  $self->{'_STATUS'} = 0;

  $self->{'_STRING'} = '';

  my $column = '';

  my $combination = '';

  my $skip_comma = 1;

  if ($#part >= 0) {

    # at least one argument was given for "combining"...

    for $column (@part) {

      if ($column =~ /[^\t\040-\176]/) {

	# an argument contained an invalid character...

	$self->{'_ERROR_INPUT'} = $column;

	return $self->{'_STATUS'};

      }

      if ($skip_comma) {

	# do not put a comma before the first argument...

	$skip_comma = 0;

      } else {

	# do put a comma before all arguments except the first argument...

	$combination .= ',';

      }

      $column =~ s/\042/\042\042/go;

      $combination .= "\042";

      $combination .= $column;

      $combination .= "\042";

    }

    $self->{'_STRING'} = $combination;

    $self->{'_STATUS'} = 1;

  }

  return $self->{'_STATUS'};

}

################################################################################

# parse

#

#    object method returning success or failure.  the given argument is expected

#    to be a valid comma-separated value.  failure can be the result of

#    no arguments or an argument containing an invalid sequence of characters.

#    side-effects include:

#      setting status()

#      setting fields()

#      setting string()

#      setting error_input()

################################################################################

sub parse {

  my $self = shift;

  $self->{'_STRING'} = shift;

  $self->{'_FIELDS'} = undef;

  $self->{'_ERROR_INPUT'} = $self->{'_STRING'};

  $self->{'_STATUS'} = 0;

  if (!defined($self->{'_STRING'})) {

    return $self->{'_STATUS'};

  }

  my $keep_biting = 1;

  my $palatable = 0;

  my $line = $self->{'_STRING'};

  if ($line =~ /\n$/) {

    chop($line);

    if ($line =~ /\r$/) {

      chop($line);

    }

  }

  my $mouthful = '';

  my @part = ();

  while ($keep_biting and ($palatable = $self->_bite(\$line, \$mouthful, \$keep_biting))) {

    push(@part, $mouthful);

  }

  if ($palatable) {

    $self->{'_ERROR_INPUT'} = undef;

    $self->{'_FIELDS'} = \@part;

  }

  return $self->{'_STATUS'} = $palatable;

}

################################################################################

# _bite

#

#    *private* class/object method returning success or failure.  the arguments

#    are:

#      - a reference to a comma-separated value string

#      - a reference to a return string

#      - a reference to a return boolean

#    upon success the first comma-separated value of the csv string is

#    transferred to the return string and the boolean is set to true if a comma

#    followed that value.  in other words, "bite" one value off of csv

#    returning the remaining string, the "piece" bitten, and if there's any

#    more.  failure can be the result of the csv string containing an invalid

#    sequence of characters.

#   

#    from the csv string and 

#    to be a valid comma-separated value.  failure can be the result of

#    no arguments or an argument containing an invalid sequence of characters.

#    side-effects include:

#      setting status()

#      setting fields()

#      setting string()

#      setting error_input()

################################################################################

sub _bite {

  my ($self, $line_ref, $piece_ref, $bite_again_ref) = @_;

  my $in_quotes = 0;

  my $ok = 0;

  $$piece_ref = '';

  $$bite_again_ref = 0;

  while (1) {

    if (length($$line_ref) < 1) {

      # end of string...

      if ($in_quotes) {

	# end of string, missing closing double-quote...

	last;

      } else {

	# proper end of string...

	$ok = 1;

	last;

      }

    } elsif ($$line_ref =~ /^\042/) {

      # double-quote...

      if ($in_quotes) {

	if (length($$line_ref) == 1) {

	  # closing double-quote at end of string...

	  substr($$line_ref, 0, 1) = '';

	  $ok = 1;

	  last;

	} elsif ($$line_ref =~ /^\042\042/) {

	  # an embedded double-quote...

	  $$piece_ref .= "\042";

	  substr($$line_ref, 0, 2) = '';

	} elsif ($$line_ref =~ /^\042,/) {

	  # closing double-quote followed by a comma...

	  substr($$line_ref, 0, 2) = '';

	  $$bite_again_ref = 1;

	  $ok = 1;

	  last;

	} else {

	  # double-quote, followed by undesirable character (bad character sequence)...

	  last;

	}

      } else {

	if (length($$piece_ref) < 1) {

	  # starting double-quote at beginning of string

	  $in_quotes = 1;

	  substr($$line_ref, 0, 1) = '';

	} else {

	  # double-quote, outside of double-quotes (bad character sequence)...

	  last;

	}

      }

    } elsif ($$line_ref =~ /^,/) {

      # comma...

      if ($in_quotes) {

	# a comma, inside double-quotes...

	$$piece_ref .= substr($$line_ref, 0 ,1);

	substr($$line_ref, 0, 1) = '';

      } else {

	# a comma, which separates values...

	substr($$line_ref, 0, 1) = '';

	$$bite_again_ref = 1;

	$ok = 1;

	last;

      }

    } elsif ($$line_ref =~ /^[\t\040-\176]/) {

      # a tab, space, or printable...

      $$piece_ref .= substr($$line_ref, 0 ,1);

      substr($$line_ref, 0, 1) = '';

    } else {

      # an undesirable character...

      last;

    }

  }

  return $ok;

}

=head1 NAME

Text::CSV - comma-separated values manipulation routines

=head1 SYNOPSIS

 use Text::CSV;

 $version = Text::CSV->version();      # get the module version

 $csv = Text::CSV->new();              # create a new object

 $status = $csv->combine(@columns);    # combine columns into a string

 $line = $csv->string();               # get the combined string

 $status = $csv->parse($line);         # parse a CSV string into fields

 @columns = $csv->fields();            # get the parsed fields

 $status = $csv->status();             # get the most recent status

 $bad_argument = $csv->error_input();  # get the most recent bad argument

=head1 DESCRIPTION

Text::CSV provides facilities for the composition and decomposition of

comma-separated values.  An instance of the Text::CSV class can combine

fields into a CSV string and parse a CSV string into fields.

=head1 FUNCTIONS

=over 4

=item version

 $version = Text::CSV->version();

This function may be called as a class or an object method.  It returns the current

module version.

=item new

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

This function may be called as a class or an object method.  It returns a reference to a

newly created Text::CSV object.

=item combine

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

This object function constructs a CSV string from the arguments, returning

success or failure.  Failure can result from lack of arguments or an argument

containing an invalid character.  Upon success, C<string()> can be called to

retrieve the resultant CSV string.  Upon failure, the value returned by

C<string()> is undefined and C<error_input()> can be called to retrieve an

invalid argument.

=item string

 $line = $csv->string();

This object function returns the input to C<parse()> or the resultant CSV string of

C<combine()>, whichever was called more recently.

=item parse

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

This object function 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, C<fields()> can be called to

retrieve the decomposed fields .  Upon failure, the value returned by

C<fields()> is undefined and C<error_input()> can be called to retrieve the

invalid argument.

=item fields

 @columns = $csv->fields();

This object function returns the input to C<combine()> or the resultant decomposed

fields of C<parse()>, whichever was called more recently.

=item status

 $status = $csv->status();

This object function returns success (or failure) of C<combine()> or C<parse()>,

whichever was called more recently.

=item error_input

 $bad_argument = $csv->error_input();

This object function returns the erroneous argument (if it exists) of C<combine()>

or C<parse()>, whichever was called more recently.

=back

=head1 EXAMPLE

  require Text::CSV;

  my $csv = Text::CSV->new;

  my $column = '';

  my $sample_input_string = '"I said, ""Hi!""",Yes,"",2.34,,"1.09"';

  if ($csv->parse($sample_input_string)) {

    my @field = $csv->fields;

    my $count = 0;

    for $column (@field) {

      print ++$count, " => ", $column, "\n";

    }

    print "\n";

  } else {

    my $err = $csv->error_input;

    print "parse() failed on argument: ", $err, "\n";

  }

  my @sample_input_fields = ('You said, "Hello!"',

			     5.67,

			     'Surely',

			     '',

			     '3.14159');

  if ($csv->combine(@sample_input_fields)) {

    my $string = $csv->string;

    print $string, "\n";

  } else {

    my $err = $csv->error_input;

    print "combine() failed on argument: ", $err, "\n";

  }

=head1 CAVEATS

This module is based upon a working definition of CSV format which may not be

the most general.

=over 4

=item 1 

Allowable characters within a CSV field include 0x09 (tab) and the inclusive

range of 0x20 (space) through 0x7E (tilde).

=item 2

A field within CSV may be surrounded by double-quotes.

=item 3

A field within CSV must be surrounded by double-quotes to contain a comma.

=item 4

A field within CSV must be surrounded by double-quotes to contain an embedded

double-quote, represented by a pair of consecutive double-quotes.

=item 5

A CSV string may be terminated by 0x0A (line feed) or by 0x0D,0x0A

(carriage return, line feed).

=head1 AUTHOR

Alan Citterman F<E<lt>alan@mfgrtl.comE<gt>>

=head1 SEE ALSO

perl(1)

=cut