NAME

       Bio::Map::PositionHandler - A Position Handler Implementation

SYNOPSIS

           # This is used by modules when they want to implement being a
           # Position or being something that has Positions (when they are
           # a L<Bio::Map::EntityI>)

           # Make a PositionHandler that knows about you
           my $ph = Bio::Map::PositionHandler->new($self);

           # Register with it so that it handles your Position-related needs
           $ph->register;

           # If you are a position, get/set the map you are on and the marker you are
           # for
           $ph->map($map);
           $ph->element($marker);
           my $map = $ph->map;
           my $marker = $ph->element;

           # If you are a marker, add a new position to yourself
           $ph->add_positions($pos);

           # And then get all your positions on a particular map
           foreach my $pos ($ph->get_positions($map)) {
               # do something with this Bio::Map::PositionI
           }

           # Or find out what maps you exist on
           my @maps = $ph->get_other_entities;

           # The same applies if you were a map

DESCRIPTION

       A Position Handler copes with the coordination of different Bio::Map::EntityI objects,
       adding and removing them from each other and knowning who belongs to who. These
       relationships between objects are based around shared Positions, hence PositionHandler.

       This PositionHandler is able to cope with Bio::Map::PositionI objects, Bio::Map::MappableI
       objects and Bio::Map::MapI objects.

FEEDBACK

   Mailing Lists
       User feedback is an integral part of the evolution of this and other Bioperl modules. Send
       your comments and suggestions preferably to the Bioperl mailing list.  Your participation
       is much appreciated.

         bioperl-l@bioperl.org                  - General discussion
         http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

   Support
       Please direct usage questions or support issues to the mailing list:

       bioperl-l@bioperl.org

       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.

   Reporting Bugs
       Report bugs to the Bioperl bug tracking system to help us keep track of the bugs and their
       resolution. Bug reports can be submitted via the web:

         https://redmine.open-bio.org/projects/bioperl/

AUTHOR - Sendu Bala

       Email bix@sendu.me.uk

APPENDIX

       The rest of the documentation details each of the object methods.  Internal methods are
       usually preceded with a _

   General methods
   new
        Title   : new
        Usage   : my $position_handler = Bio::Map::PositionHandler->new(-self => $self);
        Function: Get a Bio::Map::PositionHandler that knows who you are.
        Returns : Bio::Map::PositionHandler object
        Args    : -self => Bio::Map::EntityI that is you

   register
        Title   : register
        Usage   : $position_handler->register();
        Function: Ask this Position Handler to look after your entity relationships.
        Returns : n/a
        Args    : none

   index
        Title   : index
        Usage   : my $index = $position_handler->index();
        Function: Get the unique registry index for yourself, generated during the
                  resistration process.
        Returns : int
        Args    : none

   get_entity
        Title   : get_entity
        Usage   : my $entity = $position_handler->get_entity($index);
        Function: Get the entity that corresponds to the supplied registry index.
        Returns : Bio::Map::EntityI object
        Args    : int

   Methods for Bio::Map::PositionI objects
   map
        Title   : map
        Usage   : my $map = $position_handler->map();
                  $position_handler->map($map);
        Function: Get/Set the map you are on. You must be a Position.
        Returns : L<Bio::Map::MapI>
        Args    : none to get, OR
                  new L<Bio::Map::MapI> to set

   element
        Title   : element
        Usage   : my $element = $position_handler->element();
                  $position_handler->element($element);
        Function: Get/Set the map element you are for. You must be a Position.
        Returns : L<Bio::Map::MappableI>
        Args    : none to get, OR
                  new L<Bio::Map::MappableI> to set

   Methods for all other Bio::Map::EntityI objects
   add_positions
        Title   : add_positions
        Usage   : $position_handler->add_positions($pos1, $pos2, ...);
        Function: Add some positions to yourself. You can't be a position.
        Returns : n/a
        Args    : Array of Bio::Map::PositionI objects

   get_positions
        Title   : get_positions
        Usage   : my @positions = $position_handler->get_positions();
        Function: Get all your positions. You can't be a Position.
        Returns : Array of Bio::Map::PositionI objects
        Args    : none for all, OR
                  Bio::Map::EntityI object to limit the Positions to those that
                  are shared by you and this other entity.

   purge_positions
        Title   : purge_positions
        Usage   : $position_handler->purge_positions();
        Function: Remove all positions from yourself. You can't be a Position.
        Returns : n/a
        Args    : none to remove all, OR
                  Bio::Map::PositionI object to remove only that entity, OR
                  Bio::Map::EntityI object to limit the removal to those Positions that
                  are shared by you and this other entity.

   get_other_entities
        Title   : get_other_entities
        Usage   : my @entities = $position_handler->get_other_entities();
        Function: Get all the entities that share your Positions. You can't be a
                  Position.
        Returns : Array of Bio::Map::EntityI objects
        Args    : none