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 Text::BSV::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 ($Text::BSV::Exception::FILE_NOT_FOUND) {
              say STDERR "$DQ$bsv_file_path$DQ is not a valid file path.";
              exit(1);
          }
          when ($Text::BSV::Exception::IO_ERROR) {
              say STDERR "Couldn't open $DQ$bsv_file_path$DQ for reading.";
              exit(1);
          }
          when ($Text::BSV::Exception::INVALID_DATA_FORMAT) {
              say STDERR "Invalid BSV data:  " . $exception->get_message();
              exit(1);
          }
          default {
              say STDERR $exception->get_message();
              exit(1);
          } # 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 Text::BSV::Exception module for error
  handling.  When an error occurs during the execution of a method
  (including the constructor), the method creates a new
  Text::BSV::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 Text::BSV::Exception.

PREREQUISITES

This module requires Perl 5 (version 5.10.1 or later), the Text::BSV::BsvParsing module, and the Text::BSV::Exception module.

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 $Text::BSV::Exception::FILE_NOT_FOUND. If the file cannot be opened for reading, the constructor throws an exception of type $Text::BSV::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 $Text::BSV::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 $Text::BSV::Exception::UNSUPPORTED_OPERATION. If the BSV data in the next record is not valid, this method throws an exception of type $Text::BSV::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.