.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Bio::DB::EUtilities 3pm"
.TH Bio::DB::EUtilities 3pm "2018-09-06" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::DB::EUtilities \- Webagent which interacts with and retrieves data from NCBI's eUtils.
.SH "VERSION"
.IX Header "VERSION"
version 1.75
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\&  my $eutil = Bio::DB::EUtilities\->new(
\&    \-eutil      => \*(Aqesearch\*(Aq,
\&    \-term       => \*(AqBRCA1\*(Aq,
\&    \-db         => \*(Aqpubmed\*(Aq,
\&    \-retmax     => 10000,
\&    \-email      => \*(Aqfoo@bar.org\*(Aq); # please use your real email
\&
\&  # eutil => any of esearch, esummary, elink
\&  @ids = $eutil\->get_ids(); # returns array or array ref of IDs
\&
\&  # eutil => any of egquery, espell
\&
\&  $term = $eutil\->get_term(); # returns array or array ref of IDs
\&
\&  # eutil => any of elink, einfo
\&
\&  $db = $eutil\->get_database(); # returns database
\&
\&  # Query\-related methods (esearch, egquery, espell data)
\&  # eutil data centered on use of search terms
\&
\&  my $ct = $eutil\->get_count; # uses optional database for egquery count
\&  my $translation = $eutil\->get_count;
\&
\&  my $corrected = $eutil\->get_corrected_query; # espell
\&
\&  while (my $gquery = $eutil\->next_GlobalQuery) {
\&     # iterates through egquery data
\&  }
\&
\&  # Info\-related methods (einfo data)
\&  # database\-related information
\&
\&  my $desc = $eutil\->get_description;
\&  my $update = $eutil\->get_last_update;
\&  my $nm = $eutil\->get_menu_name;
\&  my $ct = $eutil\->get_record_count;
\&
\&  while (my $field = $eutil\->next_FieldInfo) {
\&      # ...
\&  }
\&  while (my $field = $eutil\->next_LinkInfo) {
\&      # ...
\&  }
\&
\&  # History methods (epost data, some data returned from elink)
\&  # data which enables one to retrieve and query against user\-stored
\&  # information on the NCBI server
\&
\&  while (my $cookie = $eutil\->next_History) {
\&      # ...
\&  }
\&
\&  my @hists = $eutil\->get_Histories;
\&
\&  # Bio::Tools::EUtilities::Summary (esummary data)
\&  # information on a specific database record
\&
\&  # retrieve nested docsum data
\&  while (my $docsum = $eutil\->next_DocSum) {
\&      print "ID:",$docsum\->get_ids,"\en";
\&      while (my $item = $docsum\->next_Item) {
\&          # do stuff here...
\&          while (my $listitem = $docsum\->next_ListItem) {
\&              # do stuff here...
\&              while (my $listitem = $docsum\->next_Structure) {
\&                  # do stuff here...
\&              }
\&          }
\&      }
\&  }
\&
\&  # retrieve flattened item list per DocSum
\&  while (my $docsum = $eutil\->next_DocSum) {
\&     my @items = $docsum\->get_all_DocSum_Items;
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a general webagent which posts and retrieves data to \s-1NCBI\s0's eUtils
service using their \s-1CGI\s0 interface. A separate project, currently present in
BioPerl-Run, utilizes the SOAP-based interface for eUtils.
.PP
A full explanation of the eUtils interfaces are not possible within this short
module; please see the BioPerl wiki \s-1HOWTO\s0 for more details.
.SH "METHODS"
.IX Header "METHODS"
.SS ""
.IX Subsection ""
.SH "TODO"
.IX Header "TODO"
.IP "\(bu" 3
Finish documentation
.Sp
HOWTOs (both standard and Cookbook).
.IP "\(bu" 3
Cookbook tests
.Sp
Set up dev-only tests for Cookbook examples to make sure they are consistently
updated.
.IP "\(bu" 3
\&\s-1API\s0
.Sp
Mark Jensen has written up the SOAP-based eUtil modules, maybe we should
coalesce around a consistent \s-1API\s0 between the two (they are close).
.IP "\(bu" 3
Carryover of parameters
.Sp
Maybe add a default but configurable list of parameters that can be carried over
between calls.
.IP "\(bu" 3
Make setting certain parameters consistent
.Sp
Setting history is a bit inconsistent, so maybe use a common alias for this?
.IP "\(bu" 3
Moosify?
.Sp
Not necessary, but it might make things easier and more maintainable in the long
run.
.SH "Bio::DB::GenericWebAgent methods"
.IX Header "Bio::DB::GenericWebAgent methods"
.SH "GenericWebDBI methods"
.IX Header "GenericWebDBI methods"
.SS "parameter_base"
.IX Subsection "parameter_base"
.Vb 5
\& Title   : parameter_base
\& Usage   : $dbi\->parameter_base($pobj);
\& Function: Get/Set Bio::ParameterBaseI.
\& Returns : Bio::ParameterBaseI object
\& Args    : Bio::ParameterBaseI object
.Ve
.SS "ua"
.IX Subsection "ua"
.Vb 5
\& Title   : ua
\& Usage   : $dbi\->ua;
\& Function: Get/Set LWP::UserAgent.
\& Returns : LWP::UserAgent
\& Args    : LWP::UserAgent
.Ve
.SS "get_Response"
.IX Subsection "get_Response"
.Vb 6
\& Title   : get_Response
\& Usage   : $agent\->get_Response;
\& Function: Get the HTTP::Response object by passing it an HTTP::Request (generated from
\&           Bio::ParameterBaseI implementation).
\& Returns : HTTP::Response object or data if callback is used
\& Args    : (optional)
\&
\&           \-cache_response \- flag to cache HTTP::Response object;
\&                             Default is 1 (TRUE, caching ON)
\&
\&           These are passed on to LWP::UserAgent::request() if stipulated
\&
\&           \-cb     \- use a LWP::UserAgent\-compliant callback
\&           \-file   \- dumps the response to a file (handy for large responses)
\&                     Note: can\*(Aqt use file and callback at the same time
\&           \-read_size_hint \- bytes of content to read in at a time to pass to callback
\& Note    : Caching and parameter checking are set
.Ve
.SS "delay"
.IX Subsection "delay"
.Vb 5
\& Title   : delay
\& Usage   : $secs = $self\->delay([$secs])
\& Function: get/set number of seconds to delay between fetches
\& Returns : number of seconds to delay
\& Args    : new value
.Ve
.PP
\&\s-1NOTE:\s0 the default is to use the value specified by \fIdelay_policy()\fR.
This can be overridden by calling this method.
.SH "LWP::UserAgent related methods"
.IX Header "LWP::UserAgent related methods"
.SS "proxy"
.IX Subsection "proxy"
.Vb 9
\& Title   : proxy
\& Usage   : $httpproxy = $db\->proxy(\*(Aqhttp\*(Aq)  or
\&           $db\->proxy([\*(Aqhttp\*(Aq,\*(Aqftp\*(Aq], \*(Aqhttp://myproxy\*(Aq )
\& Function: Get/Set a proxy for use of proxy
\& Returns : a string indicating the proxy
\& Args    : $protocol : an array ref of the protocol(s) to set/get
\&           $proxyurl : url of the proxy to use for the specified protocol
\&           $username : username (if proxy requires authentication)
\&           $password : password (if proxy requires authentication)
.Ve
.SS "authentication"
.IX Subsection "authentication"
.Vb 5
\& Title   : authentication
\& Usage   : $db\->authentication($user,$pass)
\& Function: Get/Set authentication credentials
\& Returns : Array of user/pass
\& Args    : Array or user/pass
.Ve
.SS "delay_policy"
.IX Subsection "delay_policy"
.Vb 5
\&  Title   : delay_policy
\&  Usage   : $secs = $self\->delay_policy
\&  Function: return number of seconds to delay between calls to remote db
\&  Returns : number of seconds to delay
\&  Args    : none
\&
\&  NOTE: NCBI requests a delay of 3 requests per second. This method implements
\&  that policy. This will likely change to check time of day or number of
\&  requests for lengthening delays.
.Ve
.SS "get_Parser"
.IX Subsection "get_Parser"
.Vb 7
\& Title   : get_Parser
\& Usage   : $agent\->get_Parser;
\& Function: Retrieve the parser used for last agent request
\& Returns : The Bio::Tools::EUtilities parser used to parse the HTTP::Response
\&           content
\& Args    : None
\& Note    : Abstract method; defined by implementation
.Ve
.SH "Bio::Tools::EUtilities::EUtilParameters\-delegating methods"
.IX Header "Bio::Tools::EUtilities::EUtilParameters-delegating methods"
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\->method' when needed.
.SS "set_parameters"
.IX Subsection "set_parameters"
.Vb 7
\& Title   : set_parameters
\& Usage   : $pobj\->set_parameters(@params);
\& Function: sets the NCBI parameters listed in the hash or array
\& Returns : None
\& Args    : [optional] hash or array of parameter/values.
\& Note    : This sets any parameter (i.e. doesn\*(Aqt screen them).  In addition to
\&           regular eutil\-specific parameters, you can set the following:
\&
\&           \-eutil    \- the eUtil to be used (default \*(Aqefetch\*(Aq)
\&           \-history  \- pass a HistoryI\-implementing object, which
\&                       sets the WebEnv, query_key, and possibly db and linkname
\&                       (the latter two only for LinkSets)
\&           \-correspondence \- Boolean flag, set to TRUE or FALSE; indicates how
\&                       IDs are to be added together for elink request where
\&                       ID correspondence might be needed
\&                       (default 0)
.Ve
.SS "reset_parameters"
.IX Subsection "reset_parameters"
.Vb 7
\& Title   : reset_parameters
\& Usage   : resets values
\& Function: resets parameters to either undef or value in passed hash
\& Returns : none
\& Args    : [optional] hash of parameter\-value pairs
\& Note    : this also resets eutil(), correspondence(), and the history and request
\&           cache
.Ve
.SS "available_parameters"
.IX Subsection "available_parameters"
.Vb 7
\& Title   : available_parameters
\& Usage   : @params = $pobj\->available_parameters()
\& Function: Returns a list of the available parameters
\& Returns : Array of available parameters (no values)
\& Args    : [optional] A string; either eutil name (for returning eutil\-specific
\&           parameters) or \*(Aqhistory\*(Aq (for those parameters allowed when retrieving
\&           data stored on the remote server using a \*(AqHistory\*(Aq object).
.Ve
.SS "get_parameters"
.IX Subsection "get_parameters"
.Vb 11
\& Title   : get_parameters
\& Usage   : @params = $pobj\->get_parameters;
\&           %params = $pobj\->get_parameters;
\& Function: Returns list of key/value pairs, parameter => value
\& Returns : Flattened list of key\-value pairs. All key\-value pairs returned,
\&           though subsets can be returned based on the \*(Aq\-type\*(Aq parameter.
\&           Data passed as an array ref are returned based on whether the
\&           \*(Aq\-join_id\*(Aq flag is set (default is the same array ref).
\& Args    : \-type : the eutil name or \*(Aqhistory\*(Aq, for returning a subset of
\&                parameters (Default: returns all)
\&           \-join_ids : Boolean; join IDs based on correspondence (Default: no join)
.Ve
.SS "get_parameter_values"
.IX Subsection "get_parameter_values"
.Vb 5
\& Title   : get_parameter_values
\& Usage   : @vals = $factory\->get_parameter_value(\*(Aqid\*(Aq); # always get array
\& Function: Returns the specific parameter values.
\& Returns : For consistency returns a list of values for this parameter.  If only
\&           one is expected, use:
\&
\&           ($val) = $factory\->get_parameter_value(\*(Aqid\*(Aq);
\&
\& Args    : parameter expected
.Ve
.SH "Bio::Tools::EUtilities\-delegating methods"
.IX Header "Bio::Tools::EUtilities-delegating methods"
.SH "Bio::Tools::EUtilities::EUtilDataI methods"
.IX Header "Bio::Tools::EUtilities::EUtilDataI methods"
.SS "eutil"
.IX Subsection "eutil"
.Vb 6
\& Title    : eutil
\& Usage    : $eutil\->$foo\->eutil
\& Function : Get/Set eutil
\& Returns  : string
\& Args     : string (eutil)
\& Throws   : on invalid eutil
.Ve
.SS "datatype"
.IX Subsection "datatype"
.Vb 5
\& Title    : datatype
\& Usage    : $type = $foo\->datatype;
\& Function : Get/Set data object type
\& Returns  : string
\& Args     : string
.Ve
.SS "to_string"
.IX Subsection "to_string"
.Vb 6
\& Title    : to_string
\& Usage    : $foo\->to_string()
\& Function : converts current object to string
\& Returns  : none
\& Args     : (optional) simple data for text formatting
\& Note     : Implemented in plugins
.Ve
.SS "print_all"
.IX Subsection "print_all"
.Vb 10
\& Title    : print_all
\& Usage    : $info\->print_all();
\&            $info\->print_all(\-fh => $fh, \-cb => $coderef);
\& Function : prints (dumps) all data in parser.  Unless a coderef is supplied,
\&            this just dumps the parser\-specific to_string method to either a
\&            file/fh or STDOUT
\& Returns  : none
\& Args     : [optional]
\&           \-file : file to print to
\&           \-fh   : filehandle to print to (cannot be used concurrently with file)
\&           \-cb   : coderef to use in place of default print method.  This is passed
\&                   in a LinkSet object
\&           \-wrap : number of columns to wrap default text output to (def = 80)
\& Notes    : only applicable for einfo.  If \-file or \-fh are not defined,
\&            prints to STDOUT
.Ve
.SH "Methods useful for multiple eutils"
.IX Header "Methods useful for multiple eutils"
.SS "get_ids"
.IX Subsection "get_ids"
.Vb 12
\& Title    : get_ids
\& Usage    : my @ids = $parser\->get_ids
\& 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. In such cases, if a db name isn\*(Aqt 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
.Ve
.SS "get_database"
.IX Subsection "get_database"
.Vb 10
\& Title    : get_database
\& Usage    : my $db = $info\->get_database;
\& Function : returns single database name (eutil\-compatible).  This is the queried
\&            database.  For most eutils this is straightforward.  For elinks
\&            (which have \*(Aqdb\*(Aq and \*(Aqdbfrom\*(Aq) this is dbto, for egquery, it is the first
\&            db in the list (you probably want get_databases instead)
\& Returns  : string
\& Args     : none
\& 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
.Ve
.SS "get_db (alias for get_database)"
.IX Subsection "get_db (alias for get_database)"
.SS "get_databases"
.IX Subsection "get_databases"
.Vb 7
\& 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
.Ve
.SS "get_dbs (alias for get_databases)"
.IX Subsection "get_dbs (alias for get_databases)"
.SS "next_History"
.IX Subsection "next_History"
.Vb 10
\& Title    : next_History
\& Usage    : while (my $hist=$parser\->next_History) {...}
\& Function : returns next HistoryI (if present).
\& Returns  : Bio::Tools::EUtilities::HistoryI (Cookie or LinkSet)
\& Args     : none
\& 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
\&            allows one to retrieve said data one piece at a time.
.Ve
.SS "next_cookie (alias for next_History)"
.IX Subsection "next_cookie (alias for next_History)"
.SS "get_Histories"
.IX Subsection "get_Histories"
.Vb 5
\& Title    : get_Histories
\& Usage    : my @hists = $parser\->get_Histories
\& Function : returns list of HistoryI objects.
\& Returns  : list of Bio::Tools::EUtilities::HistoryI (Cookie or LinkSet)
\& Args     : none
.Ve
.SH "Query-related methods"
.IX Header "Query-related methods"
.SS "get_count"
.IX Subsection "get_count"
.Vb 9
\& Title    : get_count
\& Usage    : my $ct = $parser\->get_count
\& Function : returns the count (hits for a search)
\& 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
.Ve
.SS "get_term"
.IX Subsection "get_term"
.Vb 9
\& Title    : get_term
\& Usage    : $st = $qd\->get_term;
\& Function : retrieve the term for the global search
\& Returns  : string
\& Args     : none
\& Notes    : egquery    : search term
\&            espell     : search term
\&            esearch    : from parameter_base\->term or undef
\&            all others : undef
.Ve
.SS "get_translation_from"
.IX Subsection "get_translation_from"
.Vb 6
\& Title   : get_translation_from
\& Usage   : $string = $qd\->get_translation_from();
\& Function: portion of the original query replaced with translated_to()
\& Returns : string
\& Args    : none
\& Note    : only applicable for esearch
.Ve
.SS "get_translation_to"
.IX Subsection "get_translation_to"
.Vb 6
\& Title   : get_translation_to
\& Usage   : $string = $qd\->get_translation_to();
\& Function: replaced string used in place of the original query term in translation_from()
\& Returns : string
\& Args    : none
\& Note    : only applicable for esearch
.Ve
.SS "get_retstart"
.IX Subsection "get_retstart"
.Vb 8
\& 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
.Ve
.SS "get_retmax"
.IX Subsection "get_retmax"
.Vb 8
\& 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
.Ve
.SS "get_query_translation"
.IX Subsection "get_query_translation"
.Vb 7
\& Title   : get_query_translation
\& Usage   : $string = $qd\->get_query_translation();
\& Function: returns the translated query used for the search (if any)
\& Returns : string
\& Args    : none
\& Notes   : only applicable for esearch.  This is the actual term used for
\&           esearch.
.Ve
.SS "get_corrected_query"
.IX Subsection "get_corrected_query"
.Vb 6
\& Title    : get_corrected_query
\& Usage    : my $cor = $eutil\->get_corrected_query;
\& Function : retrieves the corrected query when using espell
\& Returns  : string
\& Args     : none
\& Notes    : only applicable for espell.
.Ve
.SS "get_replaced_terms"
.IX Subsection "get_replaced_terms"
.Vb 6
\& Title    : get_replaced_terms
\& Usage    : my $term = $eutil\->get_replaced_terms
\& Function : returns array of strings replaced in the query
\& Returns  : string
\& Args     : none
\& Notes    : only applicable for espell
.Ve
.SS "next_GlobalQuery"
.IX Subsection "next_GlobalQuery"
.Vb 6
\& Title    : next_GlobalQuery
\& Usage    : while (my $query = $eutil\->next_GlobalQuery) {...}
\& Function : iterates through the queries returned from an egquery search
\& Returns  : GlobalQuery object
\& Args     : none
\& Notes    : only applicable for egquery
.Ve
.SS "get_GlobalQueries"
.IX Subsection "get_GlobalQueries"
.Vb 6
\& Title    : get_GlobalQueries
\& Usage    : @queries = $eutil\->get_GlobalQueries
\& Function : returns list of GlobalQuery objects
\& Returns  : array of GlobalQuery objects
\& Args     : none
\& Notes    : only applicable for egquery
.Ve
.SS "print_GlobalQueries"
.IX Subsection "print_GlobalQueries"
.Vb 10
\& Title    : print_GlobalQueries
\& Usage    : $docsum\->print_GlobalQueries();
\&            $docsum\->print_GlobalQueries(\-fh => $fh, \-cb => $coderef);
\& Function : prints item data for all global queries.  The default printing
\&            method is each item per DocSum is printed with relevant values if
\&            present in a simple table using Text::Wrap.
\& Returns  : none
\& Args     : [optional]
\&           \-file : file to print to
\&           \-fh   : filehandle to print to (cannot be used concurrently with file)
\&           \-cb   : coderef to use in place of default print method.  This is passed
\&                   in a GlobalQuery object;
\&           \-wrap : number of columns to wrap default text output to (def = 80)
\& Notes    : only applicable for esummary.  If \-file or \-fh are not defined,
\&            prints to STDOUT
.Ve
.SH "Summary-related methods"
.IX Header "Summary-related methods"
.SS "next_DocSum"
.IX Subsection "next_DocSum"
.Vb 6
\& Title    : next_DocSum
\& Usage    : while (my $ds = $esum\->next_DocSum) {...}
\& Function : iterate through DocSum instances
\& Returns  : single Bio::Tools::EUtilities::Summary::DocSum
\& Args     : none yet
\& Notes    : only applicable for esummary
.Ve
.SS "get_DocSums"
.IX Subsection "get_DocSums"
.Vb 6
\& Title    : get_DocSums
\& Usage    : my @docsums = $esum\->get_DocSums
\& Function : retrieve a list of DocSum instances
\& Returns  : array of Bio::Tools::EUtilities::Summary::DocSum
\& Args     : none
\& Notes    : only applicable for esummary
.Ve
.SS "print_DocSums"
.IX Subsection "print_DocSums"
.Vb 10
\& Title    : print_DocSums
\& Usage    : $docsum\->print_DocSums();
\&            $docsum\->print_DocSums(\-fh => $fh, \-cb => $coderef);
\& Function : prints item data for all docsums.  The default printing method is
\&            each item per DocSum is printed with relevant values if present
\&            in a simple table using Text::Wrap.
\& Returns  : none
\& Args     : [optional]
\&           \-file : file to print to
\&           \-fh   : filehandle to print to (cannot be used concurrently with file)
\&           \-cb   : coderef to use in place of default print method.  This is passed
\&                   in a DocSum object;
\&           \-wrap : number of columns to wrap default text output to (def = 80)
\& Notes    : only applicable for esummary.  If \-file or \-fh are not defined,
\&            prints to STDOUT
.Ve
.SH "Info-related methods"
.IX Header "Info-related methods"
.SS "get_available_databases"
.IX Subsection "get_available_databases"
.Vb 6
\& Title    : get_available_databases
\& Usage    : my @dbs = $info\->get_available_databases
\& Function : returns list of available eutil\-compatible database names
\& Returns  : Array of strings
\& Args     : none
\& Notes    : only applicable for einfo.
.Ve
.SS "get_record_count"
.IX Subsection "get_record_count"
.Vb 6
\& Title    : get_record_count
\& Usage    : my $ct = $eutil\->get_record_count;
\& Function : returns database record count
\& Returns  : integer
\& Args     : none
\& Notes    : only applicable for einfo.
.Ve
.SS "get_last_update"
.IX Subsection "get_last_update"
.Vb 6
\& Title    : get_last_update
\& Usage    : my $time = $info\->get_last_update;
\& Function : returns string containing time/date stamp for last database update
\& Returns  : integer
\& Args     : none
\& Notes    : only applicable for einfo.
.Ve
.SS "get_menu_name"
.IX Subsection "get_menu_name"
.Vb 6
\& Title    : get_menu_name
\& Usage    : my $nm = $info\->get_menu_name;
\& Function : returns string of database menu name
\& Returns  : string
\& Args     : none
\& Notes    : only applicable for einfo.
.Ve
.SS "get_description"
.IX Subsection "get_description"
.Vb 6
\& Title    : get_description
\& Usage    : my $desc = $info\->get_description;
\& Function : returns database description
\& Returns  : string
\& Args     : none
\& Notes    : only applicable for einfo.
.Ve
.SS "next_FieldInfo"
.IX Subsection "next_FieldInfo"
.Vb 7
\& Title    : next_FieldInfo
\& Usage    : while (my $field = $info\->next_FieldInfo) {...}
\& Function : iterate through FieldInfo objects
\& Returns  : Field object
\& Args     : none
\& Notes    : only applicable for einfo. Uses callback() for filtering if defined
\&            for \*(Aqfields\*(Aq
.Ve
.SS "get_FieldInfo"
.IX Subsection "get_FieldInfo"
.Vb 6
\& Title    : get_FieldInfo
\& Usage    : my @fields = $info\->get_FieldInfo;
\& Function : returns list of FieldInfo objects
\& Returns  : array (FieldInfo objects)
\& Args     : none
\& Notes    : only applicable for einfo.
.Ve
.SS "next_LinkInfo"
.IX Subsection "next_LinkInfo"
.Vb 7
\& Title    : next_LinkInfo
\& Usage    : while (my $link = $info\->next_LinkInfo) {...}
\& Function : iterate through LinkInfo objects
\& Returns  : LinkInfo object
\& Args     : none
\& Notes    : only applicable for einfo.  Uses callback() for filtering if defined
\&            for \*(Aqlinkinfo\*(Aq
.Ve
.SS "get_LinkInfo"
.IX Subsection "get_LinkInfo"
.Vb 6
\& Title    : get_LinkInfo
\& Usage    : my @links = $info\->get_LinkInfo;
\& Function : returns list of LinkInfo objects
\& Returns  : array (LinkInfo objects)
\& Args     : none
\& Notes    : only applicable for einfo.
.Ve
.SS "print_FieldInfo"
.IX Subsection "print_FieldInfo"
.Vb 12
\& Title    : print_FieldInfo
\& Usage    : $info\->print_FieldInfo();
\&            $info\->print_FieldInfo(\-fh => $fh, \-cb => $coderef);
\& Function : prints field data for each FieldInfo object. The default method
\&            prints data from each FieldInfo in a simple table using Text::Wrap.
\& Returns  : none
\& Args     : [optional]
\&           \-file : file to print to
\&           \-fh   : filehandle to print to (cannot be used concurrently with file)
\&           \-cb   : coderef to use in place of default print method.
\&           \-wrap : number of columns to wrap default text output to (def = 80)
\& Note     : if \-file or \-fh are not defined, prints to STDOUT
.Ve
.SS "print_LinkInfo"
.IX Subsection "print_LinkInfo"
.Vb 10
\& Title    : print_LinkInfo
\& Usage    : $info\->print_LinkInfo();
\&            $info\->print_LinkInfo(\-fh => $fh, \-cb => $coderef);
\& Function : prints link data for each LinkInfo object. The default is generated
\&            via LinkInfo::to_string
\& Returns  : none
\& Args     : [optional]
\&           \-file : file to print to
\&           \-fh   : filehandle to print to (cannot be used concurrently with file)
\&           \-cb   : coderef to use in place of default print method.  This is passed
\&                   in a LinkInfo object;
\&           \-wrap : number of columns to wrap default text output to (def = 80)
\& Notes    : only applicable for einfo.  If \-file or \-fh are not defined,
\&            prints to STDOUT
.Ve
.SH "Bio::Tools::EUtilities::Link\-related methods"
.IX Header "Bio::Tools::EUtilities::Link-related methods"
.SS "next_LinkSet"
.IX Subsection "next_LinkSet"
.Vb 7
\& Title    : next_LinkSet
\& Usage    : while (my $ls = $eutil\->next_LinkSet {...}
\& Function : iterate through LinkSet objects
\& Returns  : LinkSet object
\& Args     : none
\& Notes    : only applicable for elink.  Uses callback() for filtering if defined
\&            for \*(Aqlinksets\*(Aq
.Ve
.SS "get_LinkSets"
.IX Subsection "get_LinkSets"
.Vb 6
\& Title    : get_LinkSets
\& Usage    : my @links = $info\->get_LinkSets;
\& Function : returns list of LinkSets objects
\& Returns  : array (LinkSet objects)
\& Args     : none
\& Notes    : only applicable for elink.
.Ve
.SS "print_LinkSets"
.IX Subsection "print_LinkSets"
.Vb 10
\& Title    : print_LinkSets
\& Usage    : $info\->print_LinkSets();
\&            $info\->print_LinkSets(\-fh => $fh, \-cb => $coderef);
\& Function : prints link data for each LinkSet object. The default is generated
\&            via LinkSet::to_string
\& Returns  : none
\& Args     : [optional]
\&           \-file : file to print to
\&           \-fh   : filehandle to print to (cannot be used concurrently with file)
\&           \-cb   : coderef to use in place of default print method.  This is passed
\&                   in a LinkSet object
\&           \-wrap : number of columns to wrap default text output to (def = 80)
\& Notes    : only applicable for einfo.  If \-file or \-fh are not defined,
\&            prints to STDOUT
.Ve
.SS "get_linked_databases"
.IX Subsection "get_linked_databases"
.Vb 6
\& Title    : get_linked_databases
\& Usage    : my @dbs = $eutil\->get_linked_databases
\& Function : returns list of databases linked to in linksets
\& Returns  : array of databases
\& Args     : none
\& Notes    : only applicable for elink.
.Ve
.SH "Iterator\- and callback-related methods"
.IX Header "Iterator- and callback-related methods"
.SS "rewind"
.IX Subsection "rewind"
.Vb 8
\& Title    : rewind
\& Usage    : $esum\->rewind()
\&            $esum\->rewind(\*(Aqrecursive\*(Aq)
\& Function : retrieve a list of DocSum instances
\& Returns  : array of Bio::Tools::EUtilities::Summary::DocSum
\& Args     : [optional] Scalar; string (\*(Aqall\*(Aq) to reset all iterators, or string
\&            describing the specific main object iterator to reset. The following
\&            are recognized (case\-insensitive):
\&
\&            \*(Aqall\*(Aq \- rewind all objects and also recursively resets nested object
\&                    interators (such as LinkSets and DocSums).
\&            \*(Aqglobalqueries\*(Aq
\&            \*(Aqfieldinfo\*(Aq or \*(Aqfieldinfos\*(Aq
\&            \*(Aqlinkinfo\*(Aq or \*(Aqlinkinfos\*(Aq
\&            \*(Aqlinksets\*(Aq
\&            \*(Aqdocsums\*(Aq
.Ve
.SS "generate_iterator"
.IX Subsection "generate_iterator"
.Vb 7
\& Title    : generate_iterator
\& Usage    : my $coderef = $esum\->generate_iterator(\*(Aqlinkinfo\*(Aq)
\& Function : generates an iterator (code reference) which iterates through
\&            the relevant object indicated by the args
\& Returns  : code reference
\& Args     : [REQUIRED] Scalar; string describing the specific object to iterate.
\&            The following are currently recognized (case\-insensitive):
\&
\&            \*(Aqglobalqueries\*(Aq
\&            \*(Aqfieldinfo\*(Aq or \*(Aqfieldinfos\*(Aq
\&            \*(Aqlinkinfo\*(Aq or \*(Aqlinkinfos\*(Aq
\&            \*(Aqlinksets\*(Aq
\&            \*(Aqdocsums\*(Aq
\&
\&            A second argument can also be passed to generate a \*(Aqlazy\*(Aq iterator,
\&            which loops through and returns objects as they are created (instead
\&            of creating all data instances up front, then iterating through,
\&            which is the default). Use of these iterators precludes use of
\&            rewind() for the time being as we can\*(Aqt guarantee you can rewind(),
\&            as this depends on whether the data source is seek()able and thus
\&            \*(Aqrewindable\*(Aq. We will add rewind() support at a later time which
\&            will work for \*(Aqseekable\*(Aq data.
\&
\&            A callback specified using callback() will be used to filter objects
\&            for any generated iterator. This behaviour is implemented for both
\&            normal and lazy iterator types and is the default. If you don\*(Aqt want
\&            this, make sure to reset any previously set callbacks via
\&            reset_callback() (which just deletes the code ref).
\& TODO     : generate seekable iterators ala HOP for seekable fh data
.Ve
.SS "callback"
.IX Subsection "callback"
.Vb 9
\& Title    : callback
\& Usage    : $parser\->callback(sub {$_[0]\->get_database eq \*(Aqprotein\*(Aq});
\& Function : Get/set callback code ref used to filter returned data objects
\& Returns  : code ref if previously set
\& Args     : single argument:
\&            code ref \- evaluates a passed object and returns true or false value
\&                       (used in iterators)
\&            \*(Aqreset\*(Aq \- string, resets the iterator.
\&            returns upon any other args
.Ve
.SH "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing lists"
.IX Subsection "Mailing lists"
User feedback is an integral part of the evolution of this and other
Bioperl modules. Send your comments and suggestions preferably to
the Bioperl mailing list.  Your participation is much appreciated.
.PP
.Vb 2
\&  bioperl\-l@bioperl.org                  \- General discussion
\&  http://bioperl.org/wiki/Mailing_lists  \- About the mailing lists
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
\&\fIbioperl\-l@bioperl.org\fR
.PP
rather than to the module maintainer directly. Many experienced and
reponsive experts will be able look at the problem and quickly
address it. Please include a thorough description of the problem
with code and data examples if at all possible.
.SS "Reporting bugs"
.IX Subsection "Reporting bugs"
Report bugs to the Bioperl bug tracking system to help us keep track
of the bugs and their resolution. Bug reports can be submitted via the
web:
.PP
.Vb 1
\&  https://github.com/bioperl/%%7Bdist%7D
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Chris Fields <cjfields@bioperl.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This software is copyright (c) 2006\-2013 by Chris Fields.
.PP
This software is available under the same terms as the perl 5 programming language system itself.