[Bioperl-guts-l] [15152] bioperl-live/trunk/Bio: updates to EUtilities ( getting ready for docs, tests, etc)

Christopher John Fields cjfields at dev.open-bio.org
Fri Dec 12 16:29:48 EST 2008


Revision: 15152
Author:   cjfields
Date:     2008-12-12 16:29:48 -0500 (Fri, 12 Dec 2008)

Log Message:
-----------
updates to EUtilities (getting ready for docs, tests, etc)

Modified Paths:
--------------
    bioperl-live/trunk/Bio/DB/EUtilities.pm
    bioperl-live/trunk/Bio/DB/GenericWebAgent.pm
    bioperl-live/trunk/Bio/Tools/EUtilities/History.pm
    bioperl-live/trunk/Bio/Tools/EUtilities/HistoryI.pm
    bioperl-live/trunk/Bio/Tools/EUtilities/Query.pm
    bioperl-live/trunk/Bio/Tools/EUtilities/Summary/DocSum.pm
    bioperl-live/trunk/Bio/Tools/EUtilities.pm

Modified: bioperl-live/trunk/Bio/DB/EUtilities.pm
===================================================================
--- bioperl-live/trunk/Bio/DB/EUtilities.pm	2008-12-12 21:28:18 UTC (rev 15151)
+++ bioperl-live/trunk/Bio/DB/EUtilities.pm	2008-12-12 21:29:48 UTC (rev 15152)
@@ -63,7 +63,7 @@
 
 package Bio::DB::EUtilities;
 use strict;
-use Bio::DB::EUtilParameters;
+use Bio::Tools::EUtilities::EUtilParameters;
 use Bio::Tools::EUtilities;
 
 use base qw(Bio::DB::GenericWebAgent);
@@ -71,7 +71,7 @@
 sub new {
     my($class, at args) = @_;
     my $self = $class->SUPER::new(@args);
-    my $params = Bio::DB::EUtilParameters->new(-verbose => $self->verbose,
+    my $params = Bio::Tools::EUtilities::EUtilParameters->new(-verbose => $self->verbose,
                                                @args);
     # cache parameters
     $self->parameter_base($params);
@@ -208,15 +208,16 @@
         my $parser = Bio::Tools::EUtilities->new(
                             -eutil => $eutil,
                             -response => $self->get_Response,
+                            -parameters => $pobj,
                             -verbose => $self->verbose);
         return $self->{'_parser'} = $parser;
     }
     return $self->{'_parser'};
 }
 
-=head1 Bio::DB::EUtilParameters-delegating methods
+=head1 Bio::Tools::EUtilities::EUtilParameters-delegating methods
 
-This is only a subset of parameters available from Bio::DB::EUtilParameters (the
+This is only a subset of parameters available from Bio::Tools::EUtilities::EUtilParameters (the
 ones deemed absolutely necessary).  All others are available by calling
 'parameter_base-E<gt>method' when needed.
 
@@ -277,7 +278,7 @@
  Returns : Array of available parameters (no values)
  Args    : [optional] A string; either eutil name (for returning eutil-specific
            parameters) or 'history' (for those parameters allowed when retrieving
-           data stored on the remote server using a 'Cookie').
+           data stored on the remote server using a 'History' object).
 
 =cut
 
@@ -373,13 +374,16 @@
 
  Title    : get_ids
  Usage    : my @ids = $parser->get_ids
- Function : returns array or array ref of requestes IDs
- Returns  : array or array ref (based on wantarray)
+ Function : returns array of requested IDs (see Notes for more specifics)
+ Returns  : array
  Args     : [conditional] not required except when running elink queries against
             multiple databases. In case of the latter, the database name is
-            optional (but recommended) when retrieving IDs as the ID list will
-            be globbed together. If a db name isn't provided a warning is issued
-            as a reminder.
+            optional but recommended when retrieving IDs as the ID list will
+            be globbed together. In such cases, if a db name isn't provided a
+            warning is issued as a reminder.
+ Notes    : esearch    : returned ID list
+            elink      : returned ID list (see Args above for caveats)
+            all others : from parameter_base->id or undef
 
 =cut
 
@@ -392,10 +396,17 @@
 
  Title    : get_database
  Usage    : my $db = $info->get_database;
- Function : returns database name (eutil-compatible)
+ Function : returns single database name (eutil-compatible).  This is the queried
+            database.  For most eutils this is straightforward.  For elinks
+            (which have 'db' and 'dbfrom') this is dbto, for egquery, it is the first
+            db in the list (you probably want get_databases instead)
  Returns  : string
  Args     : none
- Note     : implemented for einfo and espell
+ Notes    : egquery    : first db in the query (you probably want get_databases)
+            einfo      : the queried database
+            espell     : the queried database
+            elink      : from parameter_base->dbfrom or undef
+            all others : from parameter_base->db or undef
 
 =cut
 
@@ -413,6 +424,37 @@
     return $self->get_Parser->get_db(@args);
 }
 
+=head2 get_databases
+
+ Title    : get_databases
+ Usage    : my @dbs = $parser->get_databases
+ Function : returns list of databases 
+ Returns  : array of strings
+ Args     : none
+ Notes    : This is guaranteed to return a list of databases. For a single
+            database use the convenience method get_db/get_database
+            
+            egquery    : list of all databases in the query
+            einfo      : the queried database
+            espell     : the queried database
+            all others : from parameter_base->db or undef
+
+=cut
+
+sub get_databases {
+    my ($self, @args) = @_;
+    return $self->get_Parser->get_databases(@args);
+}
+
+=head2 get_dbs (alias for get_databases)
+
+=cut
+
+sub get_dbs {
+    my ($self, @args) = @_;
+    return $self->get_Parser->get_databases(@args);
+}
+
 =head2 next_History
 
  Title    : next_History
