NAME

Text::BSV::BsvListReader - read BSV data from a list of strings containing the rows (without end-of-line characters), including the header row, and then turn the data into an array of field names plus one hash encapsulating each record.

SYNOPSIS

  use Text::BSV::BsvListReader;
  use Text::BSV::Exception;

  # Create a Text::BSV::BsvListReader instance:
  my $bsv_rows = $ARGV[0];
  my $bsv_list_reader;

  eval {
      $bsv_list_reader = Text::BSV::BsvListReader->new($bsv_rows);
  };

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

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

  # Get the records:
  my @records = @{ $bsv_list_reader->get_records() };

  # Do something with the records.

DESCRIPTION

This module defines a class for reading BSV data from a list of strings containing the rows (without end-of-line characters), including the header row, 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::BsvListReader->new() syntax, the constructor takes a reference to an array containing the BSV rows, including the header row, with no end-of-line characters.

The constructor returns a reference to a Text::BSV::BsvListReader 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::BsvListReader->new($bsv_rows);

This is the constructor. If the header row or the first record in the BSV data is not valid, the constructor throws an exception of type $Text::BSV::Exception::INVALID_DATA_FORMAT.

$bsv_list_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_list_reader->get_records();

Returns a reference to an array of hash references that encapsulate the BSV data records. The keys in each hash are the field names.

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.