branch-1-6/Bio/Tools/EUtilities/History.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Tools::EUtilities::History
   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::History - lightweight implementation of HistoryI
  20 interface (not bound to filehandles, extraneous methods, etc).
  21
  22 =head1 SYNOPSIS
  23
  24   #should work for any class which is-a HistoryI
  25
  26   if ($obj->has_History) {
  27       # do something here
  28   }
  29
  30   ($webenv, $querykey) = $obj->history;
  31
  32   $obj->history($webenv, $querykey);
  33
  34   $webenv = $obj->get_webenv;
  35
  36   $query_key = $obj->get_query_key;
  37
  38 =head1 DESCRIPTION
  39
  40 This class extends methods for any EUtilDataI implementation allow instances to
  41 dealwith NCBI history data (WebEnv and query_key).  These can be used as
  42 parameters for further queries against data sets stored on the NCBI server, much
  43 like NCBI's Entrez search history. These are important when one wants to run
  44 complex queries using esearch, retrieve related data using elink, and retrieve
  45 large datasets using epost/efetch.
  46
  47 This class is the simplest implementation and merely holds data for future
  48 queries from any HistoryI. See also Bio::Tools::EUtilities::Query (esearch) and
  49 Bio::Tools::EUtilities::LinkSet (elink), which also implement HistoryI.
  50
  51 =cut
  52
  53 =head1 FEEDBACK
  54
  55 =head2 Mailing Lists
  56
  57 User feedback is an integral part of the evolution of this and other Bioperl
  58 modules. Send your comments and suggestions preferably to one of the Bioperl
  59 mailing lists. Your participation is much appreciated.
  60
  61   bioperl-l@lists.open-bio.org               - General discussion
  62   http://www.bioperl.org/wiki/Mailing_lists  - About the mailing lists
  63
  64 =head2 Support
  65
  66 Please direct usage questions or support issues to the mailing list:
  67
  68 I<bioperl-l@bioperl.org>
  69
  70 rather than to the module maintainer directly. Many experienced and
  71 reponsive experts will be able look at the problem and quickly
  72 address it. Please include a thorough description of the problem
  73 with code and data examples if at all possible.
  74
  75 =head2 Reporting Bugs
  76
  77 Report bugs to the Bioperl bug tracking system to help us keep track the bugs
  78 and their resolution. Bug reports can be submitted via the web.
  79
  80   http://bugzilla.open-bio.org/
  81
  82 =head1 AUTHOR
  83
  84 Email cjfields at bioperl dot org
  85
  86 =head1 APPENDIX
  87
  88 The rest of the documentation details each of the object methods. Internal
  89 methods are usually preceded with a _
  90
  91 =cut
  92
  93 # Let the code begin...
  94
  95 package Bio::Tools::EUtilities::History;
  96 use strict;
  97 use warnings;
  98
  99 use base qw(Bio::Root::Root Bio::Tools::EUtilities::HistoryI);
 100
 101 sub new {
 102     my ($class, @args) = @_;
 103     my $self = $class->SUPER::new(@args);
 104     my ($eutil) = $self->_rearrange([qw(eutil)],@args);
 105     $eutil || $self->throw('eutil not defined');
 106     $self->eutil($eutil);
 107     $self->datatype('history');
 108     return $self;
 109 }
 110
 111 =head2 history
 112
 113  Title    : history
 114  Usage    : my ($webenv, $qk) = $hist->history
 115  Function : Get/Set two-element list of webenv() and query_key()
 116  Returns  : array
 117  Args     : two-element list of webenv, query key
 118
 119 =cut
 120
 121 =head2 get_webenv
 122
 123  Title    : get_webenv
 124  Usage    : my $webenv = $hist->get_webenv
 125  Function : returns web environment key needed to retrieve results from
 126             NCBI server
 127  Returns  : string (encoded key)
 128  Args     : none
 129
 130 =cut
 131
 132 =head2 get_query_key
 133
 134  Title    : get_query_key
 135  Usage    : my $qk = $hist->get_query_key
 136  Function : returns query key (integer) for the history number for this session
 137  Returns  : integer
 138  Args     : none
 139
 140 =cut
 141
 142 sub _add_data {
 143     my ($self, $simple) = @_;
 144     if (!exists $simple->{WebEnv} || !exists $simple->{QueryKey}) {
 145         $self->debug("Data:",Dumper($simple));
 146         $self->throw("Missing webenv/query key in history output");
 147     }
 148     $self->{_webenv} = $simple->{WebEnv} && delete $simple->{WebEnv};
 149     $self->{_querykey} = $simple->{QueryKey} && delete $simple->{QueryKey};
 150 }
 151
 152 =head2 to_string
 153
 154  Title    : to_string
 155  Usage    : $foo->to_string()
 156  Function : converts current object to string
 157  Returns  : none
 158  Args     : (optional) simple data for text formatting
 159  Note     : Used generally for debugging and for the print_* methods
 160
 161 =cut
 162
 163 sub to_string {
 164     my $self = shift;
 165     my $string;
 166     my %map = (
 167         'get_webenv' => 'WebEnv',
 168         'get_query_key' => 'Key'
 169         );
 170     for my $m (qw(get_webenv get_query_key)) {
 171         $string .= sprintf("%-20s:%s\n", $map{$m}, $self->$m);
 172     }
 173     return $string;
 174 }
 175
 176 1;