NAME

Text::BSV::BsvWriter - generates BSV data from a list of field names and a list of references to hashes that encapsulate records. Provides a method for returning the BSV data as a reference to an array of strings, and a method for writing the BSV data to a file.

SYNOPSIS

  use Text::BSV::BsvWriter;
  use Text::BSV::Exception;

  # Create a Text::BSV::BsvWriter instance:
  my $bsv_writer;

  eval {
      $bsv_writer = Text::BSV::BsvWriter->new($field_names, $records);
  };

  if ($EVAL_ERROR) {
      if ($EVAL_ERROR->get_type()
        == $Text::BSV::Exception::ILLEGAL_ARGUMENT) {
          say STDERR "Bad arguments passed to the Text::BSV::BsvWriter "
            . "constructor:  " . $EVAL_ERROR->get_message();
          exit(1);
      }
      else {
          say STDERR "An unknown exception occurred:  "
            . $EVAL_ERROR->get_message();
          exit(1);
      } # end if
  } # end if

  # Write the BSV data generated by the constructor to a file:
  eval {
      $bsv_writer->write_to_file($file_path);
  };

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

  # Get the BSV data rows in case you want to do something with them other
  # than writing them to a file:
  my $rows = $bsv_writer->get_rows();

DESCRIPTION

This module defines a class for generating BSV data from a list of field names and a list of references to hashes that encapsulate records. The class provides a method for returning the BSV data as a reference to an array of strings, and a method for writing the BSV data to a file.

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::BsvWriter->new() syntax, the constructor takes a reference to an array of field names and a reference to an array of references to hashes encapsulating the records.

The constructor returns a reference to a Text::BSV::BsvWriter 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::BsvWriter->new($field_names, $records);

This is the constructor. If the field names are not unique or do not match the keys in each hash, or if there are not at least two fields and at least one record, the constructor throws an exception of type $Text::BSV::Exception::ILLEGAL_ARGUMENT.

$bsv_writer->get_rows();

Returns a reference to an array of rows (including the header row) that compose the BSV data. The rows returned by this method do not have any end-of-line characters added.

$bsv_writer->write_to_file();

Takes the path to a BSV file (which will be overwritten if it already exists) and writes the BSV data generated by the constructor to the file. If the file cannot be written to, the method throws an exception of type $Text::BSV::Exception::IO_ERROR.

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.