Bio/Tools/EUtilities/Summary.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::DB::EUtilities::DocSum
   4 #
   5 # Cared for by Chris Fields
   6 #
   7 # Copyright Chris Fields
   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 # Part of the EUtilities BioPerl package
  14
  15 =head1 NAME
  16
  17 Bio::DB::EUtilities::Summary
  18
  19 =head1 SYNOPSIS
  20
  21   #### should not create instance directly; Bio::Tools::EUtilities does this ####
  22
  23   my $esum = Bio::Tools::EUtilities->new(-eutil => 'esummary',
  24                                          -file => 'summary.xml');
  25   # can also use '-response' (for HTTP::Response objects) or '-fh' (for filehandles)
  26
  27   while (my $docsum = $esum->next_DocSum) {
  28       my $id = $docsum->get_ids;  # EUtilDataI compliant method, returns docsum ID
  29       my @names = $docsum->get_item_names;
  30   }
  31
  32 =head1 DESCRIPTION
  33
  34 This class handles data output (XML) from esummary.
  35
  36 esummary retrieves information in the form of document summaries (docsums) when
  37 passed a list of primary IDs or if using a previous search history.
  38
  39 This module breaks down the returned data from esummary into individual document
  40 summaries per ID (using a DocSum object). As the data in a docsum can be nested,
  41 subclasses of DocSums (Item, ListItem, Structure) are also present.
  42
  43 Further documentation for Link and Field subclass methods is included below.
  44
  45 =head1 FEEDBACK
  46
  47 =head2 Mailing Lists
  48
  49 User feedback is an integral part of the
  50 evolution of this and other Bioperl modules. Send
  51 your comments and suggestions preferably to one
  52 of the Bioperl mailing lists. Your participation
  53 is much appreciated.
  54
  55   bioperl-l@lists.open-bio.org               - General discussion
  56   http://www.bioperl.org/wiki/Mailing_lists  - About the mailing lists
  57
  58 =head2 Reporting Bugs
  59
  60 Report bugs to the Bioperl bug tracking system to
  61 help us keep track the bugs and their resolution.
  62 Bug reports can be submitted via the web.
  63
  64   http://bugzilla.open-bio.org/
  65
  66 =head1 AUTHOR
  67
  68 Email cjfields at uiuc dot edu
  69
  70 =head1 APPENDIX
  71
  72 The rest of the documentation details each of the
  73 object methods. Internal methods are usually
  74 preceded with a _
  75
  76 =cut
  77
  78 # Let the code begin...
  79
  80 package Bio::Tools::EUtilities::Summary;
  81 use strict;
  82 use warnings;
  83
  84 use base qw(Bio::Tools::EUtilities Bio::Tools::EUtilities::EUtilDataI);
  85
  86 use Bio::Tools::EUtilities::Summary::DocSum;
  87
  88 # private EUtilDataI method
  89
  90 sub _add_data {
  91     my ($self, $data) = @_;
  92     if (!exists $data->{DocSum}) {
  93         $self->warn('No returned docsums.');
  94         return;
  95     }
  96
  97     my @docs;
  98     for my $docsum (@{ $data->{DocSum} }) {
  99         my $ds = Bio::Tools::EUtilities::Summary::DocSum->new(-datatype => 'docsum',
 100                                                               -verbose => $self->verbose);
 101         $ds->_add_data($docsum);
 102         push @{ $self->{'_docsums'} }, $ds;
 103     }
 104 }
 105
 106 =head2 to_string
 107
 108  Title    : to_string
 109  Usage    : $foo->to_string()
 110  Function : converts current object to string
 111  Returns  : none
 112  Args     : (optional) simple data for text formatting
 113  Note     : Used generally for debugging and for the print_* methods
 114
 115 =cut
 116
 117 sub to_string {
 118     my $self = shift;
 119     my %data = (
 120         'DB'    => [1, join(', ',$self->get_databases) || ''],
 121     );
 122     my $string = $self->SUPER::to_string."\n";
 123     for my $k (sort {$data{$a}->[0] <=> $data{$b}->[0]} keys %data) {
 124         $string .= sprintf("%-20s:%s\n\n",$k, $self->_text_wrap('',' 'x 20 .':', $data{$k}->[1]));
 125     }
 126     while (my $ds = $self->next_DocSum) {
 127         $string .= $ds->to_string."\n";
 128     }
 129     return $string;
 130 }
 131
 132 1;
 133
 134 __END__