Bio/MapIO.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::MapIO
   4 #
   5 # Cared for by Jason Stajich <jason@bioperl.org>
   6 #
   7 # Copyright Jason Stajich
   8 #
   9 # You may distribute this module under the same terms as perl itself
  10
  11 # POD documentation - main docs before the code
  12
  13 =head1 NAME
  14
  15 Bio::MapIO - A Map Factory object
  16
  17 =head1 SYNOPSIS
  18
  19     use Bio::MapIO;
  20     my $mapio = Bio::MapIO->new(-format => "mapmaker",
  21                                -file   => "mapfile.map");
  22
  23     while( my $map = $mapio->next_map ) {
  24         # get each map
  25         foreach my $marker ( $map->each_element ) {
  26             # loop through the markers associated with the map
  27         }
  28     }
  29
  30 =head1 DESCRIPTION
  31
  32 This is the Factory object for reading Maps from a data stream or file.
  33
  34 =head1 FEEDBACK
  35
  36 =head2 Mailing Lists
  37
  38 User feedback is an integral part of the evolution of this and other
  39 Bioperl modules. Send your comments and suggestions preferably to
  40 the Bioperl mailing list.  Your participation is much appreciated.
  41
  42   bioperl-l@bioperl.org                  - General discussion
  43   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  44
  45 =head2 Reporting Bugs
  46
  47 Report bugs to the Bioperl bug tracking system to help us keep track
  48 of the bugs and their resolution. Bug reports can be submitted the web:
  49
  50   http://bugzilla.open-bio.org/
  51
  52 =head1 AUTHOR - Jason Stajich
  53
  54 Email jason@bioperl.org
  55
  56 =head1 APPENDIX
  57
  58 The rest of the documentation details each of the object methods.
  59 Internal methods are usually preceded with a _
  60
  61 =cut
  62
  63
  64 # Let the code begin...
  65
  66
  67 package Bio::MapIO;
  68 use strict;
  69
  70
  71 use base qw(Bio::Root::Root Bio::Root::IO Bio::Factory::MapFactoryI);
  72
  73 =head2 new
  74
  75  Title   : new
  76  Usage   : my $obj = Bio::MapIO->new();
  77  Function: Builds a new Bio::MapIO object
  78  Returns : Bio::MapIO
  79  Args    :
  80
  81
  82 =cut
  83
  84 sub new {
  85   my($caller,@args) = @_;
  86
  87   my $class = ref($caller) || $caller;
  88
  89   # or do we want to call SUPER on an object if $caller is an
  90   # object?
  91   if( $class =~ /Bio::MapIO::(\S+)/ ) {
  92         my ($self) = $class->SUPER::new(@args);
  93         $self->_initialize(@args);
  94         return $self;
  95     } else {
  96
  97         my %param = @args;
  98         @param{ map { lc $_ } keys %param } = values %param; # lowercase keys
  99         my $format = $param{'-format'} ||
 100             $class->_guess_format( $param{'-file'} || $ARGV[0] ) ||
 101                 'mapmaker';
 102         $format = "\L$format";  # normalize capitalization to lower case
 103
 104         # normalize capitalization
 105         return unless( $class->_load_format_module($format) );
 106         return "Bio::MapIO::$format"->new(@args);
 107     }
 108
 109 }
 110
 111 =head2 Bio::Factory::MapFactoryI methods
 112
 113 =cut
 114
 115 =head2 next_map
 116
 117  Title   : next_tree
 118  Usage   : my $map = $factory->next_map;
 119  Function: Get a map from the factory
 120  Returns : L<Bio::Map::MapI>
 121  Args    : none
 122
 123
 124 =head2 write_map
 125
 126  Title   : write_tree
 127  Usage   : $factory->write_map($map);
 128  Function: Write a map out through the factory
 129  Returns : none
 130  Args    : L<Bio::Map::MapI>
 131
 132 =cut
 133
 134
 135 =head2 attach_EventHandler
 136
 137  Title   : attach_EventHandler
 138  Usage   : $parser->attatch_EventHandler($handler)
 139  Function: Adds an event handler to listen for events
 140  Returns : none
 141  Args    : L<Bio::Event::EventHandlerI>
 142
 143 =cut
 144
 145 sub attach_EventHandler{
 146     my ($self,$handler) = @_;
 147     return if( ! $handler );
 148     if( ! $handler->isa('Bio::Event::EventHandlerI') ) {
 149         $self->warn("Ignoring request to attatch handler ".ref($handler). ' because it is not a Bio::Event::EventHandlerI');
 150     }
 151     $self->{'_handler'} = $handler;
 152     return;
 153 }
 154
 155 =head2 _eventHandler
 156
 157  Title   : _eventHandler
 158  Usage   : private
 159  Function: Get the EventHandler
 160  Returns : L<Bio::Event::EventHandlerI>
 161  Args    : none
 162
 163
 164 =cut
 165
 166 sub _eventHandler{
 167    my ($self) = @_;
 168    return $self->{'_handler'};
 169 }
 170
 171 sub _initialize {
 172     my($self, @args) = @_;
 173     $self->{'_handler'} = undef;
 174
 175     # initialize the IO part
 176     $self->_initialize_io(@args);
 177 #    $self->attach_EventHandler(Bio::MapIO::MapEventBuilder->new());
 178 }
 179
 180 =head2 _load_format_module
 181
 182  Title   : _load_format_module
 183  Usage   : *INTERNAL MapIO stuff*
 184  Function: Loads up (like use) a module at run time on demand
 185  Example :
 186  Returns :
 187  Args    :
 188
 189 =cut
 190
 191 sub _load_format_module {
 192   my ($self,$format) = @_;
 193   my $module = "Bio::MapIO::" . $format;
 194   my $ok;
 195   eval {
 196       $ok = $self->_load_module($module);
 197   };
 198   if ( $@ ) {
 199     print STDERR <<END;
 200 $self: $format cannot be found
 201 Exception $@
 202 For more information about the MapIO system please see the MapIO docs.
 203 This includes ways of checking for formats at compile time, not run time
 204 END
 205   ;
 206   }
 207   return $ok;
 208 }
 209
 210
 211 =head2 _guess_format
 212
 213  Title   : _guess_format
 214  Usage   : $obj->_guess_format($filename)
 215  Function:
 216  Example :
 217  Returns : guessed format of filename (lower case)
 218  Args    :
 219
 220 =cut
 221
 222 sub _guess_format {
 223    my $class = shift;
 224    return unless $_ = shift;
 225    return 'mapmaker'   if /\.(map)$/i;
 226    return 'mapxml' if /\.(xml)$/i;
 227 }
 228
 229 sub DESTROY {
 230     my $self = shift;
 231
 232     $self->close();
 233 }
 234
 235 1;