Bio/ParameterBaseI.pm

filter: Statementstmt 68.7% 11 / 16 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 37.5% 3 / 8 Podpod 100% 5 / 5 totaltotal 65.5% 19 / 29 CC 1 SCAR 4.9
CC
1
Cov
69%
set_parameters
2.0
reset_parameters
2.0
parameters_changed
2.0
CRAP 1.6
« Bio/Matrix/PSM/PsmHeaderI.pm ↑ Summary Bio/DB/QueryI.pm »
1 #
2 # BioPerl module for Bio::ParameterBaseI
3 #
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
5 #
6 # Cared for by Chris Fields <cjfields at bioperl dot org>
7 #
8 # Copyright Chris Fields
9 #
10 # You may distribute this module under the same terms as perl itself
11 #
12 # POD documentation - main docs before the code
13  
14 =head1 NAME
15  
16 Bio::ParameterBaseI - Simple interface class for any parameter-related data such
17 as IDs, database name, program arguments, and other odds and ends.
18  
19 =head1 SYNOPSIS
20  
21 # Bio::DB::MyParams implements Bio::ParameterBaseI
22  
23 @params = (-db => 'protein',
24 -id => \@ids,
25 -retmax => 10);
26  
27 $pobj->Bio::DB::MyDBParams->new();
28  
29 # sets only parameters passed; results in a state change if any parameter
30 # passed is new or differs from previously set value
31  
32 $pobj->set_params(@params);
33  
34 # reset all parameters (sets to undef); results in a state change
35  
36 $pobj->reset_params();
37  
38 # resets parameters to those in %param (sets all others to undef); resets the
39 # object state to indicate change.
40  
41 $pobj->reset_params(@params);
42  
43 # direct get/set; results in a state change if any parameter passed is new or
44 # differs from previously set value
45  
46 $pobj->db('nucleotide');
47 @ids = $pobj->id();
48  
49 # retrieve list containing set defined parameters
50  
51 %myparams = $pobj->get_parameters();
52  
53 # checks whether the state of the object has changed (i.e. parameter has
54 # changed, so on)
55  
56 if ($pobj->parameters_changed) {
57 # run new search
58 } else {
59 # return cached search
60 }
61  
62 # available parameters
63  
64 @params = $pobj->available_parameters();
65  
66 # retrieve string (URI, query, etc); calling to* methods changes object state
67 # to indicate data hasn't changed (so future calls to parameters_changed()
68 # will return FALSE)
69  
70 $query = $pobj->to_string(); # returns raw string
71 $uri = $pobj->to_uri(); # returns URI-based object
72 $uri = $pobj->to_my_data_struct(); # returns implemenation-specific data structure
73 ...
74  
75 =head1 DESCRIPTION
76  
77 This is a class interface which focuses on common parameter-related tasks such
78 as building simple database queries, URI-related requests, program arguments,
79 etc.
80  
81 Implementing classes use the following ways to set parameters:
82  
83 1) Create a new instance of a ParameterBaseI-implementing object.
84  
85 $pobj->Bio::DB::MyParamClass->new(-db => 'local', -id => \@ids);
86  
87 2) Pass the parameters as a hash or array to set_parameters(), which sets the
88 parameters listed in the hash but leaves all others as is.
89  
90 $pobj->set_parameters(-retmax => 100, -retstart => 20);
91  
92 3) Pass the parameters as a hash or array to reset_parameters(), which sets the
93 parameters listed in the hash and resets everything else.
94  
95 $pobj->reset_parameters(-term => 'pyrimidine'); # sets db and id to undef
96  
97 4) Pass values using specific getter/setters.
98  
99 $pobj->id(\@ids); # sets IDs
100  
101 There is no restriction on what one uses to set up individual parameter
102 getter/setters, though there are some other options implemented in BioPerl (for
103 instance, Bio::Root::RootI::_set_from_args()).
104  
105 A key requirement is there be a way to detect changes in the state of the
106 ParameterBaseI object so that any object with a Bio::ParameterBaseI can decide
107 whether to submit a new request or return cached data. State changes are
108 revealed by the returned values of the parameters_changed() method, which is a
109 simple boolean set to TRUE when the object is first instantiated or parameters
110 have changed.
111  
112 When retrieving anything using the implementation-specific to_* methods (such as
113 to_query, to_string, to_uri, to_request, etc), the ParameterBaseI object state
114 is set to FALSE to indicate the data has been accessed and indicate reaccessing
115 will retrieve the same value. The observing object can then independently decide
116 whether to rerun the cached query or return a previously cached result.
117  
118 One can also use indiviual getter/setters to retrieve single parameter values as
119 well as use parameter_hash() to retrieve all of the parameters in one go as a
120 hash. To check which parameters are available use available_parameters(). Args
121 passed to
122  
123 =head1 FEEDBACK
124  
125 =head2 Mailing Lists
126  
127 User feedback is an integral part of the
128 evolution of this and other Bioperl modules. Send
129 your comments and suggestions preferably to one
130 of the Bioperl mailing lists. Your participation
131 is much appreciated.
132  
133 bioperl-l@lists.open-bio.org - General discussion
134 http://bioperl.org/Support.html - About the mailing lists
135  
136 =head2 Support
137  
138 Please direct usage questions or support issues to the mailing list:
139  
140 I<bioperl-l@bioperl.org>
141  
142 rather than to the module maintainer directly. Many experienced and
143 reponsive experts will be able look at the problem and quickly
144 address it. Please include a thorough description of the problem
145 with code and data examples if at all possible.
146  
147 =head2 Reporting Bugs
148  
149 Report bugs to the Bioperl bug tracking system to
150 help us keep track the bugs and their resolution.
151 Bug reports can be submitted via the web.
152  
153 https://github.com/bioperl/bioperl-live/issues
154  
155 =head1 AUTHOR
156  
157 Email cjfields at bioperl dot org
158  
159 =head1 APPENDIX
160  
161 The rest of the documentation details each of the
162 object methods. Internal methods are usually
163 preceded with a _
164  
165 =cut
166  
167 # Let the code begin...
168  
169 package Bio::ParameterBaseI;
170 2 $Bio::ParameterBaseI::VERSION = '1.7.8';
171 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
172 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
173  
174 2 ▶use base qw(Bio::Root::RootI);
Subroutine BEGIN: called CC=1 SCAR=0.0
175  
176 =head2 set_parameters
177  
178 Title : set_parameters
179 Usage : $pobj->set_parameters(%params);
180 Function: sets the parameters listed in the hash or array
181 Returns : None
182 Args : [optional] hash or array of parameter/values.
183  
184 =cut
185  
186 0 ▶sub set_parameters {
Subroutine set_parameters: not called CC=1 SCAR=6.9
Pod documented
187 0 shift->throw_not_implemented;
188 }
189  
190 =head2 reset_parameters
191  
192 Title : reset_parameters
193 Usage : resets values
194 Function: resets parameters to either undef or value in passed hash
195 Returns : none
196 Args : [optional] hash of parameter-value pairs
197  
198 =cut
199  
200 0 ▶sub reset_parameters {
Subroutine reset_parameters: not called CC=1 SCAR=6.9
Pod documented
201 0 shift->throw_not_implemented;
202 }
203  
204 =head2 parameters_changed
205  
206 Title : parameters_changed
207 Usage : if ($pobj->parameters_changed) {...}
208 Function: Returns boolean true (1) if parameters have changed
209 Returns : Boolean (0 or 1)
210 Args : [optional] Boolean
211  
212 =cut
213  
214 0 ▶sub parameters_changed {
Subroutine parameters_changed: not called CC=1 SCAR=6.9
Pod documented
215 0 shift->throw_not_implemented;
216 }
217  
218 =head2 available_parameters
219  
220 Title : available_parameters
221 Usage : @params = $pobj->available_parameters()
222 Function: Returns a list of the available parameters
223 Returns : Array of parameters
224 Args : [optional, implementation-dependent] string for returning subset of
225 parameters
226  
227 =cut
228  
229 0 ▶sub available_parameters {
Subroutine available_parameters: not called CC=1 SCAR=6.9
Pod documented
230 0 shift->throw_not_implemented;
231 }
232  
233 =head2 get_parameters
234  
235 Title : get_parameters
236 Usage : %params = $pobj->get_parameters;
237 Function: Returns list of key-value pairs of parameter => value
238 Returns : List of key-value pairs
239 Args : [optional] A string is allowed if subsets are wanted or (if a
240 parameter subset is default) 'all' to return all parameters
241  
242 =cut
243  
244 0 ▶sub get_parameters {
Subroutine get_parameters: not called CC=1 SCAR=6.9
Pod documented
245 0 shift->throw_not_implemented;
246 }
247  
248 =head1 to* methods
249  
250 All to_* methods are implementation-specific
251  
252 =cut
253  
254 2 1;
255  
« Bio/Matrix/PSM/PsmHeaderI.pm ↑ Summary Bio/DB/QueryI.pm »