@@ -420,15 +462,15 @@
  Function : returns next HistoryI (if present).
  Returns  : Bio::Tools::EUtilities::HistoryI (Cookie or LinkSet)
  Args     : none
- Note     : next_cookie() is an alias for this method. esearch, epost, and elink
-            are all capable of returning data which indicates search results (in
-            the form of UIDs) is stored on the remote server. Access to this
-            data is wrapped up in simple interface (HistoryI), which is
-            implemented in two classes: Bio::DB::EUtilities::Cookie (the
-            simplest) and Bio::DB::EUtilities::LinkSet. In general, calls to
-            epost and esearch will only return a single HistoryI object (a
+ Note     : esearch, epost, and elink are all capable of returning data which
+            indicates search results (in the form of UIDs) is stored on the
+            remote server. Access to this data is wrapped up in simple interface
+            (HistoryI), which is implemented in two classes:
+            Bio::DB::EUtilities::History (the simplest) and
+            Bio::DB::EUtilities::LinkSet. In general, calls to epost and esearch
+            will only return a single HistoryI object (formerly known as a
             Cookie), but calls to elink can generate many depending on the
-            number of IDs, the correspondence, etc.  Hence this iterator, which
+            number of IDs, the correspondence, etc. Hence this iterator, which
             allows one to retrieve said data one piece at a time.
 
 =cut
@@ -438,6 +480,15 @@
     return $self->get_Parser->next_History(@args);
 }
 
+=head2 next_cookie (alias for next_History)
+
+=cut 
+
+sub next_cookie {
+    my ($self, @args) = @_;
+    return $self->get_Parser->next_History(@args);
+}
+
 =head2 get_Histories
 
  Title    : get_Histories
@@ -463,6 +514,9 @@
  Returns  : integer
  Args     : [CONDITIONAL] string with database name - used to retrieve
             count from specific database when using egquery
+ Notes    : egquery    : count for specified database (specified above)
+            esearch    : count for last search
+            all others : undef
 
 =cut
 
@@ -471,38 +525,25 @@
     return $self->get_Parser->get_count(@args);
 }
 
-=head2 get_queried_databases
+=head2 get_term
 
- Title    : get_queried_databases
- Usage    : my @dbs = $parser->get_queried_databases
- Function : returns list of databases searched with global query
- Returns  : array of strings
+ Title    : get_term
+ Usage    : $st = $qd->get_term;
+ Function : retrieve the term for the global search
+ Returns  : string
  Args     : none
- Note     : predominately used for egquery; if used with other eutils will
-            return a list with the single database
+ Notes    : egquery    : search term
+            espell     : search term
+            esearch    : from parameter_base->term or undef
+            all others : undef
 
 =cut
 
-sub get_queried_databases {
-    my ($self, @args) = @_;
-    return $self->get_Parser->get_queried_databases(@args);
-}
-=head2 get_term
-
- Title   : get_term
- Usage   : $st = $qd->get_term;
- Function: retrieve the term for the global search
- Returns : string
- Args    : none
-
-=cut
-
-# egquery and espell
-
 sub get_term {
     my ($self, @args) = @_;
     return $self->get_Parser->get_term(@args);
 }
+
 =head2 get_translation_from
 
  Title   : get_translation_from
@@ -510,11 +551,10 @@
  Function: portion of the original query replaced with translated_to()
  Returns : string
  Args    : none
+ Note    : only applicable for esearch
 
 =cut
 
-# esearch
-
 sub get_translation_from {
     my ($self, @args) = @_;
     return $self->get_Parser->get_translation_from(@args);
@@ -527,6 +567,7 @@
  Function: replaced string used in place of the original query term in translation_from()
  Returns : string
  Args    : none
+ Note    : only applicable for esearch 
 
 =cut
 
@@ -537,11 +578,14 @@
 
 =head2 get_retstart
 
- Title   : get_retstart
- Usage   : $start = $qd->get_retstart();
- Function: retstart setting for the query (either set or NCBI default)
- Returns : Integer
- Args    : none
+ Title    : get_retstart
+ Usage    : $start = $qd->get_retstart();
+ Function : retstart setting for the query (either set or NCBI default)
+ Returns  : Integer
+ Args     : none
+ Notes    : esearch    : retstart
+            esummary   : retstart
+            all others : from parameter_base->retstart or undef
 
 =cut
 
@@ -552,12 +596,15 @@
 
 =head2 get_retmax
 
- Title   : get_retmax
- Usage   : $max = $qd->get_retmax();
- Function: retmax setting for the query (either set or NCBI default)
- Returns : Integer
- Args    : none
-
+ Title    : get_retmax
+ Usage    : $max = $qd->get_retmax();
+ Function : retmax setting for the query (either set or NCBI default)
+ Returns  : Integer
+ Args     : none
+ Notes    : esearch    : retmax
+            esummary   : retmax
+            all others : from parameter_base->retmax or undef
+            
 =cut
 
 sub get_retmax {
@@ -572,7 +619,8 @@
  Function: returns the translated query used for the search (if any)
  Returns : string
  Args    : none
- Note    : this differs from the original term.
+ Notes   : only applicable for esearch.  This is the actual term used for
+           esearch.
 
 =cut
 
@@ -588,6 +636,7 @@
  Function : retrieves the corrected query when using espell
  Returns  : string
  Args     : none

@@ Diff output truncated at 10000 characters. @@



More information about the Bioperl-guts-l mailing list