lib/Bio/MapIO.pm

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