.\" Automatically generated by Pod::Man 4.11 (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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bio::ParameterBaseI 3pm"
.TH Bio::ParameterBaseI 3pm "2020-10-28" "perl v5.30.3" "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::ParameterBaseI \- Simple interface class for any parameter\-related data such
as IDs, database name, program arguments, and other odds and ends.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  # Bio::DB::MyParams implements Bio::ParameterBaseI
\&
\&  @params = (\-db   => \*(Aqprotein\*(Aq,
\&             \-id   => \e@ids,
\&             \-retmax => 10);
\&
\&  $pobj\->Bio::DB::MyDBParams\->new();
\&
\&  # sets only parameters passed; results in a state change if any parameter
\&  # passed is new or differs from previously set value
\&
\&  $pobj\->set_params(@params);
\&
\&  # reset all parameters (sets to undef); results in a state change
\&
\&  $pobj\->reset_params();
\&
\&  # resets parameters to those in %param (sets all others to undef); resets the
\&  # object state to indicate change.
\&
\&  $pobj\->reset_params(@params);
\&
\&  # direct get/set; results in a state change if any parameter passed is new or
\&  # differs from previously set value
\&
\&  $pobj\->db(\*(Aqnucleotide\*(Aq);
\&  @ids = $pobj\->id();
\&
\&  # retrieve list containing set defined parameters
\&
\&  %myparams = $pobj\->get_parameters();
\&
\&  # checks whether the state of the object has changed (i.e. parameter has
\&  # changed, so on)
\&
\&  if ($pobj\->parameters_changed) {
\&     # run new search
\&  } else {
\&     # return cached search
\&  }
\&
\&  # available parameters
\&
\&  @params = $pobj\->available_parameters();
\&
\&  # retrieve string (URI, query, etc); calling to* methods changes object state
\&  # to indicate data hasn\*(Aqt changed (so future calls to parameters_changed()
\&  # will return FALSE)
\&
\&  $query = $pobj\->to_string(); # returns raw string
\&  $uri = $pobj\->to_uri(); #  returns URI\-based object
\&  $uri = $pobj\->to_my_data_struct(); #  returns implemenation\-specific data structure
\&  ...
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a class interface which focuses on common parameter-related tasks such
as building simple database queries, URI-related requests, program arguments,
etc.
.PP
Implementing classes use the following ways to set parameters:
.PP
1) Create a new instance of a ParameterBaseI-implementing object.
.PP
.Vb 1
\&  $pobj\->Bio::DB::MyParamClass\->new(\-db => \*(Aqlocal\*(Aq, \-id => \e@ids);
.Ve
.PP
2) Pass the parameters as a hash or array to \fBset_parameters()\fR, which sets the
parameters listed in the hash but leaves all others as is.
.PP
.Vb 1
\&  $pobj\->set_parameters(\-retmax => 100, \-retstart => 20);
.Ve
.PP
3) Pass the parameters as a hash or array to \fBreset_parameters()\fR, which sets the
parameters listed in the hash and resets everything else.
.PP
.Vb 1
\&  $pobj\->reset_parameters(\-term => \*(Aqpyrimidine\*(Aq); # sets db and id to undef
.Ve
.PP
4) Pass values using specific getter/setters.
.PP
.Vb 1
\&  $pobj\->id(\e@ids); # sets IDs
.Ve
.PP
There is no restriction on what one uses to set up individual parameter
getter/setters, though there are some other options implemented in BioPerl (for
instance, \fBBio::Root::RootI::_set_from_args()\fR).
.PP
A key requirement is there be a way to detect changes in the state of the
ParameterBaseI object so that any object with a Bio::ParameterBaseI can decide
whether to submit a new request or return cached data. State changes are
revealed by the returned values of the \fBparameters_changed()\fR method, which is a
simple boolean set to \s-1TRUE\s0 when the object is first instantiated or parameters
have changed.
.PP
When retrieving anything using the implementation-specific to_* methods (such as
to_query, to_string, to_uri, to_request, etc), the ParameterBaseI object state
is set to \s-1FALSE\s0 to indicate the data has been accessed and indicate reaccessing
will retrieve the same value. The observing object can then independently decide
whether to rerun the cached query or return a previously cached result.
.PP
One can also use indiviual getter/setters to retrieve single parameter values as
well as use \fBparameter_hash()\fR to retrieve all of the parameters in one go as a
hash. To check which parameters are available use \fBavailable_parameters()\fR.  Args
passed to
.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 one
of the Bioperl mailing lists. Your participation
is much appreciated.
.PP
.Vb 2
\&  bioperl\-l@lists.open\-bio.org               \- General discussion
\&  http://bioperl.org/Support.html  \- About the mailing lists
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\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 the bugs and their resolution.
Bug reports can be submitted via the web.
.PP
.Vb 1
\&  https://github.com/bioperl/bioperl\-live/issues
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Email cjfields at bioperl dot org
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the
object methods. Internal methods are usually
preceded with a _
.SS "set_parameters"
.IX Subsection "set_parameters"
.Vb 5
\& Title   : set_parameters
\& Usage   : $pobj\->set_parameters(%params);
\& Function: sets the parameters listed in the hash or array
\& Returns : None
\& Args    : [optional] hash or array of parameter/values.
.Ve
.SS "reset_parameters"
.IX Subsection "reset_parameters"
.Vb 5
\& 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
.Ve
.SS "parameters_changed"
.IX Subsection "parameters_changed"
.Vb 5
\& Title   : parameters_changed
\& Usage   : if ($pobj\->parameters_changed) {...}
\& Function: Returns boolean true (1) if parameters have changed
\& Returns : Boolean (0 or 1)
\& Args    : [optional] Boolean
.Ve
.SS "available_parameters"
.IX Subsection "available_parameters"
.Vb 6
\& Title   : available_parameters
\& Usage   : @params = $pobj\->available_parameters()
\& Function: Returns a list of the available parameters
\& Returns : Array of parameters
\& Args    : [optional, implementation\-dependent] string for returning subset of
\&           parameters
.Ve
.SS "get_parameters"
.IX Subsection "get_parameters"
.Vb 6
\& Title   : get_parameters
\& Usage   : %params = $pobj\->get_parameters;
\& Function: Returns list of key\-value pairs of parameter => value
\& Returns : List of key\-value pairs
\& Args    : [optional] A string is allowed if subsets are wanted or (if a
\&           parameter subset is default) \*(Aqall\*(Aq to return all parameters
.Ve
.SH "to* methods"
.IX Header "to* methods"
All to_* methods are implementation-specific