lib/Bio/Map/PositionHandlerI.pm

   1 #
   2 # BioPerl module for Bio::Map::PositionHandlerI
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Sendu Bala <bix@sendu.me.uk>
   7 #
   8 # Copyright Sendu Bala
   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::Map::PositionHandlerI - A Position Handler Interface
  17
  18 =head1 SYNOPSIS
  19
  20     # do not use this module directly
  21     # See Bio::Map::PositionHandler for an example of
  22     # implementation.
  23
  24 =head1 DESCRIPTION
  25
  26 This interface describes the basic methods required for Position Handlers. A
  27 Position Handler copes with the coordination of different Bio::Map::EntityI
  28 objects, adding and removing them from each other and knowning who belongs to
  29 who. These relationships between objects are based around shared Positions,
  30 hence PositionHandler.
  31
  32 =head1 FEEDBACK
  33
  34 =head2 Mailing Lists
  35
  36 User feedback is an integral part of the evolution of this and other
  37 Bioperl modules. Send your comments and suggestions preferably to
  38 the Bioperl mailing list.  Your participation is much appreciated.
  39
  40   bioperl-l@bioperl.org                  - General discussion
  41   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  42
  43 =head2 Support
  44
  45 Please direct usage questions or support issues to the mailing list:
  46
  47 I<bioperl-l@bioperl.org>
  48
  49 rather than to the module maintainer directly. Many experienced and
  50 reponsive experts will be able look at the problem and quickly
  51 address it. Please include a thorough description of the problem
  52 with code and data examples if at all possible.
  53
  54 =head2 Reporting Bugs
  55
  56 Report bugs to the Bioperl bug tracking system to help us keep track
  57 of the bugs and their resolution. Bug reports can be submitted via the
  58 web:
  59
  60   https://github.com/bioperl/bioperl-live/issues
  61
  62 =head1 AUTHOR - Sendu Bala
  63
  64 Email bix@sendu.me.uk
  65
  66 =head1 APPENDIX
  67
  68 The rest of the documentation details each of the object methods.
  69 Internal methods are usually preceded with a _
  70
  71 =cut
  72
  73 # Let the code begin...
  74
  75 package Bio::Map::PositionHandlerI;
  76 use strict;
  77
  78 use base qw(Bio::Root::RootI);
  79
  80 =head2 General methods
  81
  82 =cut
  83
  84 =head2 register
  85
  86  Title   : register
  87  Usage   : $position_handler->register();
  88  Function: Ask this Position Handler to look after your entity relationships.
  89  Returns : n/a
  90  Args    : none
  91
  92 =cut
  93
  94 sub register {
  95     my $self = shift;
  96     $self->throw_not_implemented();
  97 }
  98
  99 =head2 index
 100
 101  Title   : index
 102  Usage   : my $index = $position_handler->index();
 103  Function: Get the unique registry index for yourself, generated during the
 104            resistration process.
 105  Returns : int
 106  Args    : none
 107
 108 =cut
 109
 110 sub index {
 111     my $self = shift;
 112     $self->throw_not_implemented();
 113 }
 114
 115 =head2 get_entity
 116
 117  Title   : get_entity
 118  Usage   : my $entity = $position_handler->get_entity($index);
 119  Function: Get the entity that corresponds to the supplied registry index.
 120  Returns : Bio::Map::EntityI object
 121  Args    : int
 122
 123 =cut
 124
 125 sub get_entity {
 126         my $self = shift;
 127     $self->throw_not_implemented();
 128 }
 129
 130 =head2 Methods for Bio::Map::PositionI objects
 131
 132 =cut
 133
 134 =head2 map
 135
 136  Title   : map
 137  Usage   : my $map = $position_handler->map();
 138            $position_handler->map($map);
 139  Function: Get/Set the map you are on. You must be a Position.
 140  Returns : L<Bio::Map::MapI>
 141  Args    : none to get, OR
 142            new L<Bio::Map::MapI> to set
 143
 144 =cut
 145
 146 sub map {
 147     my $self = shift;
 148     $self->throw_not_implemented();
 149 }
 150
 151 =head2 element
 152
 153  Title   : element
 154  Usage   : my $element = $position_handler->element();
 155            $position_handler->element($element);
 156  Function: Get/Set the map element you are for. You must be a Position.
 157  Returns : L<Bio::Map::MappableI>
 158  Args    : none to get, OR
 159            new L<Bio::Map::MappableI> to set
 160
 161 =cut
 162
 163 sub element {
 164     my $self = shift;
 165     $self->throw_not_implemented();
 166 }
 167
 168 =head2 Methods for all other Bio::Map::EntityI objects
 169
 170 =cut
 171
 172 =head2 add_positions
 173
 174  Title   : add_positions
 175  Usage   : $position_handler->add_positions($pos1, $pos2, ...);
 176  Function: Add some positions to yourself. You can't be a position.
 177  Returns : n/a
 178  Args    : Array of Bio::Map::PositionI objects
 179
 180 =cut
 181
 182 sub add_positions {
 183     my $self = shift;
 184     $self->throw_not_implemented();
 185 }
 186
 187 =head2 get_positions
 188
 189  Title   : get_positions
 190  Usage   : my @positions = $position_handler->get_positions();
 191  Function: Get all your positions. You can't be a Position.
 192  Returns : Array of Bio::Map::PositionI objects
 193  Args    : none for all, OR
 194            Bio::Map::EntityI object to limit the Positions to those that
 195            are shared by you and this other entity.
 196
 197 =cut
 198
 199 sub get_positions {
 200     my $self = shift;
 201     $self->throw_not_implemented();
 202 }
 203
 204 =head2 purge_positions
 205
 206  Title   : purge_positions
 207  Usage   : $position_handler->purge_positions();
 208  Function: Remove all positions from yourself. You can't be a Position.
 209  Returns : n/a
 210  Args    : none to remove all, OR
 211            Bio::Map::PositionI object to remove only that entity, OR
 212            Bio::Map::EntityI object to limit the removal to those Positions that
 213            are shared by you and this other entity.
 214
 215 =cut
 216
 217 sub purge_positions {
 218     my $self = shift;
 219     $self->throw_not_implemented();
 220 }
 221
 222 =head2 get_other_entities
 223
 224  Title   : get_other_entities
 225  Usage   : my @entities = $position_handler->get_other_entities();
 226  Function: Get all the entities that share your Positions. You can't be a
 227            Position.
 228  Returns : Array of Bio::Map::EntityI objects
 229  Args    : none
 230
 231 =cut
 232
 233 sub get_other_entities {
 234     my $self = shift;
 235     $self->throw_not_implemented();
 236 }
 237
 238 1;