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 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 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::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 $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.