Provided by: libbio-perl-perl_1.6.901-2_all bug

NAME

       Bio::Tools::EUtilities::EUtilParameters - Manipulation of NCBI eutil-based parameters for
       remote database requests.

SYNOPSIS

        # Bio::Tools::EUtilities::EUtilParameters implements Bio::ParameterBaseI

        my @params = (-eutil => 'efetch',
                     db => 'nucleotide',
                     id => \@ids,
                     email => 'me@foo.bar',
                     retmode => 'xml');

        my $p = Bio::Tools::EUtilities::EUtilParameters->new(@params);

        if ($p->parameters_changed) {
                                     # ...
                                    } # state information

        $p->set_parameters(@extra_params); # set new NCBI parameters, leaves others preset

        $p->reset_parameters(@new_params); # reset NCBI parameters to original state

        $p->to_string(); # get a URI-encoded string representation of the URL address

        $p->to_request(); # get an HTTP::Request object (to pass on to LWP::UserAgent)

DESCRIPTION

       Bio::Tools::EUtilities::EUtilParameters is-a Bio::ParameterBaseI implementation that
       allows simple manipulation of NCBI eutil parameters for CGI-based queries.  SOAP-based
       methods may be added in the future.

       For simplicity parameters do not require dashes when passed and do not need URI encoding
       (spaces are converted to '+', symbols encoded, etc). Also, the following extra parameters
       can be passed to the new() constructor or via set_parameters() or reset_parameters():

         eutil - the eutil to be used. The default is 'efetch' if not set.
         correspondence - Flag for how IDs are treated. Default is undef (none).
         history - a Bio::Tools::EUtilities::HistoryI object. Default is undef (none).

       At this point minimal checking is done for potential errors in parameter passing, though
       these should be easily added in the future when necessary.

FEEDBACK

   Mailing Lists
       User feedback is an integral part of the evolution of this and other Bioperl modules. Send
       your comments and suggestions preferably to one of the Bioperl mailing lists. Your
       participation is much appreciated.

         bioperl-l@lists.open-bio.org               - General discussion
         http://www.bioperl.org/wiki/Mailing_lists  - About the mailing lists

   Support
       Please direct usage questions or support issues to the mailing list:

       bioperl-l@bioperl.org

       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.

   Reporting Bugs
       Report bugs to the Bioperl bug tracking system to help us keep track the bugs and their
       resolution.  Bug reports can be submitted via the web.

         https://redmine.open-bio.org/projects/bioperl/

AUTHOR

       Email cjfields at bioperl dot org

APPENDIX

       The rest of the documentation details each of the object methods. Internal methods are
       usually preceded with a _

Bio::ParameterBaseI implemented methods

   set_parameters
        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 passed but leaves previously set data alone.
                  In addition to regular eutil-specific parameters, you can set the
                  following:

                  -eutil    - the eUtil to be used (default 'efetch')
                  -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)

   reset_parameters
        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 sets any parameter passed, but resets all others (deletes them).
                  In addition to regular eutil-specific parameters, you can set the
                  following:

                  -eutil    - the eUtil to be used (default 'efetch')
                  -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)

   carryover
        Title    : carryover
        Usage    : $obj->carryover(qw(email tool db))
        Function : Carries over the designated parameters when using reset_parameters()
        Returns  : a list of carried-over parameters
        Args     : An array reference of parameters to carry over, followed optionally
                   by the mode ('add' or 'delete', indicating whether to append to or
                   remove the specified values passed in). To clear all values, pass in
                   an empty array reference (the mode in this case doesn't matter).

                   In addition to the normal eUtil-specific parameters, the following
                   additional parameters are allowed:

                   -eutil    - the eUtil to be used (default 'efetch')
                   -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)
        Default  : None (no carried over parameters)
        Status   : NYI (dev in progress, carry on, nothing to see here)

   request_mode
        Title    : request_mode
        Usage    : $obj->request_mode
        Function : get/set the mode for the user agent to use for generating a request
        Returns  : either a preset mode (checked against the eutil) or a best-possible
                   option based upon the currently-set parameters
        Args     :
        Status   :

   parameters_changed
        Title   : parameters_changed
        Usage   : if ($pobj->parameters_changed) {...}
        Function: Returns TRUE if parameters have changed
        Returns : Boolean (0 or 1)
        Args    : [optional] Boolean

   available_parameters
        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 with the eutil name (for returning eutil-specific
                  parameters)

   get_parameters
        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 '-type' parameter. Data
                  originally set as an array ref are returned based on whether the
                  '-join_id' flag is set (default is the same array ref).
        Args    : -type : the eutil name (Default: returns all).  Use of '-list'
                           supercedes this
                  -list : array ref of specific parameters
                  -join_ids : Boolean; join IDs based on correspondence (Default: no join)

