Bio/DB/EUtilities.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::DB::EUtilities
   4 #
   5 # Cared for by Chris Fields <cjfields at uiuc dot edu>
   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 # EUtil-based extension of GenericWebDBI interface
  14
  15 =head1 NAME
  16
  17 Bio::DB::EUtilities - webagent which interacts with and retrieves data from
  18 NCBI's eUtils
  19
  20 =head1 SYNOPSIS
  21
  22   # ...To be added!
  23
  24 =head1 DESCRIPTION
  25
  26 This is a general webagent which posts and retrieves data to NCBI's eUtilities
  27 service using their CGI interface.
  28
  29 =head1 FEEDBACK
  30
  31 =head2 Mailing Lists
  32
  33 User feedback is an integral part of the
  34 evolution of this and other Bioperl modules. Send
  35 your comments and suggestions preferably to one
  36 of the Bioperl mailing lists. Your participation
  37 is much appreciated.
  38
  39   bioperl-l@lists.open-bio.org               - General discussion
  40   http://www.bioperl.org/wiki/Mailing_lists  - About the mailing lists
  41
  42 =head2 Reporting Bugs
  43
  44 Report bugs to the Bioperl bug tracking system to
  45 help us keep track the bugs and their resolution.
  46 Bug reports can be submitted via the web.
  47
  48   http://bugzilla.open-bio.org/
  49
  50 =head1 AUTHOR
  51
  52 Email cjfields at uiuc dot edu
  53
  54 =head1 APPENDIX
  55
  56 The rest of the documentation details each of the
  57 object methods. Internal methods are usually
  58 preceded with a _
  59
  60 =cut
  61
  62 # Let the code begin...
  63
  64 package Bio::DB::EUtilities;
  65 use strict;
  66 use Bio::Tools::EUtilities::EUtilParameters;
  67 use Bio::Tools::EUtilities;
  68
  69 use base qw(Bio::DB::GenericWebAgent);
  70
  71 sub new {
  72     my($class,@args) = @_;
  73     my $self = $class->SUPER::new(@args);
  74     my $params = Bio::Tools::EUtilities::EUtilParameters->new(-verbose => $self->verbose,
  75                                                @args);
  76     # cache parameters
  77     $self->parameter_base($params);
  78     return $self;
  79 }
  80
  81 =head1 Bio::DB::GenericWebAgent methods
  82
  83 =cut
  84
  85 =head1 GenericWebDBI methods
  86
  87 =head2 parameter_base
  88
  89  Title   : parameter_base
  90  Usage   : $dbi->parameter_base($pobj);
  91  Function: Get/Set Bio::ParameterBaseI.
  92  Returns : Bio::ParameterBaseI object
  93  Args    : Bio::ParameterBaseI object
  94
  95 =cut
  96
  97 =head2 ua
  98
  99  Title   : ua
 100  Usage   : $dbi->ua;
 101  Function: Get/Set LWP::UserAgent.
 102  Returns : LWP::UserAgent
 103  Args    : LWP::UserAgent
 104
 105 =cut
 106
 107 =head2 get_Response
 108
 109  Title   : get_Response
 110  Usage   : $agent->get_Response;
 111  Function: Get the HTTP::Response object by passing it an HTTP::Request (generated from
 112            Bio::ParameterBaseI implementation).
 113  Returns : HTTP::Response object or data if callback is used
 114  Args    : (optional)
 115
 116            -cache_response - flag to cache HTTP::Response object;
 117                              Default is 1 (TRUE, caching ON)
 118
 119            These are passed on to LWP::UserAgent::request() if stipulated
 120
 121            -file   - use a LWP::UserAgent-compliant callback
 122            -cb     - dumps the response to a file (handy for large responses)
 123                      Note: can't use file and callback at the same time
 124            -read_size_hint - bytes of content to read in at a time to pass to callback
 125  Note    : Caching and parameter checking are set
 126
 127 =cut
 128
 129 =head2 delay
 130
 131  Title   : delay
 132  Usage   : $secs = $self->delay([$secs])
 133  Function: get/set number of seconds to delay between fetches
 134  Returns : number of seconds to delay
 135  Args    : new value
 136
 137 NOTE: the default is to use the value specified by delay_policy().
 138 This can be overridden by calling this method.
 139
 140 =cut
 141
 142 =head1 LWP::UserAgent related methods
 143
 144 =head2 proxy
 145
 146  Title   : proxy
 147  Usage   : $httpproxy = $db->proxy('http')  or
 148            $db->proxy(['http','ftp'], 'http://myproxy' )
 149  Function: Get/Set a proxy for use of proxy
 150  Returns : a string indicating the proxy
 151  Args    : $protocol : an array ref of the protocol(s) to set/get
 152            $proxyurl : url of the proxy to use for the specified protocol
 153            $username : username (if proxy requires authentication)
 154            $password : password (if proxy requires authentication)
 155
 156 =cut
 157
 158 =head2 authentication
 159
 160  Title   : authentication
 161  Usage   : $db->authentication($user,$pass)
 162  Function: Get/Set authentication credentials
 163  Returns : Array of user/pass
 164  Args    : Array or user/pass
 165
 166 =cut
 167
 168 =head2 delay_policy
 169
 170   Title   : delay_policy
 171   Usage   : $secs = $self->delay_policy
 172   Function: return number of seconds to delay between calls to remote db
 173   Returns : number of seconds to delay
 174   Args    : none
 175
 176   NOTE: NCBI requests a delay of 3 seconds between requests.  This method
 177         implements that policy.  This may change to check time of day for lengthening delays if needed
 178
 179 =cut
 180
 181 sub delay_policy {
 182   my $self = shift;
 183   return 3;
 184 }
 185
 186 =head2 get_Parser
 187
 188  Title   : get_Parser
 189  Usage   : $agent->get_Parser;
 190  Function: Retrieve the parser used for last agent request
 191  Returns : The Bio::Tools::EUtilities parser used to parse the HTTP::Response
 192            content
 193  Args    : None
 194  Note    : Abstract method; defined by implementation
 195
 196 =cut
 197
 198 sub get_Parser {
 199     my ($self) = @_;
 200     my $pobj = $self->parameter_base;
 201     if ($pobj->parameters_changed || !$self->{'_parser'}) {
 202         my $eutil = $pobj->eutil ;
 203         if ($eutil eq 'efetch') {
 204             $self->throw("No parser defined for efetch; use get_Response() directly");
 205         };
 206         # if we are to add pipe/tempfile support this would probably be the
 207         # place to add it....
 208         my $parser = Bio::Tools::EUtilities->new(
 209                             -eutil => $eutil,
 210                             -response => $self->get_Response,
 211                             -parameters => $pobj,
 212                             -verbose => $self->verbose);
 213         return $self->{'_parser'} = $parser;
 214     }
 215     return $self->{'_parser'};
 216 }
 217
 218 =head1 Bio::Tools::EUtilities::EUtilParameters-delegating methods
 219
 220 This is only a subset of parameters available from Bio::Tools::EUtilities::EUtilParameters (the
 221 ones deemed absolutely necessary).  All others are available by calling
 222 'parameter_base-E<gt>method' when needed.
 223
 224 =cut
 225
 226 =head2 set_parameters
 227
 228  Title   : set_parameters
 229  Usage   : $pobj->set_parameters(@params);
 230  Function: sets the NCBI parameters listed in the hash or array
 231  Returns : None
 232  Args    : [optional] hash or array of parameter/values.
 233  Note    : This sets any parameter (i.e. doesn't screen them).  In addition to
 234            regular eutil-specific parameters, you can set the following:
 235
 236            -eutil    - the eUtil to be used (default 'efetch')
 237            -history  - pass a HistoryI-implementing object, which
 238                        sets the WebEnv, query_key, and possibly db and linkname
 239                        (the latter two only for LinkSets)
 240            -correspondence - Boolean flag, set to TRUE or FALSE; indicates how
 241                        IDs are to be added together for elink request where
 242                        ID correspondence might be needed
 243                        (default 0)
 244
 245 =cut
 246
 247 sub set_parameters {
 248     my ($self, @args) = @_;
 249     # just ensures that parser instance isn't reused
 250     delete $self->{'_parser'};
 251     $self->parameter_base->set_parameters(@args);
 252 }
 253
 254 =head2 reset_parameters
 255
 256  Title   : reset_parameters
 257  Usage   : resets values
 258  Function: resets parameters to either undef or value in passed hash
 259  Returns : none
 260  Args    : [optional] hash of parameter-value pairs
 261  Note    : this also resets eutil(), correspondence(), and the history and request
 262            cache
 263
 264 =cut
 265
 266 sub reset_parameters {
 267     my ($self, @args) = @_;
 268     # just ensures that parser instance isn't reused
 269     delete $self->{'_parser'};
 270     $self->parameter_base->reset_parameters(@args);
 271 }
 272
 273 =head2 available_parameters
 274
 275  Title   : available_parameters
 276  Usage   : @params = $pobj->available_parameters()
 277  Function: Returns a list of the available parameters
 278  Returns : Array of available parameters (no values)
 279  Args    : [optional] A string; either eutil name (for returning eutil-specific
 280            parameters) or 'history' (for those parameters allowed when retrieving
 281            data stored on the remote server using a 'History' object).
 282
 283 =cut
 284
 285 sub available_parameters {
 286     my ($self, @args) = @_;
 287     return $self->parameter_base->available_parameters(@args);
 288 }
 289
 290 =head2 get_parameters
 291
 292  Title   : get_parameters
 293  Usage   : @params = $pobj->get_parameters;
 294            %params = $pobj->get_parameters;
 295  Function: Returns list of key/value pairs, parameter => value
 296  Returns : Flattened list of key-value pairs. All key-value pairs returned,
 297            though subsets can be returned based on the '-type' parameter.
 298            Data passed as an array ref are returned based on whether the
 299            '-join_id' flag is set (default is the same array ref).
 300  Args    : -type : the eutil name or 'history', for returning a subset of
 301                 parameters (Default: returns all)
 302            -join_ids : Boolean; join IDs based on correspondence (Default: no join)
 303
 304 =cut
 305
 306 sub get_parameters {
 307     my ($self, @args) = @_;
 308     return $self->parameter_base->get_parameters(@args);
 309 }
 310
 311 =head2 get_parameter_values
 312
 313  Title   : get_parameter_values
 314  Usage   : @vals = $factory->get_parameter_value('id'); # always get array
 315  Function: Returns the specific parameter values.
 316  Returns : For consistency returns a list of values for this parameter.  If only
 317            one is expected, use:
 318
 319            ($val) = $factory->get_parameter_value('id');
 320
 321  Args    : parameter expected
 322
 323 =cut
 324
 325 sub get_parameter_values {
 326     my ($self, $p) = @_;
 327     my %params = $self->parameter_base->get_parameters(-list => [$p]);
 328     if (exists $params{$p}) {
 329         return ref $params{$p} eq 'ARRAY' ? @{$params{$p}} : $params{$p};
 330     }
 331     return;
 332 }
 333
 334 =head1 Bio::Tools::EUtilities-delegating methods
 335
 336 =cut
 337
 338 =head1 Bio::Tools::EUtilities::EUtilDataI methods
 339
 340 =head2 eutil
 341
 342  Title    : eutil
 343  Usage    : $eutil->$foo->eutil
 344  Function : Get/Set eutil
 345  Returns  : string
 346  Args     : string (eutil)
 347  Throws   : on invalid eutil
 348
 349 =cut
 350
 351 sub eutil {
 352     my ($self, @args) = @_;
 353     return $self->get_Parser->eutil(@args);
 354 }
 355
 356 =head2 datatype
 357
 358  Title    : datatype
 359  Usage    : $type = $foo->datatype;
 360  Function : Get/Set data object type
 361  Returns  : string
 362  Args     : string
 363
 364 =cut
 365
 366 sub datatype {
 367     my ($self, @args) = @_;
 368     return $self->get_Parser->datatype(@args);
 369 }
 370
 371 =head2 to_string
 372
 373  Title    : to_string
 374  Usage    : $foo->to_string()
 375  Function : converts current object to string
 376  Returns  : none
 377  Args     : (optional) simple data for text formatting
 378  Note     : Implemented in plugins
 379
 380 =cut
 381
 382 sub to_string {
 383     my ($self, @args) = @_;
 384     return $self->get_Parser->to_string(@args);
 385 }
 386
 387 =head2 print_all
 388
 389  Title    : print_all
 390  Usage    : $info->print_all();
 391             $info->print_all(-fh => $fh, -cb => $coderef);
 392  Function : prints (dumps) all data in parser.  Unless a coderef is supplied,
 393             this just dumps the parser-specific to_string method to either a
 394             file/fh or STDOUT
 395  Returns  : none
 396  Args     : [optional]
 397            -file : file to print to
 398            -fh   : filehandle to print to (cannot be used concurrently with file)
 399            -cb   : coderef to use in place of default print method.  This is passed
 400                    in a LinkSet object
 401            -wrap : number of columns to wrap default text output to (def = 80)
 402  Notes    : only applicable for einfo.  If -file or -fh are not defined,
 403             prints to STDOUT
 404
 405 =cut
 406
 407 sub print_all {
 408     my ($self, @args) = @_;
 409     return $self->get_Parser->print_all(@args);
 410 }
 411
 412 =head1 Methods useful for multiple eutils
 413
 414 =head2 get_ids
 415
 416  Title    : get_ids
 417  Usage    : my @ids = $parser->get_ids
 418  Function : returns array of requested IDs (see Notes for more specifics)
 419  Returns  : array
 420  Args     : [conditional] not required except when running elink queries against
 421             multiple databases. In case of the latter, the database name is
 422             optional but recommended when retrieving IDs as the ID list will
 423             be globbed together. In such cases, if a db name isn't provided a
 424             warning is issued as a reminder.
 425  Notes    : esearch    : returned ID list
 426             elink      : returned ID list (see Args above for caveats)
 427             all others : from parameter_base->id or undef
 428
 429 =cut
 430
 431 sub get_ids {
 432     my ($self, @args) = @_;
 433     return $self->get_Parser->get_ids(@args);
 434 }
 435
 436 =head2 get_database
 437
 438  Title    : get_database
 439  Usage    : my $db = $info->get_database;
 440  Function : returns single database name (eutil-compatible).  This is the queried
 441             database.  For most eutils this is straightforward.  For elinks
 442             (which have 'db' and 'dbfrom') this is dbto, for egquery, it is the first
 443             db in the list (you probably want get_databases instead)
 444  Returns  : string
 445  Args     : none
 446  Notes    : egquery    : first db in the query (you probably want get_databases)
 447             einfo      : the queried database
 448             espell     : the queried database
 449             elink      : from parameter_base->dbfrom or undef
 450             all others : from parameter_base->db or undef
 451
 452 =cut
 453
 454 sub get_database {
 455     my ($self, @args) = @_;
 456     return $self->get_Parser->get_database(@args);
 457 }
 458
 459 =head2 get_db (alias for get_database)
 460
 461 =cut
 462
 463 sub get_db {
 464     my ($self, @args) = @_;
 465     return $self->get_Parser->get_db(@args);
 466 }
 467
 468 =head2 get_databases
 469
 470  Title    : get_databases
 471  Usage    : my @dbs = $parser->get_databases
 472  Function : returns list of databases
 473  Returns  : array of strings
 474  Args     : none
 475  Notes    : This is guaranteed to return a list of databases. For a single
 476             database use the convenience method get_db/get_database
 477
 478             egquery    : list of all databases in the query
 479             einfo      : the queried database
 480             espell     : the queried database
 481             all others : from parameter_base->db or undef
 482
 483 =cut
 484
 485 sub get_databases {
 486     my ($self, @args) = @_;
 487     return $self->get_Parser->get_databases(@args);
 488 }
 489
 490 =head2 get_dbs (alias for get_databases)
 491
 492 =cut
 493
 494 sub get_dbs {
 495     my ($self, @args) = @_;
 496     return $self->get_Parser->get_databases(@args);
 497 }
 498
 499 =head2 next_History
 500
 501  Title    : next_History
 502  Usage    : while (my $hist=$parser->next_History) {...}
 503  Function : returns next HistoryI (if present).
 504  Returns  : Bio::Tools::EUtilities::HistoryI (Cookie or LinkSet)
 505  Args     : none
 506  Note     : esearch, epost, and elink are all capable of returning data which
 507             indicates search results (in the form of UIDs) is stored on the
 508             remote server. Access to this data is wrapped up in simple interface
 509             (HistoryI), which is implemented in two classes:
 510             Bio::DB::EUtilities::History (the simplest) and
 511             Bio::DB::EUtilities::LinkSet. In general, calls to epost and esearch
 512             will only return a single HistoryI object (formerly known as a
 513             Cookie), but calls to elink can generate many depending on the
 514             number of IDs, the correspondence, etc. Hence this iterator, which
 515             allows one to retrieve said data one piece at a time.
 516
 517 =cut
 518
 519 sub next_History {
 520     my ($self, @args) = @_;
 521     return $self->get_Parser->next_History(@args);
 522 }
 523
 524 =head2 next_cookie (alias for next_History)
 525
 526 =cut
 527
 528 sub next_cookie {
 529     my ($self, @args) = @_;
 530     return $self->get_Parser->next_History(@args);
 531 }
 532
 533 =head2 get_Histories
 534
 535  Title    : get_Histories
 536  Usage    : my @hists = $parser->get_Histories
 537  Function : returns list of HistoryI objects.
 538  Returns  : list of Bio::Tools::EUtilities::HistoryI (Cookie or LinkSet)
 539  Args     : none
 540
 541 =cut
 542
 543 sub get_Histories {
 544     my ($self, @args) = @_;
 545     return $self->get_Parser->get_Histories(@args);
 546 }
 547
 548 =head1 Query-related methods
 549
 550 =head2 get_count
 551
 552  Title    : get_count
 553  Usage    : my $ct = $parser->get_count
 554  Function : returns the count (hits for a search)
 555  Returns  : integer
 556  Args     : [CONDITIONAL] string with database name - used to retrieve
 557             count from specific database when using egquery
 558  Notes    : egquery    : count for specified database (specified above)
 559             esearch    : count for last search
 560             all others : undef
 561
 562 =cut
 563
 564 sub get_count {
 565     my ($self, @args) = @_;
 566     return $self->get_Parser->get_count(@args);
 567 }
 568
 569 =head2 get_term
 570
 571  Title    : get_term
 572  Usage    : $st = $qd->get_term;
 573  Function : retrieve the term for the global search
 574  Returns  : string
 575  Args     : none
 576  Notes    : egquery    : search term
 577             espell     : search term
 578             esearch    : from parameter_base->term or undef
 579             all others : undef
 580
 581 =cut
 582
 583 sub get_term {
 584     my ($self, @args) = @_;
 585     return $self->get_Parser->get_term(@args);
 586 }
 587
 588 =head2 get_translation_from
 589
 590  Title   : get_translation_from
 591  Usage   : $string = $qd->get_translation_from();
 592  Function: portion of the original query replaced with translated_to()
 593  Returns : string
 594  Args    : none
 595  Note    : only applicable for esearch
 596
 597 =cut
 598
 599 sub get_translation_from {
 600     my ($self, @args) = @_;
 601     return $self->get_Parser->get_translation_from(@args);
 602 }
 603
 604 =head2 get_translation_to
 605
 606  Title   : get_translation_to
 607  Usage   : $string = $qd->get_translation_to();
 608  Function: replaced string used in place of the original query term in translation_from()
 609  Returns : string
 610  Args    : none
 611  Note    : only applicable for esearch
 612
 613 =cut
 614
 615 sub get_translation_to {
 616     my ($self, @args) = @_;
 617     return $self->get_Parser->get_translation_to(@args);
 618 }
 619
 620 =head2 get_retstart
 621
 622  Title    : get_retstart
 623  Usage    : $start = $qd->get_retstart();
 624  Function : retstart setting for the query (either set or NCBI default)
 625  Returns  : Integer
 626  Args     : none
 627  Notes    : esearch    : retstart
 628             esummary   : retstart
 629             all others : from parameter_base->retstart or undef
 630
 631 =cut
 632
 633 sub get_retstart {
 634     my ($self, @args) = @_;
 635     return $self->get_Parser->get_retstart(@args);
 636 }
 637
 638 =head2 get_retmax
 639
 640  Title    : get_retmax
 641  Usage    : $max = $qd->get_retmax();
 642  Function : retmax setting for the query (either set or NCBI default)
 643  Returns  : Integer
 644  Args     : none
 645  Notes    : esearch    : retmax
 646             esummary   : retmax
 647             all others : from parameter_base->retmax or undef
 648
 649 =cut
 650
 651 sub get_retmax {
 652     my ($self, @args) = @_;
 653     return $self->get_Parser->get_retmax(@args);
 654 }
 655
 656 =head2 get_query_translation
 657
 658  Title   : get_query_translation
 659  Usage   : $string = $qd->get_query_translation();
 660  Function: returns the translated query used for the search (if any)
 661  Returns : string
 662  Args    : none
 663  Notes   : only applicable for esearch.  This is the actual term used for
 664            esearch.
 665
 666 =cut
 667
 668 sub get_query_translation {
 669     my ($self, @args) = @_;
 670     return $self->get_Parser->get_query_translation(@args);
 671 }
 672
 673 =head2 get_corrected_query
 674
 675  Title    : get_corrected_query
 676  Usage    : my $cor = $eutil->get_corrected_query;
 677  Function : retrieves the corrected query when using espell
 678  Returns  : string
 679  Args     : none
 680  Notes    : only applicable for espell.
 681
 682 =cut
 683
 684 sub get_corrected_query {
 685     my ($self, @args) = @_;
 686     return $self->get_Parser->get_corrected_query(@args);
 687 }
 688
 689 =head2 get_replaced_terms
 690
 691  Title    : get_replaced_terms
 692  Usage    : my $term = $eutil->get_replaced_term
 693  Function : returns array of strings replaced in the query
 694  Returns  : string
 695  Args     : none
 696  Notes    : only applicable for espell
 697
 698 =cut
 699
 700 sub get_replaced_terms {
 701     my ($self, @args) = @_;
 702     return $self->get_Parser->get_replaced_terms(@args);
 703 }
 704
 705 =head2 next_GlobalQuery
 706
 707  Title    : next_GlobalQuery
 708  Usage    : while (my $query = $eutil->next_GlobalQuery) {...}
 709  Function : iterates through the queries returned from an egquery search
 710  Returns  : GlobalQuery object
 711  Args     : none
 712  Notes    : only applicable for egquery
 713
 714 =cut
 715
 716 sub next_GlobalQuery {
 717     my ($self, @args) = @_;
 718     return $self->get_Parser->next_GlobalQuery(@args);
 719 }
 720
 721 =head2 get_GlobalQueries
 722
 723  Title    : get_GlobalQueries
 724  Usage    : @queries = $eutil->get_GlobalQueries
 725  Function : returns list of GlobalQuery objects
 726  Returns  : array of GlobalQuery objects
 727  Args     : none
 728  Notes    : only applicable for egquery
 729
 730 =cut
 731
 732 sub get_GlobalQueries {
 733     my ($self, @args) = @_;
 734     return $self->get_Parser->get_GlobalQueries(@args);
 735 }
 736
 737 =head2 print_GlobalQueries
 738
 739  Title    : print_GlobalQueries
 740  Usage    : $docsum->print_GlobalQueries();
 741             $docsum->print_GlobalQueries(-fh => $fh, -cb => $coderef);
 742  Function : prints item data for all global queries.  The default printing
 743             method is each item per DocSum is printed with relevant values if
 744             present in a simple table using Text::Wrap.
 745  Returns  : none
 746  Args     : [optional]
 747            -file : file to print to
 748            -fh   : filehandle to print to (cannot be used concurrently with file)
 749            -cb   : coderef to use in place of default print method.  This is passed
 750                    in a GlobalQuery object;
 751            -wrap : number of columns to wrap default text output to (def = 80)
 752  Notes    : only applicable for esummary.  If -file or -fh are not defined,
 753             prints to STDOUT
 754
 755 =cut
 756
 757 sub print_GlobalQueries {
 758     my ($self, @args) = @_;
 759     return $self->get_Parser->print_GlobalQueries(@args);
 760 }
 761
 762 =head1 Summary-related methods
 763
 764 =head2 next_DocSum
 765
 766  Title    : next_DocSum
 767  Usage    : while (my $ds = $esum->next_DocSum) {...}
 768  Function : iterate through DocSum instances
 769  Returns  : single Bio::Tools::EUtilities::Summary::DocSum
 770  Args     : none yet
 771  Notes    : only applicable for esummary
 772
 773 =cut
 774
 775 sub next_DocSum {
 776     my ($self, @args) = @_;
 777     return $self->get_Parser->next_DocSum(@args);
 778 }
 779
 780 =head2 get_DocSums
 781
 782  Title    : get_DocSums
 783  Usage    : my @docsums = $esum->get_DocSums
 784  Function : retrieve a list of DocSum instances
 785  Returns  : array of Bio::Tools::EUtilities::Summary::DocSum
 786  Args     : none
 787  Notes    : only applicable for esummary
 788
 789 =cut
 790
 791 sub get_DocSums {
 792     my ($self, @args) = @_;
 793     return $self->get_Parser->get_DocSums(@args);
 794 }
 795
 796 =head2 print_DocSums
 797
 798  Title    : print_DocSums
 799  Usage    : $docsum->print_DocSums();
 800             $docsum->print_DocSums(-fh => $fh, -cb => $coderef);
 801  Function : prints item data for all docsums.  The default printing method is
 802             each item per DocSum is printed with relevant values if present
 803             in a simple table using Text::Wrap.
 804  Returns  : none
 805  Args     : [optional]
 806            -file : file to print to
 807            -fh   : filehandle to print to (cannot be used concurrently with file)
 808            -cb   : coderef to use in place of default print method.  This is passed
 809                    in a DocSum object;
 810            -wrap : number of columns to wrap default text output to (def = 80)
 811  Notes    : only applicable for esummary.  If -file or -fh are not defined,
 812             prints to STDOUT
 813
 814 =cut
 815
 816 sub print_DocSums {
 817     my ($self, @args) = @_;
 818     return $self->get_Parser->print_DocSums(@args);
 819 }
 820
 821 =head1 Info-related methods
 822
 823 =head2 get_available_databases
 824
 825  Title    : get_available_databases
 826  Usage    : my @dbs = $info->get_available_databases
 827  Function : returns list of available eutil-compatible database names
 828  Returns  : Array of strings
 829  Args     : none
 830  Notes    : only applicable for einfo.
 831
 832 =cut
 833
 834 sub get_available_databases {
 835     my ($self, @args) = @_;
 836     return $self->get_Parser->get_available_databases(@args);
 837 }
 838
 839 =head2 get_record_count
 840
 841  Title    : get_record_count
 842  Usage    : my $ct = $eutil->get_record_count;
 843  Function : returns database record count
 844  Returns  : integer
 845  Args     : none
 846  Notes    : only applicable for einfo.
 847
 848 =cut
 849
 850 sub get_record_count {
 851     my ($self, @args) = @_;
 852     return $self->get_Parser->get_record_count(@args);
 853 }
 854
 855 =head2 get_last_update
 856
 857  Title    : get_last_update
 858  Usage    : my $time = $info->get_last_update;
 859  Function : returns string containing time/date stamp for last database update
 860  Returns  : integer
 861  Args     : none
 862  Notes    : only applicable for einfo.
 863
 864 =cut
 865
 866 sub get_last_update {
 867     my ($self, @args) = @_;
 868     return $self->get_Parser->get_last_update(@args);
 869 }
 870
 871 =head2 get_menu_name
 872
 873  Title    : get_menu_name
 874  Usage    : my $nm = $info->get_menu_name;
 875  Function : returns string of database menu name
 876  Returns  : string
 877  Args     : none
 878  Notes    : only applicable for einfo.
 879
 880 =cut
 881
 882 sub get_menu_name {
 883     my ($self, @args) = @_;
 884     return $self->get_Parser->get_menu_name(@args);
 885 }
 886
 887 =head2 get_description
 888
 889  Title    : get_description
 890  Usage    : my $desc = $info->get_description;
 891  Function : returns database description
 892  Returns  : string
 893  Args     : none
 894  Notes    : only applicable for einfo.
 895
 896 =cut
 897
 898 sub get_description {
 899     my ($self, @args) = @_;
 900     return $self->get_Parser->get_description(@args);
 901 }
 902
 903 =head2 next_FieldInfo
 904
 905  Title    : next_FieldInfo
 906  Usage    : while (my $field = $info->next_FieldInfo) {...}
 907  Function : iterate through FieldInfo objects
 908  Returns  : Field object
 909  Args     : none
 910  Notes    : only applicable for einfo. Uses callback() for filtering if defined
 911             for 'fields'
 912
 913 =cut
 914
 915 sub next_FieldInfo {
 916     my ($self, @args) = @_;
 917     return $self->get_Parser->next_FieldInfo(@args);
 918 }
 919
 920 =head2 get_FieldInfo
 921
 922  Title    : get_FieldInfo
 923  Usage    : my @fields = $info->get_FieldInfo;
 924  Function : returns list of FieldInfo objects
 925  Returns  : array (FieldInfo objects)
 926  Args     : none
 927  Notes    : only applicable for einfo.
 928
 929 =cut
 930
 931 sub get_FieldInfo {
 932     my ($self, @args) = @_;
 933     return $self->get_Parser->get_FieldInfo(@args);
 934 }
 935
 936 *get_FieldInfos = \&get_FieldInfo;
 937
 938 =head2 next_LinkInfo
 939
 940  Title    : next_LinkInfo
 941  Usage    : while (my $link = $info->next_LinkInfo) {...}
 942  Function : iterate through LinkInfo objects
 943  Returns  : LinkInfo object
 944  Args     : none
 945  Notes    : only applicable for einfo.  Uses callback() for filtering if defined
 946             for 'linkinfo'
 947
 948 =cut
 949
 950 sub next_LinkInfo {
 951     my ($self, @args) = @_;
 952     return $self->get_Parser->next_LinkInfo(@args);
 953 }
 954
 955 =head2 get_LinkInfo
 956
 957  Title    : get_LinkInfo
 958  Usage    : my @links = $info->get_LinkInfo;
 959  Function : returns list of LinkInfo objects
 960  Returns  : array (LinkInfo objects)
 961  Args     : none
 962  Notes    : only applicable for einfo.
 963
 964 =cut
 965
 966 sub get_LinkInfo {
 967     my ($self, @args) = @_;
 968     return $self->get_Parser->get_LinkInfo(@args);
 969 }
 970
 971 *get_LinkInfos = \&get_LinkInfo;
 972
 973 =head2 print_FieldInfo
 974
 975  Title    : print_FieldInfo
 976  Usage    : $info->print_FieldInfo();
 977             $info->print_FieldInfo(-fh => $fh, -cb => $coderef);
 978  Function : prints field data for each FieldInfo object. The default method
 979             prints data from each FieldInfo in a simple table using Text::Wrap.
 980  Returns  : none
 981  Args     : [optional]
 982            -file : file to print to
 983            -fh   : filehandle to print to (cannot be used concurrently with file)
 984            -cb   : coderef to use in place of default print method.
 985            -wrap : number of columns to wrap default text output to (def = 80)
 986  Note     : if -file or -fh are not defined, prints to STDOUT
 987
 988 =cut
 989
 990 sub print_FieldInfo {
 991     my ($self, @args) = @_;
 992     return $self->get_Parser->print_FieldInfo(@args);
 993 }
 994
 995 =head2 print_LinkInfo
 996
 997  Title    : print_LinkInfo
 998  Usage    : $info->print_LinkInfo();
 999             $info->print_LinkInfo(-fh => $fh, -cb => $coderef);
1000  Function : prints link data for each LinkInfo object. The default is generated
1001             via LinkInfo::to_string
1002  Returns  : none
1003  Args     : [optional]
1004            -file : file to print to
1005            -fh   : filehandle to print to (cannot be used concurrently with file)
1006            -cb   : coderef to use in place of default print method.  This is passed
1007                    in a LinkInfo object;
1008            -wrap : number of columns to wrap default text output to (def = 80)
1009  Notes    : only applicable for einfo.  If -file or -fh are not defined,
1010             prints to STDOUT
1011
1012 =cut
1013
1014 sub print_LinkInfo {
1015     my ($self, @args) = @_;
1016     return $self->get_Parser->print_LinkInfo(@args);
1017 }
1018
1019 =head1 Bio::Tools::EUtilities::Link-related methods
1020
1021 =head2 next_LinkSet
1022
1023  Title    : next_LinkSet
1024  Usage    : while (my $ls = $eutil->next_LinkSet {...}
1025  Function : iterate through LinkSet objects
1026  Returns  : LinkSet object
1027  Args     : none
1028  Notes    : only applicable for elink.  Uses callback() for filtering if defined
1029             for 'linksets'
1030
1031 =cut
1032
1033 sub next_LinkSet {
1034     my ($self, @args) = @_;
1035     return $self->get_Parser->next_LinkSet(@args);
1036 }
1037
1038 =head2 get_LinkSets
1039
1040  Title    : get_LinkSets
1041  Usage    : my @links = $info->get_LinkSets;
1042  Function : returns list of LinkSets objects
1043  Returns  : array (LinkSet objects)
1044  Args     : none
1045  Notes    : only applicable for elink.
1046
1047 =cut
1048
1049 # add support for retrieval of data if lazy parsing is enacted
1050
1051 sub get_LinkSets {
1052     my ($self, @args) = @_;
1053     return $self->get_Parser->get_LinkSets(@args);
1054 }
1055
1056 =head2 print_LinkSets
1057
1058  Title    : print_LinkSets
1059  Usage    : $info->print_LinkSets();
1060             $info->print_LinkSets(-fh => $fh, -cb => $coderef);
1061  Function : prints link data for each LinkSet object. The default is generated
1062             via LinkSet::to_string
1063  Returns  : none
1064  Args     : [optional]
1065            -file : file to print to
1066            -fh   : filehandle to print to (cannot be used concurrently with file)
1067            -cb   : coderef to use in place of default print method.  This is passed
1068                    in a LinkSet object
1069            -wrap : number of columns to wrap default text output to (def = 80)
1070  Notes    : only applicable for einfo.  If -file or -fh are not defined,
1071             prints to STDOUT
1072
1073 =cut
1074
1075 sub print_LinkSets {
1076     my ($self, @args) = @_;
1077     return $self->get_Parser->print_LinkSets(@args);
1078 }
1079
1080 =head2 get_linked_databases
1081
1082  Title    : get_linked_databases
1083  Usage    : my @dbs = $eutil->get_linked_databases
1084  Function : returns list of databases linked to in linksets
1085  Returns  : array of databases
1086  Args     : none
1087  Notes    : only applicable for elink.
1088
1089 =cut
1090
1091 sub get_linked_databases {
1092     my ($self, @args) = @_;
1093     return $self->get_Parser->get_linked_databases(@args);
1094 }
1095
1096 =head1 Iterator- and callback-related methods
1097
1098 =cut
1099
1100 =head2 rewind
1101
1102  Title    : rewind
1103  Usage    : $esum->rewind()
1104             $esum->rewind('recursive')
1105  Function : retrieve a list of DocSum instances
1106  Returns  : array of Bio::Tools::EUtilities::Summary::DocSum
1107  Args     : [optional] Scalar; string ('all') to reset all iterators, or string
1108             describing the specific main object iterator to reset. The following
1109             are recognized (case-insensitive):
1110
1111             'all' - rewind all objects and also recursively resets nested object
1112                     interators (such as LinkSets and DocSums).
1113             'globalqueries'
1114             'fieldinfo' or 'fieldinfos'
1115             'linkinfo' or 'linkinfos'
1116             'linksets'
1117             'docsums'
1118
1119 =cut
1120
1121 sub rewind {
1122     my ($self, $string) = @_;
1123     return $self->get_Parser->rewind($string);
1124 }
1125
1126 =head2 generate_iterator
1127
1128  Title    : generate_iterator
1129  Usage    : my $coderef = $esum->generate_iterator('linkinfo')
1130  Function : generates an iterator (code reference) which iterates through
1131             the relevant object indicated by the args
1132  Returns  : code reference
1133  Args     : [REQUIRED] Scalar; string describing the specific object to iterate.
1134             The following are currently recognized (case-insensitive):
1135
1136             'globalqueries'
1137             'fieldinfo' or 'fieldinfos'
1138             'linkinfo' or 'linkinfos'
1139             'linksets'
1140             'docsums'
1141
1142             A second argument can also be passed to generate a 'lazy' iterator,
1143             which loops through and returns objects as they are created (instead
1144             of creating all data instances up front, then iterating through,
1145             which is the default). Use of these iterators precludes use of
1146             rewind() for the time being as we can't guarantee you can rewind(),
1147             as this depends on whether the data source is seek()able and thus
1148             'rewindable'. We will add rewind() support at a later time which
1149             will work for 'seekable' data.
1150
1151             A callback specified using callback() will be used to filter objects
1152             for any generated iterator. This behaviour is implemented for both
1153             normal and lazy iterator types and is the default. If you don't want
1154             this, make sure to reset any previously set callbacks via
1155             reset_callback() (which just deletes the code ref).
1156  TODO     : generate seekable iterators ala HOP for seekable fh data
1157
1158 =cut
1159
1160 sub generate_iterator {
1161     my ($self, @args) = @_;
1162     return $self->get_Parser->generate_iterator(@args);
1163 }
1164
1165 =head2 callback
1166
1167  Title    : callback
1168  Usage    : $parser->callback(sub {$_[0]->get_database eq 'protein'});
1169  Function : Get/set callback code ref used to filter returned data objects
1170  Returns  : code ref if previously set
1171  Args     : single argument:
1172             code ref - evaluates a passed object and returns true or false value
1173                        (used in iterators)
1174             'reset' - string, resets the iterator.
1175             returns upon any other args
1176
1177 =cut
1178
1179 sub callback {
1180     my ($self, @args) = @_;
1181     return $self->get_Parser->callback(@args);
1182 }
1183
1184 1;
1185 __END__