lib/Bio/DB/LocationI.pm

   1 #
   2 # BioPerl module for Bio::DB::LocationI
   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::DB::LocationI - A RandomAccessI-like abstract interface for
  17 retrieving location data from a sequence database and returning
  18 Bio::LocationI objects
  19
  20 =head1 SYNOPSIS
  21
  22   #
  23   # get a database object somehow using a concrete class
  24   #
  25
  26   $loc = $db->get_Location_by_id('123456');
  27
  28   #
  29   # $loc is a Bio::LocationI object
  30   #
  31
  32 =head1 DESCRIPTION
  33
  34 This is a pure interface class - in other words, all this does is define
  35 methods which other (concrete) classes will actually implement.
  36
  37 The Bio::DB::LocationI class defines methods used to retrieve location data
  38 from a sequence.  This is returned in the form of Bio::LocationI objects,
  39 which can include:
  40
  41 Bio::Location::Simple
  42 Bio::Location::Fuzzy
  43 Bio::Location::Split
  44
  45 At the moment it is just the ability to make Bio::LocationI objects
  46 from a name or unique id (id), an accession number (acc), and so on.
  47
  48 =head1 CONTACT
  49
  50 Ewan Birney originally wrote Bio::DB::RandomAccessI, from which this class
  51 is based.
  52
  53 =head2 Mailing Lists
  54
  55 User feedback is an integral part of the
  56 evolution of this and other Bioperl modules. Send
  57 your comments and suggestions preferably to one
  58 of the Bioperl mailing lists. Your participation
  59 is much appreciated.
  60
  61   bioperl-l@lists.open-bio.org               - General discussion
  62   http://bioperl.org/Support.html  - About the mailing lists
  63
  64 =head2 Support
  65
  66 Please direct usage questions or support issues to the mailing list:
  67
  68 I<bioperl-l@bioperl.org>
  69
  70 rather than to the module maintainer directly. Many experienced and
  71 reponsive experts will be able look at the problem and quickly
  72 address it. Please include a thorough description of the problem
  73 with code and data examples if at all possible.
  74
  75 =head2 Reporting Bugs
  76
  77 Report bugs to the Bioperl bug tracking system to
  78 help us keep track the bugs and their resolution.
  79 Bug reports can be submitted via the web.
  80
  81   https://github.com/bioperl/bioperl-live/issues
  82
  83 =head1 AUTHOR
  84
  85 Email cjfields at bioperl dot org
  86
  87 =head1 APPENDIX
  88
  89 The rest of the documentation details each of the
  90 object methods. Internal methods are usually
  91 preceded with a _
  92
  93 =cut
  94
  95 # Let the code begin...
  96
  97 package Bio::DB::LocationI;
  98
  99 use strict;
 100
 101 use Bio::Root::RootI;
 102
 103 use base qw(Bio::Root::Root);
 104
 105 =head2 get_Location_by_id
 106
 107  Title   : get_Location_by_id
 108  Usage   : $loc = $db->get_Location_by_id('123456')
 109  Function: Gets a Bio::LocationI-implementing object by its name (id)
 110  Returns : a Bio::LocationI object or undef if not found
 111  Args    : the id (as a string) of a sequence
 112
 113 =cut
 114
 115 sub get_Location_by_id{
 116    my ($self,@args) = @_;
 117    $self->throw_not_implemented();
 118 }
 119
 120 =head2 get_Location_by_acc
 121
 122  Title   : get_Location_by_acc
 123  Usage   : $loc = $db->get_Location_by_acc('X77802');
 124  Function: Gets a Bio::LocationI object by accession number
 125  Returns : A Bio::LocationI object or undef if not found
 126  Args    : accession number (as a string)
 127  Throws  : "more than one sequences correspond to this accession"
 128             if the accession maps to multiple primary ids and
 129             method is called in a scalar context
 130
 131 =cut
 132
 133 sub get_Location_by_acc{
 134    my ($self,@args) = @_;
 135    $self->throw_not_implemented();
 136 }
 137
 138 =head2 get_Location_by_version
 139
 140  Title   : get_Location_by_version
 141  Usage   : $loc = $db->get_Location_by_version('X77802.1');
 142  Function: Gets a Bio::LocationI object by sequence version
 143  Returns : A Bio::LocationI object
 144  Args    : accession.version (as a string)
 145  Throws  : "acc.version does not exist" exception
 146
 147 =cut
 148
 149 sub get_Location_by_version{
 150    my ($self,@args) = @_;
 151    $self->throw_not_implemented();
 152 }
 153
 154 ## End of Package
 155
 156 1;