Bio/Factory/SeqAnalysisParserFactory.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Factory::SeqAnalysisParserFactory
   4 #
   5 # Cared for by Jason Stajich <jason@bioperl.org>,
   6 # and Hilmar Lapp <hlapp@gmx.net>
   7 #
   8 # Copyright Jason Stajich, Hilmar Lapp
   9 #
  10 # You may distribute this module under the same terms as perl itself
  11
  12 # POD documentation - main docs before the code
  13
  14 =head1 NAME
  15
  16 Bio::Factory::SeqAnalysisParserFactory - class capable of creating
  17 SeqAnalysisParserI compliant parsers
  18
  19 =head1 SYNOPSIS
  20
  21     # initialize an object implementing this interface, e.g.
  22     $factory = Bio::Factory::SeqAnalysisParserFactory->new();
  23     # find out the methods it knows about
  24     print "registered methods: ",
  25           join(', ', keys %{$factory->driver_table}), "\n";
  26     # obtain a parser object
  27     $parser = $factory->get_parser(-input=>$inputobj,
  28                                    -params=>[@params],
  29                                    -method => $method);
  30     # $parser is an object implementing Bio::SeqAnalysisParserI
  31     # annotate sequence with features produced by parser
  32     while(my $feat = $parser->next_feature()) {
  33         $seq->add_SeqFeature($feat);
  34     }
  35
  36 =head1 DESCRIPTION
  37
  38 This is a factory class capable of instantiating SeqAnalysisParserI
  39 implementing parsers.
  40
  41 The concept behind this class and the interface it implements
  42 (Bio::Factory::SeqAnalysisParserFactoryI) is a generic analysis result
  43 parsing in high-throughput automated sequence annotation
  44 pipelines. See Bio::SeqAnalysisParserI for more documentation of this
  45 concept.
  46
  47 You can always find out the methods an instance of this class knows
  48 about by the way given in the SYNOPSIS section. By default, and
  49 assuming that the documentation is up-to-date, this will comprise of
  50 genscan, mzef, estscan, blast, hmmer, gff, and sim4 (all
  51 case-insensitive).
  52
  53 =head1 FEEDBACK
  54
  55 =head2 Mailing Lists
  56
  57 User feedback is an integral part of the evolution of this
  58 and other Bioperl modules. Send your comments and suggestions preferably
  59  to one of the Bioperl mailing lists.
  60 Your participation is much appreciated.
  61
  62   bioperl-l@bioperl.org                  - General discussion
  63   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  64
  65 =head2 Reporting Bugs
  66
  67 Report bugs to the Bioperl bug tracking system to help us keep track
  68 the bugs and their resolution.  Bug reports can be submitted via the
  69 web:
  70
  71   http://bugzilla.open-bio.org/
  72
  73 =head1 AUTHOR - Hilmar Lapp, Jason Stajich
  74
  75 Email Hilmar Lapp E<lt>hlapp@gmx.netE<gt>, Jason Stajich E<lt>jason@bioperl.orgE<gt>
  76
  77 =head1 APPENDIX
  78
  79 The rest of the documentation details each of the object
  80 methods. Internal methods are usually preceded with a _
  81
  82 =cut
  83
  84 package Bio::Factory::SeqAnalysisParserFactory;
  85 use strict;
  86
  87
  88 use base qw(Bio::Factory::DriverFactory Bio::Factory::SeqAnalysisParserFactoryI);
  89
  90 BEGIN {
  91     Bio::Factory::DriverFactory->register_driver
  92         (
  93          "genscan"   => "Bio::Tools::Genscan",
  94          "mzef"      => "Bio::Tools::MZEF",
  95          "estscan"   => "Bio::Tools::ESTScan",
  96          "hmmer"     => "Bio::Tools::HMMER::Result",
  97          "gff"       => "Bio::Tools::GFF",
  98          "sim4"      => "Bio::Tools::Sim4::Results",
  99          "epcr"      => "Bio::Tools::EPCR",
 100          "exonerate" => "Bio::Tools::Exonerate",
 101          );
 102 }
 103
 104 sub new {
 105     my ($class, @args) = @_;
 106     my $self = $class->SUPER::new(@args);
 107
 108     # no per-object initialization right now - registration of default drivers
 109     # is only done once when the module is loaded
 110     return $self;
 111 }
 112
 113 =head2 get_parser
 114
 115  Title   : get_parser
 116  Usage   : $factory->get_parser(-input=>$inputobj,
 117                                 [ -params=>[@params] ],
 118                                 -method => $method)
 119  Function: Creates and returns a parser object for the given input and method.
 120            Both file names and streams (filehandles) are allowed.
 121
 122            Parameters (-params argument) are passed on to the parser object
 123            and therefore are specific to the parser to be created.
 124  Example :
 125  Returns : A Bio::SeqAnalysisParserI implementing object. Exception if
 126            creation of the parser object fails.
 127  Args    : B<input>  - object/file where analysis results are coming from,
 128            B<params> - parameter to use when parsing/running analysis
 129            B<method> - method of analysis
 130
 131 =cut
 132
 133 sub get_parser {
 134     my ($self, @args) = @_;
 135     my $parser;
 136     my $module;
 137
 138     my ($input, $params, $method) =
 139         $self->_rearrange([qw(INPUT PARAMS METHOD)], @args);
 140
 141     # retrieve module name for requested method
 142     $method = lc $method; # method is case-insensitive
 143     $module = $self->get_driver($method);
 144     if(! defined($module)) {
 145         $self->throw("Analysis parser driver for method $method not registered.");
 146     }
 147     # load module
 148     $self->_load_module($module); # throws an exception on failure to load
 149     # make sure parameters is not undef
 150     $params = [] if( !defined $params );
 151     # figure out input method (file or stream)
 152     my $inputmethod = '-file';
 153     if( ref($input) =~ /GLOB/i ) {
 154         $inputmethod = '-fh';
 155     }
 156     # instantiate parser and return the result
 157     $parser = $module->new($inputmethod => $input, @$params);
 158     if(! $parser->isa('Bio::SeqAnalysisParserI')) {
 159         $self->throw("Driver $module registered for method $method does not ".
 160                      "implement Bio::SeqAnalyisParserI. How come?");
 161     }
 162     return $parser;
 163 }
 164
 165
 166 =head2 register_driver
 167
 168  Title   : register_driver
 169  Usage   : $factory->register_driver("genscan", "Bio::Tools::Genscan");
 170  Function: Registers a driver a factory class should be able to instantiate.
 171
 172            This method can be called both as an instance and as a
 173            class method.
 174
 175  Returns :
 176  Args    : Key of the driver (string) and the module implementing the driver
 177            (string).
 178
 179 =cut
 180
 181 =head2 driver_table
 182
 183  Title   : driver_table
 184  Usage   : $table = $factory->driver_table();
 185  Function: Returns a reference to the hash table storing associations of
 186            methods with drivers.
 187
 188            You use this table to look up registered methods (keys) and
 189            drivers (values).
 190
 191            In this implementation the table is class-specific and
 192            therefore shared by all instances. You can override this in
 193            a derived class, but note that this method can be called
 194            both as an instance and a class method.
 195
 196            This will be the table used by the object internally. You
 197            should definitely know what you're doing if you modify the
 198            table's contents.  Modifications are shared by _all_
 199            instances, those present and those yet to be created.
 200
 201  Returns : A reference to a hash table.
 202  Args    :
 203
 204
 205 =cut
 206
 207
 208 1;