File Coverage

Bio/IdentifiableI.pm
Criterion Covered Total %
statement 10 18 55.5
branch 1 2 50.0
condition n/a
subroutine 4 8 50.0
pod 6 6 100.0
total 21 34 61.7


line stmt bran cond sub pod time code
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.
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
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 216     216   1169 use strict;
  216         254  
  216         5895  
94              
95              
96 216     216   882 use base qw(Bio::Root::RootI);
  216         330  
  216         42691  
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 0     0 1 0 my ($self) = @_;
117 0         0 $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 0     0 1 0 my ($self) = @_;
135 0         0 $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 0     0 1 0 my ($self) = @_;
153 0         0 $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 0     0 1 0 my ($self) = @_;
171 0         0 $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 2     2 1 3 my ($self) = @_;
194              
195 2         4 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 4     4 1 6 my ($self) = @_;
212              
213 4 50       8 return $self->namespace.":".$self->object_id .
214             (defined($self->version()) ? ".".$self->version : '');
215             }
216              
217             1;