Bio/ParameterBaseI.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://www.bioperl.org/wiki/Mailing_lists  - 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://redmine.open-bio.org/projects/bioperl/
 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 use strict;
 171 use warnings;
 172
 173 use base qw(Bio::Root::RootI);
 174
 175 =head2 set_parameters
 176
 177  Title   : set_parameters
 178  Usage   : $pobj->set_parameters(%params);
 179  Function: sets the parameters listed in the hash or array
 180  Returns : None
 181  Args    : [optional] hash or array of parameter/values.
 182
 183 =cut
 184
 185 sub set_parameters {
 186     shift->throw_not_implemented;
 187 }
 188
 189 =head2 reset_parameters
 190
 191  Title   : reset_parameters
 192  Usage   : resets values
 193  Function: resets parameters to either undef or value in passed hash
 194  Returns : none
 195  Args    : [optional] hash of parameter-value pairs
 196
 197 =cut
 198
 199 sub reset_parameters {
 200     shift->throw_not_implemented;
 201 }
 202
 203 =head2 parameters_changed
 204
 205  Title   : parameters_changed
 206  Usage   : if ($pobj->parameters_changed) {...}
 207  Function: Returns boolean true (1) if parameters have changed
 208  Returns : Boolean (0 or 1)
 209  Args    : [optional] Boolean
 210
 211 =cut
 212
 213 sub parameters_changed {
 214     shift->throw_not_implemented;
 215 }
 216
 217 =head2 available_parameters
 218
 219  Title   : available_parameters
 220  Usage   : @params = $pobj->available_parameters()
 221  Function: Returns a list of the available parameters
 222  Returns : Array of parameters
 223  Args    : [optional, implementation-dependent] string for returning subset of
 224            parameters
 225
 226 =cut
 227
 228 sub available_parameters {
 229     shift->throw_not_implemented;
 230 }
 231
 232 =head2 get_parameters
 233
 234  Title   : get_parameters
 235  Usage   : %params = $pobj->get_parameters;
 236  Function: Returns list of key-value pairs of parameter => value
 237  Returns : List of key-value pairs
 238  Args    : [optional] A string is allowed if subsets are wanted or (if a
 239            parameter subset is default) 'all' to return all parameters
 240
 241 =cut
 242
 243 sub get_parameters {
 244     shift->throw_not_implemented;
 245 }
 246
 247 =head1 to* methods
 248
 249 All to_* methods are implementation-specific
 250
 251 =cut
 252
 253 1;
 254