NAME

Text::BSV::BsvFileReader - read BSV data from a file and then turn the data into an array of field names plus one hash encapsulating each record.

SYNOPSIS

  use Text::BSV::BsvFileReader;
  use Exception;

  # Constants:
  my $DQ = "\"";

  # Create a Text::BSV::BsvFileReader instance:
  my $bsv_file_path = $ARGV[0];
  my $bsv_file_reader;

  eval {
      $bsv_file_reader = Text::BSV::BsvFileReader->new($bsv_file_path);
  };

  if ($EVAL_ERROR) {
      my $exception = $EVAL_ERROR;

      given ($exception->get_type()) {
          when ($Exception::FILE_NOT_FOUND) {
              say STDERR "$DQ$bsv_file_path$DQ is not a valid file path.";
              exit(1);
          }
          when ($Exception::IO_ERROR) {
              say STDERR "Couldn't open $DQ$bsv_file_path$DQ for reading.";
              exit(1);
          }
          when ($Exception::INVALID_DATA_FORMAT) {
              say STDERR "Invalid BSV data:  " . $exception->get_message();
              exit(1);
          }
          default {
              say STDERR $exception->get_message();
          } # end when
      } # end given
  } # end if

  # Get the field names:
  my @field_names = @{ $bsv_file_reader->get_field_names() };

  # Get the records:
  my @records;

  while ($bsv_file_reader->has_next()) {
      eval {
          push @records, $bsv_file_reader->get_record();
      };

      if ($EVAL_ERROR) {
          say STDERR $EVAL_ERROR->get_message();
          exit(1);
      } # end if
  } # end while

  # Close the connection to the underlying BSV file:
  $bsv_file_reader->close();

  # Do something with the records.

DESCRIPTION

This module defines a class for reading BSV data from a file and then turning the data into an array of field names plus one hash encapsulating each record.

For a complete specification of the BSV (Bar-Separated Values) format, see bsv_format.txt.

In addition to the class-name argument, which is passed in automatically when you use the Text::BSV::BsvFileReader->new() syntax, the constructor takes a string containing the path to a BSV file.

The constructor returns a reference to a Text::BSV::BsvFileReader object, which is implemented internally as a hash. All functionality is exposed through methods.

  NOTE:  This module uses the Exception module for error handling.  When an
  error occurs during the execution of a method (including the constructor),
  the method creates a new Exception object of the appropriate type and then
  passes it to "die".  When you call the constructor or a method documented
  to throw an exception, do so within an "eval" statement and then query
  $EVAL_ERROR ($@) to catch any exceptions that occurred.  For more
  information, see the documentation for Exception.pm (included with the
  distribution at the top level of the lib directory).

PREREQUISITES

This module requires Perl 5, version 5.10.1 or later, and the Exception module (which is included with the distribution at the top level of the lib directory).

METHODS

Text::BSV::BsvFileReader->new($bsv_file_path);

This is the constructor. If the specified file does not exist, the constructor throws an exception of type $Exception::FILE_NOT_FOUND. If the file cannot be opened for reading, the constructor throws an exception of type $Exception::IO_ERROR. If the header row or the first non-header row in the BSV data is not valid, the constructor throws an exception of type $Exception::INVALID_DATA_FORMAT.

$bsv_file_reader->get_field_names();

Returns a reference to an array containing the field names, preserving the order in which they appear in the BSV data.

$bsv_file_reader->has_next();

Returns a Boolean value indicating whether there is a next record available.

$bsv_file_reader->get_record();

Returns a reference to a hash encapsulating the next record. The keys are the field names, and the values are the field values for the record encapsulated by the hash.

If there is no next record, this method throws an exception of type $Exception::UNSUPPORTED_OPERATION. If the BSV data in the next record is not valid, this method throws an exception of type $Exception::INVALID_DATA_FORMAT.

$bsv_file_reader->close();

Closes the connection to the underlying BSV file.

AUTHOR

Benjamin Fitch, <blernflerkl@yahoo.com>

COPYRIGHT AND LICENSE

Copyright 2010 by Benjamin Fitch.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.