Implementation-specific to_* methods

   to_string
        Title   : to_string
        Usage   : $string = $pobj->to_string;
        Function: Returns string (URL only in this case)
        Returns : String (URL only for now)
        Args    : [optional] 'all'; build URI::http using all parameters
                  Default : Builds based on allowed parameters (presence of history data
                  or eutil type in %MODE).
        Note    : Changes state of object.  Absolute string

   to_request
        Title   : to_request
        Usage   : $uri = $pobj->to_request;
        Function: Returns HTTP::Request object
        Returns : HTTP::Request
        Args    : [optional] 'all'; builds request using all parameters
                  Default : Builds based on allowed parameters (presence of history data
                  or eutil type in %MODE).
        Note    : Changes state of object (to boolean FALSE).  Used for CGI-based GET/POST
        TODO    : esearch, esummary, elink now accept POST for batch submission
                  (something NCBI apparently allowed but didn't advertise). Should we
                  switch most of these to utilize POST instead, or make it dep on the
                  number of submitted IDs?

Implementation specific-methods

   eutil
        Title   : eutil
        Usage   : $p->eutil('efetch')
        Function: gets/sets the eutil for this set of parameters
        Returns : string (eutil)
        Args    : [optional] string (eutil)
        Throws  : '$eutil not supported' if eutil not present
        Note    : This does not reset retmode to the default if called directly.

   history
        Title   : history
        Usage   : $p->history($history);
        Function: gets/sets the history object to be used for these parameters
        Returns : Bio::Tools::EUtilities::HistoryI (if set)
        Args    : [optional] Bio::Tools::EUtilities::HistoryI
        Throws  : Passed something other than a Bio::Tools::EUtilities::HistoryI
        Note    : This overrides WebEnv() and query_key() settings when set.  This
                  caches the last history object passed and returns like a Get/Set

   correspondence
        Title   : correspondence
        Usage   : $p->correspondence(1);
        Function: Sets flag for posting IDs for one-to-one correspondence
        Returns : Boolean
        Args    : [optional] boolean value

   id_file
        Title   : id_file
        Usage   : $p->id_file('<foo');
        Function: convenience method; passes in file containing a list of IDs for
                  searches (one per line), sets id() to list
        Returns : none
        Args    : either string indicating file to use, a file handle, or an IO::Handle
                  object
        Note    : use of this overrides concurrent use of the '-id' parameter when both
                  are passed.  The filename is not retained, merely parsed for IDs.

   url_base_address
        Title   : url_base_address
        Usage   : $address = $p->url_base_address();
        Function: Get URL base address
        Returns : String
        Args    : None in this implementation; the URL is fixed

   set_default_retmode
        Title   : set_default_retmode
        Usage   : $p->set_default_retmode();
        Function: sets retmode to default value specified by the eutil() and the value
                  in %NCBI_DATABASE (for efetch only) if called
        Returns : none
        Args    : none

perl v5.14.2                                2011-12-2Bio::Tools::EUtilities::EUtilParameters(3pm)