NAME

TIGR::FASTA::Writer - TIGR::FASTA::Writer class for writing TIGR::FASTA::Record objects to a file

SYNOPSIS

  use TIGR::FASTA:Writer;
  my $obj_instance = new TIGR::FASTA::Writer ($tigr_foundation_obj,
                                              $output_file_name);

DESCRIPTION

This module provides an object definition for a TIGR::FASTA::Writer. The TIGR::FASTA::Writer object accepts TIGR::FASTA::Record objects for printing to an output file.

$obj_instance = new TIGR::FASTA::Writer ($foundation_object, $error_array_ref, $output_file);

This method returns a new instance of a TIGR::FASTA::Writer object. It takes three optional parameters: a TIGR::Foundation object ($foundation_object), a reference to an array for logging user error messages ($error_array_ref), and an output file name, $output_file, as parameters. A new object instance is returned on success and successful opening of a specified output file. If the file supplied cannot be opened, this method returns undefined. This method also returns undefined if the parameters supplied are invalid. Writing errors are written to the array at $error_array_ref and the log file.

$result = $obj_instance->open($file_name, $flag);

This method opens a FASTA file for writing or appending. The file, $file_name, is opened using the open() flags specified by $flag. Supported flags include 'w' and 'a'. On success, this method returns 1. The default open() method is 'w', or truncated open. If the file cannot be opened, this method returns undefined.

$result = $obj_instance->close();

This method closes the object file stream and resets all internal data structures. The result of the operation is returned. If the file stream is closed successfully, this object returns true (1), otherwise false (undefined).

$result = $obj_instance->write($fasta_obj);

This method takes a TIGR::FASTA::Record object, $fasta_obj, and writes it to the file specified in new() or open(). On success, this method returns true (1). On error, this method returns false (undefined) and logs an error message.

USAGE

To use this module, load the TIGR::FASTA::Record and TIGR::FASTA::Writer modules with the use function. Then, create a new instance of the object via the new() method, as shown below. There are several invocations possible for this method since all parameters to new() are optional. An example script using this module follows. The TIGR::Foundation module is included for completeness but does not have to be used.

   #!/usr/local/bin/perl -w

   # This example uses the TIGR::FASTA::Writer object to write 
   # a simple TIGR::FASTA::Record object to a file specified with
   # the '-o' option to this script.
   # Writing errors are collected to the '@errors_list' array.
 
   use strict;
   use TIGR::Foundation;
   use TIGR::FASTA::Record;
   use TIGR::FASTA::Writer;

   MAIN:
   {
      my $tf_object = new TIGR::Foundation;
      my @errors_list = ();
      my $output_file = undef;

      my $getopts_result = undef;

      $getopts_result = $tf_object->TIGR_GetOptions( "o=s" => \$output_file );
      
      if ( $getopts_result != 1 ) {
         $tf_object->bail("Invalid command line option.");
      }

      if ( ! defined ( $output_file ) ) {
         $tf_object->bail("Must specify an output file with the '-o' option");
      }

      my $header = "ORF00001";
      my $data = "ATGC";

      my $fasta_record = new TIGR::FASTA::Record $header, $data;
      if ( ! defined ( $fasta_record ) ) {
         $tf_object->bail("Cannot create TIGR::FASTA::Record object");
      }
      
      # Create a TIGR::FASTA::Writer instance using TIGR::Foundation and
      # an error message list.

      my $fasta_writer = new TIGR::FASTA::Writer $tf_object, \@errors_list;

      $fasta_writer->open($output_file) or 
         $tf_object->logLocal("Cannot open output file $output_file", 
                               $DEBUG_LEVEL_1);

      if ( scalar(@errors_list) > 0 ) { # are there parse errors?
         while ( @errors_list ) { # get the messages from the list
            my $message = shift @errors_list; 
            print STDERR $message, "\n";
         }
      }

      $fasta_writer->write($fasta_record ) or 
         $tf_object->logLocal("Cannot write FASTA record to $output_file", 
                               $DEBUG_LEVEL_1);
   }