.\" 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::Tools::EUtilities 3pm"
.TH Bio::Tools::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::Tools::EUtilities \- NCBI eutil XML parsers.
.SH "VERSION"
.IX Header "VERSION"
version 1.75
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&  # from file or fh
\&  my $parser = Bio::Tools::EUtilities\->new(
\&                                       \-eutil    => \*(Aqeinfo\*(Aq,
\&                                       \-file     => \*(Aqoutput.xml\*(Aq
\&                                        );
\&
\&  # or HTTP::Response object...
\&  my $parser = Bio::Tools::EUtilities\->new(
\&                                       \-eutil => \*(Aqesearch\*(Aq,
\&                                       \-response => $response
\&                                        );
\&  # esearch, esummary, elink
\&  @ids = $parser\->get_ids(); # returns array or array ref of IDs
\&
\&  # egquery, espell
\&
\&  $term = $parser\->get_term(); # returns array or array ref of IDs
\&
\&  # elink, einfo
\&
\&  $db = $parser\->get_database(); # returns database
\&
\&  # Query\-related methods (esearch, egquery, espell data)
\&  # eutil data centered on use of search terms
\&
\&  my $ct = $parser\->get_count; # uses optional database for egquery count
\&  my $translation = $parser\->get_count;
\&
\&  my $corrected = $parser\->get_corrected_query; # espell
\&
\&  while (my $gquery = $parser\->next_GlobalQuery) {
\&     # iterates through egquery data
\&  }
\&
\&  # Info\-related methods (einfo data)
\&  # database\-related information
\&
\&  my $desc = $parser\->get_description;
\&  my $update = $parser\->get_last_update;
\&  my $nm = $parser\->get_menu_name;
\&  my $ct = $parser\->get_record_count;
\&
\&  while (my $field = $parser\->next_FieldInfo) {
\&      # ...
\&  }
\&  while (my $field = $parser\->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 = $parser\->next_History) {
\&      # ...
\&  }
\&
\&  my @hists = $parser\->get_Histories;
\&
\&  # Bio::Tools::EUtilities::Summary (esummary data)
\&  # information on a specific database record
\&
\&  # retrieve nested docsum data
\&  while (my $docsum = $parser\->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 = $parser\->next_DocSum) {
\&     my @items = $docsum\->get_all_DocSum_Items;
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Parses \s-1NCBI\s0 eutils \s-1XML\s0 output for retrieving IDs and other information. Part of
the BioPerl EUtilities system.
.PP
This is a general parser for eutils \s-1XML\s0; data from efetch is \s-1NOT\s0 parsed (this
requires separate format-dependent parsers). All other \s-1XML\s0 for eutils is parsed.
These modules can be used independently of Bio::DB::EUtilities and
Bio::Tools::EUtilities::EUtilParameters; if used in this way, only data present
in the \s-1XML\s0 will be parsed out (other bits are retrieved from a passed-in
Bio::Tools::EUtilities::EUtilParameters instance used while querying the
database)
.SH "TODO"
.IX Header "TODO"
This module is largely complete. However there are a few holes which will
eventually be filled in. TranslationSets from esearch are not currently parsed,
for instance.
.SS "Constructor methods"
.IX Subsection "Constructor methods"
.SS "new"
.IX Subsection "new"
.Vb 8
\& Title    : new
\& Usage    : my $parser = Bio::Tools::EUtilities\->new(\-file => \*(Aqmy.xml\*(Aq,
\&                                                    \-eutil => \*(Aqesearch\*(Aq);
\& Function : create Bio::Tools::EUtilities instance
\& Returns  : new Bio::Tools::EUtilities instance
\& Args     : \-file/\-fh \- File or filehandle
\&            \-eutil    \- eutil parser to use (supports all but efetch)
\&            \-response \- HTTP::Response object (optional)
.Ve
.SH "Bio::Tools::EUtilities methods"
.IX Header "Bio::Tools::EUtilities methods"
.SS "cache_response"
.IX Subsection "cache_response"
.Vb 6
\& Title    : cache_response
\& Usage    : $parser\->cache_response(1)
\& Function : sets flag to cache response object (off by default)
\& Returns  : value eval\*(Aqing to TRUE or FALSE
\& Args     : value eval\*(Aqing to TRUE or FALSE
\& Note     : must be set prior to any parsing run
.Ve
.SS "response"
.IX Subsection "response"
.Vb 6
\& Title    : response
\& Usage    : my $response = $parser\->response;
\& Function : Get/Set HTTP::Response object
\& Returns  : HTTP::Response
\& Args     : HTTP::Response
\& Note     : to prevent object from destruction set cache_response() to TRUE
.Ve
.SS "parameter_base"
.IX Subsection "parameter_base"
.Vb 8
\& Title    : parameter_base
\& Usage    : my $response = $parser\->parameter_base;
\& Function : Get/Set Bio::ParameterBaseI object (should be Bio::Tools::EUtilities::EUtilParameters)
\& Returns  : Bio::Tools::EUtilities::EUtilParameters || undef
\& Args     : (optional) Bio::Tools::EUtilities::EUtilParameters
\& Note     : If this object is present, it may be used as a last resort for
\&            some data values if parsed XML does not contain said values (for
\&            instance, database, term, IDs, etc).
.Ve
.SS "data_parsed"
.IX Subsection "data_parsed"
.Vb 7
\& Title    : data_parsed
\& Usage    : if ($parser\->data_parsed) {...}
\& Function : returns TRUE if data has been parsed
\& Returns  : value eval\*(Aqing to TRUE or FALSE
\& Args     : none (set within parser)
\& Note     : mainly internal method (set in case user wants to check
\&            whether parser is exhausted).
.Ve
.SS "is_lazy"
.IX Subsection "is_lazy"
.Vb 8
\& Title    : is_lazy
\& Usage    : if ($parser\->is_lazy) {...}
\& Function : returns TRUE if parser is set to lazy parsing mode
\&            (only affects elink/esummary)
\& Returns  : Boolean
\& Args     : none
\& Note     : Permanently set in constructor.  Still highly experimental.
\&            Don\*(Aqt stare directly at happy fun ball...
.Ve
.SS "parse_data"
.IX Subsection "parse_data"
.Vb 5
\& Title    : parse_data
\& Usage    : $parser\->parse_data
\& Function : direct call to parse data; normally implicitly called
\& Returns  : none
\& Args     : none
.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 the parser 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::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
.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 db/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
\&            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, or the available databases
\&            espell     : the queried database
\&            elink      : collected from each LinkSet
\&            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 (History 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, \-callback => $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 data is generated
\&            via DocSum::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 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 10
\& Title    : print_FieldInfo
\& Usage    : $info\->print_FieldInfo();
\&            $info\->print_FieldInfo(\-fh => $fh, \-cb => $coderef);
\& Function : prints link data for each FieldInfo object. The default is generated
\&            via FieldInfo::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 FieldInfo 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 "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.  Now defers to get_databases.
.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 \- GlobalQuery objects
\&            \*(Aqfieldinfo\*(Aq or \*(Aqfieldinfos\*(Aq \- FieldInfo objects
\&            \*(Aqlinkinfo\*(Aq or \*(Aqlinkinfos\*(Aq \- LinkInfo objects in this layer
\&            \*(Aqlinksets\*(Aq \- LinkSet objects
\&            \*(Aqdocsums\*(Aq \- DocSum objects
\&            \*(Aqhistories\*(Aq \- HistoryI objects (Cookies, LinkSets)
.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 (the latter sounds clumsy, but I alias it JIC)
\&            \*(Aqlinkinfo\*(Aq or \*(Aqlinkinfos\*(Aq (the latter sounds clumsy, but I alias it JIC)
\&            \*(Aqlinksets\*(Aq
\&            \*(Aqdocsums\*(Aq
\&            \*(Aqhistories\*(Aq
\&
\& Note     : This function generates a simple coderef that one can use
\&            independently of the various next_* functions (in fact, the next_*
\&            functions use lazily created iterators generated via this method,
\&            while rewind() merely deletes them so they can be regenerated on the
\&            next call).
\&
\&            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).  Note that setting
\&            callback() also changes the behavior of the next_* functions as the
\&            iterators are generated here (as described above); this is a feature
\&            and not a bug.
\&
\&            \*(AqLazy\*(Aq iterators are considered an experimental feature and may be
\&            modified in the future. 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) is returned if the
\&            parser is set to \*(Aqlazy\*(Aq mode. This mode is only present for elink
\&            and esummary output as they are the two formats parsed which can
\&            generate potentially thousands of individual objects (note efetch
\&            isn\*(Aqt parsed, so isn\*(Aqt counted). Use of rewind() with these
\&            iterators is not supported 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 or possibly cached
\&            objects via Storable or BDB.
.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.