[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