lib/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://github.com/bioperl/bioperl-live/issues
  85
  86 =head1 AUTHOR - Ewan Birney
  87
  88 Email birney@ebi.ac.uk
  89
  90 =cut
  91
  92 package Bio::IdentifiableI;
  93
  94 use strict;
  95
  96
  97 use base qw(Bio::Root::RootI);
  98
  99 =head1 Implementation Specific Functions
 100
 101 These functions are the ones that a specific implementation must
 102 define.
 103
 104 =head2 object_id
 105
 106  Title   : object_id
 107  Usage   : $string    = $obj->object_id()
 108  Function: a string which represents the stable primary identifier
 109            in this namespace of this object. For DNA sequences this
 110            is its accession_number, similarly for protein sequences
 111  Returns : A scalar
 112  Status  : Virtual
 113
 114 =cut
 115
 116 sub object_id {
 117    my ($self) = @_;
 118    $self->throw_not_implemented();
 119 }
 120
 121 =head2 version
 122
 123  Title   : version
 124  Usage   : $version    = $obj->version()
 125  Function: a number which differentiates between versions of
 126            the same object. Higher numbers are considered to be
 127            later and more relevant, but a single object described
 128            the same identifier should represent the same concept
 129  Returns : A number
 130  Status  : Virtual
 131
 132 =cut
 133
 134 sub version {
 135    my ($self) = @_;
 136    $self->throw_not_implemented();
 137 }
 138
 139
 140 =head2 authority
 141
 142  Title   : authority
 143  Usage   : $authority    = $obj->authority()
 144  Function: a string which represents the organisation which
 145            granted the namespace, written as the DNS name for
 146            organisation (eg, wormbase.org)
 147  Returns : A scalar
 148  Status  : Virtual
 149
 150 =cut
 151
 152 sub authority {
 153    my ($self) = @_;
 154    $self->throw_not_implemented();
 155 }
 156
 157
 158 =head2 namespace
 159
 160  Title   : namespace
 161  Usage   : $string    = $obj->namespace()
 162  Function: A string representing the name space this identifier
 163            is valid in, often the database name or the name
 164            describing the collection
 165  Returns : A scalar
 166  Status  : Virtual
 167
 168 =cut
 169
 170 sub namespace {
 171    my ($self) = @_;
 172    $self->throw_not_implemented();
 173 }
 174
 175
 176 =head1 Implementation optional functions
 177
 178 These functions are helper functions that are provided by
 179 the interface but can be overridden if so wished
 180
 181 =head2 lsid_string
 182
 183  Title   : lsid_string
 184  Usage   : $string   = $obj->lsid_string()
 185  Function: a string which gives the LSID standard
 186            notation for the identifier of interest
 187
 188
 189  Returns : A scalar
 190
 191 =cut
 192
 193 sub lsid_string {
 194   my ($self) = @_;
 195
 196   return $self->authority.":".$self->namespace.":".$self->object_id;
 197 }
 198
 199
 200
 201 =head2 namespace_string
 202
 203  Title   : namespace_string
 204  Usage   : $string   = $obj->namespace_string()
 205  Function: a string which gives the common notation of
 206            namespace:object_id.version
 207  Returns : A scalar
 208
 209 =cut
 210
 211 sub namespace_string {
 212   my ($self) = @_;
 213
 214   return $self->namespace.":".$self->object_id .
 215       (defined($self->version()) ? ".".$self->version : '');
 216 }
 217
 218 1;