Bio/Biblio/IO.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Biblio::IO
   4 #
   5 # Cared for by Martin Senger <senger@ebi.ac.uk>
   6 # For copyright and disclaimer see below.
   7
   8 # POD documentation - main docs before the code
   9
  10 =head1 NAME
  11
  12 Bio::Biblio::IO - Handling the bibliographic references
  13
  14 =head1 SYNOPSIS
  15
  16     use Bio::Biblio::IO;
  17
  18     # getting citations from a file
  19     $in = Bio::Biblio::IO->new ('-file' => 'myfile.xml' ,
  20                                 '-format' => 'medlinexml');
  21  --- OR ---
  22
  23     # getting citations from a string
  24     $in = Bio::Biblio::IO->new ('-data' => '<MedlineCitation>...</MedlineCitation>' ,
  25                                 '-format' => 'medlinexml');
  26  --- OR ---
  27
  28     # getting citations from a string if IO::String is installed
  29     use IO::String;
  30     $in = Bio::Biblio::IO->new ('-fh' => IO::String->new ($citation),
  31                                 '-format' => 'medlinexml');
  32
  33     $in = Bio::Biblio::IO->new(-fh => $io_handle , '-format' => 'medlinexml');
  34
  35  --- OR ---
  36
  37     # getting citations from any IO handler
  38     $in = Bio::Biblio::IO->new('-fh' => $io_handle ,
  39                                '-format' => 'medlinexml');
  40
  41
  42     # now, having $in, we can read all citations
  43     while ( my $citation = $in->next_bibref() ) {
  44         &do_something_with_citation ($citation);
  45     }
  46
  47  --- OR ---
  48
  49     # again reading all citation but now a callback defined in your
  50     # code is used (note that the reading starts already when new()
  51     # is called)
  52     $io = new Bio::Biblio::IO ('-format'   => 'medlinexml',
  53                                '-file'     => $testfile,
  54                                '-callback' => \&callback);
  55     sub callback {
  56         my $citation = shift;
  57         print $citation->{'_identifier'} . "\n";
  58     }
  59
  60 Now, to actually get a citation in an XML format,
  61 use I<Bio::Biblio> module which returns an XML string:
  62
  63     use Bio::Biblio;
  64     my $xml = new Bio::Biblio->get_by_id ('94033980');
  65     my $reader = Bio::Biblio::IO->new ('-data' => $xml,
  66                                        '-format' => 'medlinexml');
  67
  68     while (my $citation = $reader->next_bibref()) {
  69        ... do something here with $citation
  70        }
  71
  72 And, finally, the resulting citation can be received in different
  73 output formats:
  74
  75     $io = new Bio::Biblio::IO ('-format' => 'medlinexml',
  76                                '-result' => 'raw');
  77  --- OR ---
  78
  79     $io = new Bio::Biblio::IO ('-format' => 'medlinexml',
  80                                '-result' => 'medline2ref');
  81
  82  --- OR ---
  83
  84     $io = new Bio::Biblio::IO ('-format' => 'pubmedxml',
  85                                '-result' => 'pubmed2ref');
  86
  87 =head1 DESCRIPTION
  88
  89 Bio::Biblio::IO is a handler module for accessing bibliographic
  90 citations. The citations can be in different formats - assuming that
  91 there is a corresponding module knowing that format in Bio::Biblio::IO
  92 directory (e.g. Bio::Biblio::IO::medlinexml). The format (and the
  93 module name) is given by the argument I<-format>.
  94
  95 Once an instance of C<Bio::Biblio::IO> class is available, the
  96 citations can be read by calling repeatedly method I<next_bibref>:
  97
  98     while (my $citation = $reader->next_bibref()) {
  99        ... do something here with $citation
 100        }
 101
 102 However, this may imply that all citations were already read into the
 103 memory. If you expect a huge amount of citations to be read, you may
 104 choose a I<callback> option. Your subroutine is specified in the
 105 C<new()> method and is called everytime a new citation is available
 106 (see an example above in SYNOPSIS).
 107
 108 The citations returned by I<next_bibref> or given to your callback
 109 routine can be of different formats depending on the argument
 110 I<-result>. One result type is I<raw> and it is represented by a
 111 simple, not blessed hash table:
 112
 113     $io = new Bio::Biblio::IO ('-result' => 'raw');
 114
 115 What other result formats are available depends on the module who
 116 reads the citations in the first place. At the moment, the following
 117 ones are available:
 118
 119     $io = new Bio::Biblio::IO ('-result' => 'medline2ref');
 120
 121 This is a default result format for reading citations by the
 122 I<medlinexml> module. The C<medlinexml> module is again the default
 123 one. Which means that you can almost omit arguments (you still need to
 124 say where the citations come from):
 125
 126     $io = new Bio::Biblio::IO ('-file' => 'data/medline_data.xml');
 127
 128 Another result format available is for PUBMED citations (which is a
 129 super-set of the MEDLINE citations having few more tags):
 130
 131     $io = new Bio::Biblio::IO ('-format' => 'pubmedxml',
 132                                '-result' => 'pubmed2ref',
 133                                '-data'   => $citation);
 134
 135 Or, because C<pubmed2ref> is a default one for PUBMED citations, you can say just:
 136
 137     $io = new Bio::Biblio::IO ('-format' => 'pubmedxml',
 138                                '-data'   => $citation);
 139
 140 Both C<medline2ref> and C<pubmed2ref> results are objects defined in
 141 the directory C<Bio::Biblio>.
 142
 143 =head1 SEE ALSO
 144
 145 =over
 146
 147 =item *
 148
 149 An example script I<examples/biblio.pl>. It has many options and its
 150 own help.  The relevant options to this IO module are I<-f>
 151 (specifying what file to read) and I<-O> (specifying what result
 152 format to achieve).
 153
 154 =item *
 155
 156 OpenBQS home page: http://industry.ebi.ac.uk/openBQS
 157
 158 =item *
 159
 160 Comments to the Perl client: http://industry.ebi.ac.uk/openBQS/Client_perl.html
 161
 162 =back
 163
 164 =head1 FEEDBACK
 165
 166 =head2 Mailing Lists
 167
 168 User feedback is an integral part of the evolution of this
 169 and other Bioperl modules. Send your comments and suggestions preferably
 170  to one of the Bioperl mailing lists.
 171 Your participation is much appreciated.
 172
 173   bioperl-l@bioperl.org                  - General discussion
 174   http://bioperl.org/MailList.shtml      - About the mailing lists
 175
 176 =head2 Reporting Bugs
 177
 178 Report bugs to the Bioperl bug tracking system to help us keep track
 179  the bugs and their resolution.
 180  Bug reports can be submitted via email or the web:
 181
 182   bioperl-bugs@bioperl.org
 183   http://bugzilla.bioperl.org/
 184
 185 =head1 AUTHOR
 186
 187 Martin Senger (senger@ebi.ac.uk)
 188
 189 =head1 COPYRIGHT
 190
 191 Copyright (c) 2002 European Bioinformatics Institute. All Rights Reserved.
 192
 193 This module is free software; you can redistribute it and/or modify
 194 it under the same terms as Perl itself.
 195
 196 =head1 DISCLAIMER
 197
 198 This software is provided "as is" without warranty of any kind.
 199
 200 =head1 APPENDIX
 201
 202 The rest of the documentation details each of the object
 203 methods. Internal methods are preceded with a _
 204
 205 =cut
 206
 207
 208 # Let the code begin...
 209
 210 package Bio::Biblio::IO;
 211
 212 use strict;
 213 use vars qw(@ISA);
 214
 215 use Bio::Root::Root;
 216 use Bio::Root::IO;
 217 use Symbol();
 218
 219 @ISA = qw(Bio::Root::Root Bio::Root::IO);
 220
 221 my $entry = 0;
 222
 223 sub new {
 224     my ($caller, @args) = @_;
 225     my $class = ref ($caller) || $caller;
 226
 227     # if $caller is an object, or if it is an underlying
 228     # 'real-work-doing' class (e.g. Bio::Biblio::IO::medlinexml) then
 229     # we want to call SUPER to create and bless an object
 230     if( $class =~ /Bio::Biblio::IO::(\S+)/ ) {
 231         my ($self) = $class->SUPER::new (@args);
 232         $self->_initialize (@args);
 233         return $self;
 234
 235     # this is called only the first time when somebody calls: 'new
 236     # Bio::Biblio::IO (...)', and it actually loads a 'real-work-doing'
 237     # module and call this new() method again (unless the loaded
 238     # module has its own new() method)
 239     } else {
 240         my %param = @args;
 241         @param{ map { lc $_ } keys %param } = values %param; # lowercase keys
 242         my $format = $param{'-format'} ||
 243             $class->_guess_format( $param{-file} || $ARGV[0] ) ||
 244                 'medlinexml';
 245         $format = "\L$format";  # normalize capitalization to lower case
 246
 247         # load module with the real implementation - as defined in $format
 248         return undef unless (&_load_format_module ($format));
 249
 250         # this will call this same method new() - but rather its
 251         # upper (object) branche
 252         return "Bio::Biblio::IO::$format"->new(@args);
 253     }
 254 }
 255
 256 sub newFh {
 257   my $class = shift;
 258   return unless my $self = $class->new(@_);
 259   return $self->fh;
 260 }
 261
 262
 263 sub fh {
 264   my $self = shift;
 265   my $class = ref($self) || $self;
 266   my $s = Symbol::gensym;
 267   tie $$s,$class,$self;
 268   return $s;
 269 }
 270
 271 # _initialize is chained for all Bio::Biblio::IO classes
 272
 273 sub _initialize {
 274     my ($self, @args) = @_;
 275     # initialize the IO part
 276     $self->_initialize_io (@args);
 277 }
 278
 279 =head2 next_bibref
 280
 281  Usage   : $citation = stream->next_bibref
 282  Function: Reads the next citation object from the stream and returns it.
 283  Returns : a Bio::Biblio::Ref citation object, or something else
 284            (depending on the '-result' argument given in the 'new()'
 285             method).
 286  Args    : none
 287
 288 =cut
 289
 290 sub next_bibref {
 291    my ($self) = shift;
 292    $self->throw ("Sorry, you cannot read from a generic Bio::Biblio::IO object.");
 293 }
 294
 295 # -----------------------------------------------------------------------------
 296
 297 =head2 _load_format_module
 298
 299  Usage   : $class->_load_format_module ($format)
 300  Returns : 1 on success, undef on failure
 301  Args    : 'format' should contain the last part of the
 302            name of a module who does the real implementation
 303
 304 It does (in run-time) a similar thing as
 305
 306    require Bio::Biblio::IO::$format
 307
 308 It throws an exception if it fails to find and load the module
 309 (for example, because of the compilation errors in the module).
 310
 311 =cut
 312
 313 sub _load_format_module {
 314   my ($format) = @_;
 315   my ($module, $load, $m);
 316
 317   $module = "_<Bio/Biblio/IO/$format.pm";
 318   $load = "Bio/Biblio/IO/$format.pm";
 319
 320   return 1 if $main::{$module};
 321   eval {
 322     require $load;
 323   };
 324   if ( $@ ) {
 325     Bio::Root::Root->throw (<<END);
 326 $load: $format cannot be found or loaded
 327 Exception $@
 328 For more information about the Biblio system please see the Bio::Biblio::IO docs.
 329 END
 330   ;
 331     return;
 332   }
 333   return 1;
 334 }
 335
 336 =head2 _guess_format
 337
 338  Usage   : $class->_guess_format ($filename)
 339  Returns : string with a guessed format of the input data (e.g. 'medlinexml')
 340  Args    : a file name whose extension can help to guess its format
 341
 342 It makes an expert guess what kind of data are in the given file
 343 (but be prepare that $filename may be empty).
 344
 345 =cut
 346
 347 sub _guess_format {
 348    my $class = shift;
 349    return unless $_ = shift;
 350    return 'medlinexml'   if (/\.(xml|medlinexml)$/i);
 351    return;
 352 }
 353
 354 sub DESTROY {
 355     my $self = shift;
 356
 357     $self->close();
 358 }
 359
 360 sub TIEHANDLE {
 361     my ($class,$val) = @_;
 362     return bless {'biblio' => $val}, $class;
 363 }
 364
 365 sub READLINE {
 366   my $self = shift;
 367   return $self->{'biblio'}->next_bibref() unless wantarray;
 368   my (@list, $obj);
 369   push @list, $obj while $obj = $self->{'biblio'}->next_bibref();
 370   return @list;
 371 }
 372
 373 1;