NAME

TIGR::FASTA::Reader - TIGR::FASTA::Reader class for parsing and navigating FASTA format files.

SYNOPSIS

   use TIGR::FASTA::Reader;  
   my $obj_instance = new TIGR::FASTA::Reader ($foundation_obj_ref, 
                      $error_array_ref, $fasta_file_name);

DESCRIPTION

This module iterates over a FASTA formatted database file. It provides data extraction and simple analysis routines. This module utilizes acceptance validation of FASTA formatted files via the TIGR::FASTA::Grammar module.

$obj_instance = new TIGR::FASTA::Reader ($foundation_object, $error_array_ref, $db_file);

This method returns a new instance of a TIGR::FASTA::Reader 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 FASTA file ($db_file). The new instance is returned on success. If the file supplied cannot be opened or is invalid, this method returns undefined. This method also returns undefined if the parameters supplied are invalid. Errors in parsing 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 reading. This method also parses the file for correctness. The file, $file_name, is opened using the open() flags specified by $flag. On success, this method returns 1. If the file cannot be opened or parsing fails, 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).

$record_num = $obj_instance->index();

This method returns the record number of the active record. If no record has been selected (ie. made active), then this method returns undefined. If the active record pointer is before the first record, this method returns '-1'.

$result = $obj_instance->seekIndex($num);

This method selects a record by record order index. The $num ordered record is selected. If $num is out of range for the database or not -1 (indicating to seek one record before the first record), this function returns undefined and the active record pointer is not changed. Otherwise, the requested record is made active and the method returns 1.

$result = $obj_instance->next();

This method selects the next record in numerical order to be the active record. It returns the record on success, undefined on failure. If the active record is equal to -1, the first record is selected.

$result = $obj_instance->hasNext();

This method returns true (1) if there are more elements beyond the current element. If not, this method returns false (undefined).

$result = $obj_instance->getRecordByIdentifier($identifier);

This method selects a record by record minimal identifier. If $identifier does not exist in the set of records, this function returns undefined and the previously active record remains active. Otherwise, the requested record is made active and the method returns a TIGR::FASTA::Record object representation of the current(active) record.

$result = $obj_instance->seekIdentifier($identifier);

This method selects a record by record minimal identifier. If $identifier does not exist in the set of records, this function returns undefined and the previously active record remains active. Otherwise, the requested record is made active and the method returns 1.

$record_contents = $obj_instance->get();

This method returns a TIGR::FASTA::Record object representation of the current (active) record. If no defined record is active, this method returns undefined.

$db_name = $obj_instance->path();

This method returns the path to the file used for processing.

$cnt = $obj_instance->count();

This method returns the number of records in the database file.

USAGE

To use this module, load the TIGR::FASTA::Reader package via 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. To access records from the TIGR::FASTA::Reader instance, the TIGR::FASTA::Record package must be loaded via the use function. 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 script accepts FASTA files with the '-i' option
   # on the command line and validates every one in turn.
   # Parse errors are collected to the '@errors_list' array.
   # This program concatenates all of the records together to 
   # one output file specified with the '-o' option.
   # NOTE: The '-i' option must be specified before every input file.
   # NOTE: The 'TIGR::FASTA::Writer' module is intended for writing 
   #       FASTA records.

   use strict;
   use TIGR::FASTA::Reader;
   use TIGR::FASTA::Record;

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

      # Capture the return code from the TIGR::Foundation method
      my $result = $tf_object->TIGR_GetOptions('i=s' => \@input_files,
                                               'o=s' => \$output_file);
      if ( $result != 1 ) {
         $tf_object->bail("Invalid command line options.");
      }

      # Create a TIGR::FASTA::Reader instance using TIGR::Foundation and
      # an error message list.
      my $fasta_reader = new TIGR::FASTA::Reader $tf_object, \@errors_list;

      if ( !(  defined ( $output_file ) &&
               open OUTFILE, ">$output_file" ) ) {
         $tf_object->bail("Cannot open output file for writing.");
      }

      foreach my $in_file ( @input_files ) {
         $fasta_reader->open($in_file) or
            $tf_object->logLocal("Cannot open or read file $in_file", 2);

         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";
            }
         }

         while ( $fasta_reader->hasNext() ) {
            # print each record to OUTFILE
            print OUTFILE $fasta_reader->next()->toString();
         }
      }
   }