Bio/Tools/EUtilities/Info.pm

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