Bio/Biblio/IO.pm

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