Bio/IdentifiableI.pm

   1 #
   2 # This module is licensed under the same terms as Perl itself. You use,
   3 # modify, and redistribute it under the terms of the Perl Artistic License.
   4 #
   5
   6 =head1 NAME
   7
   8 Bio::IdentifiableI - interface for objects with identifiers
   9
  10 =head1 SYNOPSIS
  11
  12     # to test this is an identifiable object
  13
  14     $obj->isa("Bio::IdentifiableI") ||
  15       $obj->throw("$obj does not implement the Bio::IdentifiableI interface");
  16
  17     # Accessors
  18
  19     $object_id = $obj->object_id();
  20     $namespace = $obj->namespace();
  21     $authority = $obj->authority();
  22     $version   = $obj->version();
  23     # Gets authority:namespace:object_id
  24     $lsid = $obj->lsid_string();
  25     # Gets namespace:object_id.version
  26     $ns_string = $obj->namespace_string();
  27
  28 =head1 DESCRIPTION
  29
  30 This interface describes methods expected on identifiable objects, i.e.
  31 ones which have identifiers expected to make sense across a number of
  32 instances and/or domains. This interface is modeled after pretty much
  33 ubiquitous ideas for names in bioinformatics being
  34
  35  databasename:object_id.version
  36
  37 Example:
  38
  39  swissprot:P012334.2
  40
  41 or:
  42
  43  GO:0007048
  44
  45 The object will also work with LSID proposals which adds the concept of an
  46 authority, being the DNS name of the organisation assigning the namespace.
  47 See L<http://lsid.sourceforge.net/>.
  48
  49 Helper functions are provided to make useful strings:
  50
  51   lsid_string - string complying to the LSID standard
  52
  53   namespace_string - string complying to the usual convention of
  54                      namespace:object_id.version
  55
  56 =head1 FEEDBACK
  57
  58 =head2 Mailing Lists
  59
  60 User feedback is an integral part of the evolution of this and other
  61 Bioperl modules. Send your comments and suggestions preferably to one
  62 of the Bioperl mailing lists.  Your participation is much appreciated.
  63
  64   bioperl-l@bioperl.org                  - General discussion
  65   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  66
  67 =head2 Support
  68
  69 Please direct usage questions or support issues to the mailing list:
  70
  71 I<bioperl-l@bioperl.org>
  72
  73 rather than to the module maintainer directly. Many experienced and
  74 reponsive experts will be able look at the problem and quickly
  75 address it. Please include a thorough description of the problem
  76 with code and data examples if at all possible.
  77
  78 =head2 Reporting Bugs
  79
  80 Report bugs to the Bioperl bug tracking system to help us keep track
  81 the bugs and their resolution.  Bug reports can be submitted via the
  82 web:
  83
  84   https://redmine.open-bio.org/projects/bioperl/
  85
  86 =head1 AUTHOR - Ewan Birney
  87
  88 Email birney@ebi.ac.uk
  89
  90 =cut
  91
  92 package Bio::IdentifiableI;
  93 use strict;
  94
  95
  96 use base qw(Bio::Root::RootI);
  97
  98 =head1 Implementation Specific Functions
  99
 100 These functions are the ones that a specific implementation must
 101 define.
 102
 103 =head2 object_id
 104
 105  Title   : object_id
 106  Usage   : $string    = $obj->object_id()
 107  Function: a string which represents the stable primary identifier
 108            in this namespace of this object. For DNA sequences this
 109            is its accession_number, similarly for protein sequences
 110  Returns : A scalar
 111  Status  : Virtual
 112
 113 =cut
 114
 115 sub object_id {
 116    my ($self) = @_;
 117    $self->throw_not_implemented();
 118 }
 119
 120 =head2 version
 121
 122  Title   : version
 123  Usage   : $version    = $obj->version()
 124  Function: a number which differentiates between versions of
 125            the same object. Higher numbers are considered to be
 126            later and more relevant, but a single object described
 127            the same identifier should represent the same concept
 128  Returns : A number
 129  Status  : Virtual
 130
 131 =cut
 132
 133 sub version {
 134    my ($self) = @_;
 135    $self->throw_not_implemented();
 136 }
 137
 138
 139 =head2 authority
 140
 141  Title   : authority
 142  Usage   : $authority    = $obj->authority()
 143  Function: a string which represents the organisation which
 144            granted the namespace, written as the DNS name for
 145            organisation (eg, wormbase.org)
 146  Returns : A scalar
 147  Status  : Virtual
 148
 149 =cut
 150
 151 sub authority {
 152    my ($self) = @_;
 153    $self->throw_not_implemented();
 154 }
 155
 156
 157 =head2 namespace
 158
 159  Title   : namespace
 160  Usage   : $string    = $obj->namespace()
 161  Function: A string representing the name space this identifier
 162            is valid in, often the database name or the name
 163            describing the collection
 164  Returns : A scalar
 165  Status  : Virtual
 166
 167 =cut
 168
 169 sub namespace {
 170    my ($self) = @_;
 171    $self->throw_not_implemented();
 172 }
 173
 174
 175 =head1 Implementation optional functions
 176
 177 These functions are helper functions that are provided by
 178 the interface but can be overridden if so wished
 179
 180 =head2 lsid_string
 181
 182  Title   : lsid_string
 183  Usage   : $string   = $obj->lsid_string()
 184  Function: a string which gives the LSID standard
 185            notation for the identifier of interest
 186
 187
 188  Returns : A scalar
 189
 190 =cut
 191
 192 sub lsid_string {
 193   my ($self) = @_;
 194
 195   return $self->authority.":".$self->namespace.":".$self->object_id;
 196 }
 197
 198
 199
 200 =head2 namespace_string
 201
 202  Title   : namespace_string
 203  Usage   : $string   = $obj->namespace_string()
 204  Function: a string which gives the common notation of
 205            namespace:object_id.version
 206  Returns : A scalar
 207
 208 =cut
 209
 210 sub namespace_string {
 211   my ($self) = @_;
 212
 213   return $self->namespace.":".$self->object_id .
 214       (defined($self->version()) ? ".".$self->version : '');
 215 }
 216
 217 1;