1Bio::ParameterBaseI(3)User Contributed Perl DocumentationBio::ParameterBaseI(3)
2
6 Bio::ParameterBaseI - Simple interface class for any parameter-related
7 data such as IDs, database name, program arguments, and other odds and
8 ends.
9
11 # Bio::DB::MyParams implements Bio::ParameterBaseI
12 @params = (-db => 'protein',
14 -id => \@ids,
15 -retmax => 10);
16 $pobj->Bio::DB::MyDBParams->new();
18 # sets only parameters passed; results in a state change if any parameter
20 # passed is new or differs from previously set value
21 $pobj->set_params(@params);
23 # reset all parameters (sets to undef); results in a state change
25 $pobj->reset_params();
27 # resets parameters to those in %param (sets all others to undef); resets the
29 # object state to indicate change.
30 $pobj->reset_params(@params);
32 # direct get/set; results in a state change if any parameter passed is new or
34 # differs from previously set value
35 $pobj->db('nucleotide');
37 @ids = $pobj->id();
38 # retrieve list containing set defined parameters
40 %myparams = $pobj->get_parameters();
42 # checks whether the state of the object has changed (i.e. parameter has
44 # changed, so on)
45 if ($pobj->parameters_changed) {
47 # run new search
48 } else {
49 # return cached search
50 }
51 # available parameters
53 @params = $pobj->available_parameters();
55 # retrieve string (URI, query, etc); calling to* methods changes object state
57 # to indicate data hasn't changed (so future calls to parameters_changed()
58 # will return FALSE)
59 $query = $pobj->to_string(); # returns raw string
61 $uri = $pobj->to_uri(); # returns URI-based object
62 $uri = $pobj->to_my_data_struct(); # returns implemenation-specific data structure
63 ...
64
66 This is a class interface which focuses on common parameter-related
67 tasks such as building simple database queries, URI-related requests,
68 program arguments, etc.
69 Implementing classes use the following ways to set parameters:
71 1) Create a new instance of a ParameterBaseI-implementing object.
73 $pobj->Bio::DB::MyParamClass->new(-db => 'local', -id => \@ids);
75 2) Pass the parameters as a hash or array to set_parameters(), which
77 sets the parameters listed in the hash but leaves all others as is.
78 $pobj->set_parameters(-retmax => 100, -retstart => 20);
80 3) Pass the parameters as a hash or array to reset_parameters(), which
82 sets the parameters listed in the hash and resets everything else.
83 $pobj->reset_parameters(-term => 'pyrimidine'); # sets db and id to undef
85 4) Pass values using specific getter/setters.
87 $pobj->id(\@ids); # sets IDs
89 There is no restriction on what one uses to set up individual parameter
91 getter/setters, though there are some other options implemented in
92 BioPerl (for instance, Bio::Root::RootI::_set_from_args()).
93 A key requirement is there be a way to detect changes in the state of
95 the ParameterBaseI object so that any object with a Bio::ParameterBaseI
96 can decide whether to submit a new request or return cached data. State
97 changes are revealed by the returned values of the parameters_changed()
98 method, which is a simple boolean set to TRUE when the object is first
99 instantiated or parameters have changed.
100 When retrieving anything using the implementation-specific to_* methods
102 (such as to_query, to_string, to_uri, to_request, etc), the
103 ParameterBaseI object state is set to FALSE to indicate the data has
104 been accessed and indicate reaccessing will retrieve the same value.
105 The observing object can then independently decide whether to rerun the
106 cached query or return a previously cached result.
107 One can also use indiviual getter/setters to retrieve single parameter
109 values as well as use parameter_hash() to retrieve all of the
110 parameters in one go as a hash. To check which parameters are available
111 use available_parameters(). Args passed to
112
114 Mailing Lists
115 User feedback is an integral part of the evolution of this and other
116 Bioperl modules. Send your comments and suggestions preferably to one
117 of the Bioperl mailing lists. Your participation is much appreciated.
118 bioperl-l@lists.open-bio.org - General discussion
120 http://www.bioperl.org/wiki/Mailing_lists - About the mailing lists
121 Support
123 Please direct usage questions or support issues to the mailing list:
124 bioperl-l@bioperl.org
126 rather than to the module maintainer directly. Many experienced and
128 reponsive experts will be able look at the problem and quickly address
129 it. Please include a thorough description of the problem with code and
130 data examples if at all possible.
131 Reporting Bugs
133 Report bugs to the Bioperl bug tracking system to help us keep track
134 the bugs and their resolution. Bug reports can be submitted via the
135 web.
136 http://bugzilla.open-bio.org/
138
140 Email cjfields at bioperl dot org
141
143 The rest of the documentation details each of the object methods.
144 Internal methods are usually preceded with a _
145 set_parameters
147 Title : set_parameters
148 Usage : $pobj->set_parameters(%params);
149 Function: sets the parameters listed in the hash or array
150 Returns : None
151 Args : [optional] hash or array of parameter/values.
152 reset_parameters
154 Title : reset_parameters
155 Usage : resets values
156 Function: resets parameters to either undef or value in passed hash
157 Returns : none
158 Args : [optional] hash of parameter-value pairs
159 parameters_changed
161 Title : parameters_changed
162 Usage : if ($pobj->parameters_changed) {...}
163 Function: Returns boolean true (1) if parameters have changed
164 Returns : Boolean (0 or 1)
165 Args : [optional] Boolean
166 available_parameters
168 Title : available_parameters
169 Usage : @params = $pobj->available_parameters()
170 Function: Returns a list of the available parameters
171 Returns : Array of parameters
172 Args : [optional, implementation-dependent] string for returning subset of
173 parameters
174 get_parameters
176 Title : get_parameters
177 Usage : %params = $pobj->get_parameters;
178 Function: Returns list of key-value pairs of parameter => value
179 Returns : List of key-value pairs
180 Args : [optional] A string is allowed if subsets are wanted or (if a
181 parameter subset is default) 'all' to return all parameters
182
184 All to_* methods are implementation-specific
185perl v5.12.0 2010-04-29 Bio::ParameterBaseI(3)