Bio/Tools/EUtilities/Info.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Tools::EUtilities::Info
   4 #
   5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   6 #
   7 # Cared for by Chris Fields
   8 #
   9 # Copyright Chris Fields
  10 #
  11 # You may distribute this module under the same terms as perl itself
  12 #
  13 # POD documentation - main docs before the code
  14 #
  15 # Part of the EUtilities BioPerl package
  16
  17 =head1 NAME
  18
  19 Bio::Tools::EUtilities::Info - interface class for storing einfo data
  20
  21 =head1 SYNOPSIS
  22
  23   #### should not create instance directly; Bio::Tools::EUtilities does this ####
  24
  25   my $info = Bio::Tools::EUtilities->new(-eutil => 'einfo',
  26                                          -file => 'einfo.xml');
  27   # can also use '-response' (for HTTP::Response objects) or '-fh' (for filehandles)
  28
  29   # print available databases (if data is present)
  30
  31   print join(', ',$info->get_available_databases),"\n";
  32
  33   # get database info
  34
  35   my $db = $info->get_database; # in case you forgot...
  36   my $desc = $info->get_description;
  37   my $nm = $info->get_menu_name;
  38   my $ct = $info->get_record_count;
  39   my $dt = $info->get_last_update;
  40
  41   # EUtilDataI interface methods
  42
  43   my $eutil = $info->eutil;
  44   my $type = $info->datatype;
  45
  46   # iterate through Field and Link objects
  47
  48   while (my $field = $info->next_Field) {
  49       print "Field code: ",$field->get_field_code,"\n";
  50       print "Field name: ",$field->get_field_name,"\n";
  51       print "Field desc: ",$field->get_field_description,"\n";
  52       print "DB  : ",$field->get_database,"\n";
  53       print "Term ct   : ",$field->get_term_count,"\n";
  54       for my $att (qw(is_date is_singletoken is_hierarchy is_hidden is_numerical)) {
  55           print "\tField $att\n" if $field->$att;
  56       }
  57   }
  58
  59   my @fields = $info->get_Fields; # grab them all (useful for grep)
  60
  61   while (my $link = $info->next_LinkInfo) {
  62       print "Link name: ",$link->get_link_name,"\n";
  63       print "Link desc: ",$link->get_link_description,"\n";
  64       print "DBFrom: ",$link->get_dbfrom,"\n"; # same as get_database()
  65       print "DBTo: ",$link->get_dbto,"\n"; # database linked to
  66   }
  67
  68   my @links = $info->get_LinkInfo; # grab them all (useful for grep)
  69
  70   $info->rewind(); # rewinds all iterators
  71   $info->rewind('links'); # rewinds Link iterator
  72   $info->rewind('fields'); # rewinds Field iterator
  73
  74 =head1 DESCRIPTION
  75
  76 This class handles data output (XML) from einfo.
  77
  78 einfo is capable of returning two types of information: 1) a list of all
  79 available databases (when called w/o parameters) and 2) information about a
  80 specific database. The latter information includes the database description,
  81 record count, and date/time stamp for the last update, among other things. It
  82 also includes a list of fields (indices by which record data is stored which can
  83 be used in queries) and links (crossrefs between related records in other
  84 databases at NCBI). Data from the latter two are stored in two small subclasses
  85 (Field and Link) which can be iterated through or retrieved all at once, as
  86 demonstrated above. NOTE: Methods described for the Link and Field subclasses
  87 are unique to those classes (as they retrieve data unique to those data types).
  88
  89 Further documentation for Link and Field subclass methods is included below.
  90
  91 For more information on einfo see:
  92
  93    http://eutils.ncbi.nlm.nih.gov/entrez/query/static/einfo_help.html
  94
  95 =head1 FEEDBACK
  96
  97 =head2 Mailing Lists
  98
  99 User feedback is an integral part of the evolution of this and other Bioperl
 100 modules. Send your comments and suggestions preferably to one of the Bioperl
 101 mailing lists. Your participation is much appreciated.
 102
 103   bioperl-l@lists.open-bio.org               - General discussion
 104   http://www.bioperl.org/wiki/Mailing_lists  - About the mailing lists
 105
 106 =head2 Support
 107
 108 Please direct usage questions or support issues to the mailing list:
 109
 110 L<bioperl-l@bioperl.org>
 111
 112 rather than to the module maintainer directly. Many experienced and
 113 reponsive experts will be able look at the problem and quickly
 114 address it. Please include a thorough description of the problem
 115 with code and data examples if at all possible.
 116
 117 =head2 Reporting Bugs
 118
 119 Report bugs to the Bioperl bug tracking system to help us keep track the bugs
 120 and their resolution. Bug reports can be submitted via the web.
 121
 122   http://bugzilla.open-bio.org/
 123
 124 =head1 AUTHOR
 125
 126 Email cjfields at bioperl dot org
 127
 128 =head1 APPENDIX
 129
 130 The rest of the documentation details each of the object methods. Internal
 131 methods are usually preceded with a _
 132
 133 =cut
 134
 135 # Let the code begin...
 136
 137 package Bio::Tools::EUtilities::Info;
 138
 139 use strict;
 140 use warnings;
 141 use base qw(Bio::Tools::EUtilities Bio::Tools::EUtilities::EUtilDataI);
 142
 143 use Bio::Tools::EUtilities::Info::LinkInfo;
 144 use Bio::Tools::EUtilities::Info::FieldInfo;
 145
 146 =head2 rewind
 147
 148  Title    : rewind
 149  Usage    : $info->rewind() # rewinds all (default)
 150             $info->rewind('links') # rewinds only links
 151  Function : 'rewinds' (resets) specified interators (all if no arg)
 152  Returns  : none
 153  Args     : [OPTIONAL] String:
 154             'all'    - all iterators (default)
 155             'linkinfo'  - LinkInfo objects only
 156             'fieldinfo' - FieldInfo objects only
 157
 158 =cut
 159
 160
 161 # private EUtilDataI method
 162
 163 sub _add_data {
 164     my ($self, $simple) = @_;
 165     if (exists $simple->{DbList} &&
 166         exists $simple->{DbList}->{DbName}) {
 167         $self->{'_available_databases'} = $simple->{DbList}->{DbName};
 168     }
 169     # start setting internal variables
 170     if (exists $simple->{DbInfo}) {
 171         for my $key (sort keys %{ $simple->{DbInfo} }) {
 172             my $data =
 173             ($key eq 'FieldList') ? $simple->{DbInfo}->{$key}->{Field} :
 174             ($key eq 'LinkList' ) ? $simple->{DbInfo}->{$key}->{Link}  :
 175             $simple->{DbInfo}->{$key};
 176             if ($key eq 'FieldList' || $key eq 'LinkList') {
 177                 for my $chunk (@{$data}) {
 178                     if (exists $simple->{DbInfo}->{DbName}) {
 179                         $chunk->{DbFrom} = $simple->{DbInfo}->{DbName};
 180                     }
 181                     my $type = ($key eq 'FieldList') ? 'FieldInfo' : 'LinkInfo';
 182                     my $obj = "Bio::Tools::EUtilities::Info::$type"->new(
 183                                            -eutil => 'einfo',
 184                                            -type => lc $type,
 185                                         -verbose => $self->verbose);
 186                     $obj->_add_data($chunk);
 187                     push @{ $self->{'_'.lc $type} }, $obj;
 188                 }
 189             } else {
 190                 $self->{'_'.lc $key} = $data;
 191             }
 192         }
 193     } else {
 194         map { $self->{'_'.lc $_} = $simple->{$_} unless ref $simple->{$_}} keys %$simple;
 195     }
 196 }
 197
 198 =head2 to_string
 199
 200  Title    : to_string
 201  Usage    : $foo->to_string()
 202  Function : converts current object to string
 203  Returns  : none
 204  Args     : (optional) simple data for text formatting
 205  Note     : Used generally for debugging and for various print methods
 206
 207 =cut
 208
 209 sub to_string {
 210     my $self = shift;
 211     my $string = $self->SUPER::to_string;
 212     if (my @dbs = $self->get_databases) {
 213         $string .= sprintf("%-20s:%s\n\n", 'DB',
 214             $self->_text_wrap('', ' 'x20 .':', join(', ',@dbs)));
 215     }
 216     while (my $fi = $self->next_FieldInfo) {
 217         $string .= $fi->to_string."\n";
 218     }
 219     while (my $li = $self->next_LinkInfo) {
 220         $string .= $li->to_string."\n";
 221     }
 222     return $string;
 223 }
 224
 225 1;