Bio::ParameterBaseI - Simple interface class for any parameter-related data such
as IDs, database name, program arguments, and other odds and ends.
# Bio::DB::MyParams implements Bio::ParameterBaseI
@params = (-db => 'protein',
-id => \@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('nucleotide');
@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't 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
...
This is a class interface which focuses on common parameter-related tasks such
as building simple database queries, URI-related requests, program arguments,
etc.
Implementing classes use the following ways to set parameters:
1) Create a new instance of a ParameterBaseI-implementing object.
$pobj->Bio::DB::MyParamClass->new(-db => 'local', -id => \@ids);
2) Pass the parameters as a hash or array to
set_parameters(), which sets
the parameters listed in the hash but leaves all others as is.
$pobj->set_parameters(-retmax => 100, -retstart => 20);
3) Pass the parameters as a hash or array to
reset_parameters(), which
sets the parameters listed in the hash and resets everything else.
$pobj->reset_parameters(-term => 'pyrimidine'); # sets db and id to undef
4) Pass values using specific getter/setters.
$pobj->id(\@ids); # sets IDs
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,
Bio::Root::RootI::_set_from_args()).
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
parameters_changed() method,
which is a simple boolean set to TRUE when the object is first instantiated or
parameters have changed.
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 FALSE 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.
One can also use indiviual getter/setters to retrieve single parameter values as
well as use
parameter_hash() to retrieve all of the parameters in one
go as a hash. To check which parameters are available use
available_parameters(). Args passed to
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.
[email protected] - General discussion
http://bioperl.org/Support.html - About the mailing lists
Please direct usage questions or support issues to the mailing list:
[email protected]
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.
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://github.com/bioperl/bioperl-live/issues
Email cjfields at bioperl dot org
The rest of the documentation details each of the object methods. Internal
methods are usually preceded with a _
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.
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
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
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
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) 'all' to return all parameters
All to_* methods are implementation-specific