Bio/AnnotationI.pm

filter: Statementstmt 66.6% 8 / 12 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 33.3% 2 / 6 Podpod 100% 4 / 4 totaltotal 63.6% 14 / 22 CC 1 SCAR 5.1
CC
1
Cov
67%
as_text
2.0
display_text
2.0
hash_tree
2.0
CRAP 1.7
« Bio/Search/DatabaseI.pm ↑ Summary Bio/HandlerBaseI.pm »
1 #
2 # BioPerl module for Bio::AnnotationI
3 #
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
5 #
6 # Cared for by Ewan Birney <birney@ebi.ac.uk>
7 #
8 # Copyright Ewan Birney
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::AnnotationI - Annotation interface
17  
18 =head1 SYNOPSIS
19  
20 # generally you get AnnotationI's from AnnotationCollectionI's
21  
22 foreach $key ( $ac->get_all_annotation_keys() ) {
23 @values = $ac->get_Annotations($key);
24 foreach $value ( @values ) {
25 # value is an Bio::AnnotationI, and defines a "as_text" method
26 print "Annotation ",$key," stringified value ",$value->as_text,"\n";
27 # you can also use a generic hash_tree method for getting
28 # stuff out say into XML format
29 $hash_tree = $value->hash_tree();
30 }
31 }
32  
33 =head1 DESCRIPTION
34  
35 Interface all annotations must support. There are two things that each
36 annotation has to support.
37  
38 $annotation->as_text()
39  
40 Annotations have to support an "as_text" method. This should be a
41 single text string, without newlines representing the annotation,
42 mainly for human readability. It is not aimed at being able to
43 store/represent the annotation.
44  
45 The second method allows annotations to at least attempt to represent
46 themselves as pure data for storage/display/whatever. The method
47 hash_tree should return an anonymous hash with "XML-like" formatting:
48  
49 $hash = $annotation->hash_tree();
50  
51 The formatting is as follows.
52  
53 (1) For each key in the hash, if the value is a reference'd array -
54  
55 (2) For each element of the array if the value is a object -
56 Assume the object has the method "hash_tree";
57 (3) else if the value is a reference to a hash
58 Recurse again from point (1)
59 (4) else
60 Assume the value is a scalar, and handle it directly as text
61 (5) else (if not an array) apply rules 2,3 and 4 to value
62  
63 The XML path in tags is represented by the keys taken in the
64 hashes. When arrays are encountered they are all present in the path
65 level of this tag
66  
67 This is a pretty "natural" representation of an object tree in an XML
68 style, without forcing everything to inherit off some super-generic
69 interface for representing things in the hash.
70  
71 =head1 FEEDBACK
72  
73 =head2 Mailing Lists
74  
75 User feedback is an integral part of the evolution of this
76 and other Bioperl modules. Send your comments and suggestions preferably
77 to one of the Bioperl mailing lists.
78 Your participation is much appreciated.
79  
80 bioperl-l@bioperl.org
81  
82 =head2 Support
83  
84 Please direct usage questions or support issues to the mailing list:
85  
86 I<bioperl-l@bioperl.org>
87  
88 rather than to the module maintainer directly. Many experienced and
89 reponsive experts will be able look at the problem and quickly
90 address it. Please include a thorough description of the problem
91 with code and data examples if at all possible.
92  
93 =head2 Reporting Bugs
94  
95 Report bugs to the Bioperl bug tracking system to help us keep track
96 the bugs and their resolution. Bug reports can be submitted via the
97 web:
98  
99 https://github.com/bioperl/bioperl-live/issues
100  
101 =head1 AUTHOR - Ewan Birney
102  
103 Email birney@ebi.ac.uk
104  
105 =head1 APPENDIX
106  
107 The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _
108  
109 =cut
110  
111 #'
112 # Let the code begin...
113  
114  
115 package Bio::AnnotationI;
116 346 $Bio::AnnotationI::VERSION = '1.7.8';
117 346 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
118  
119 # Object preamble - inherits from Bio::Root::Root
120  
121 346 ▶use base qw(Bio::Root::RootI);
Subroutine BEGIN: called CC=1 SCAR=0.0
122  
123 =head2 as_text
124  
125 Title : as_text
126 Usage :
127 Function: single text string, without newlines representing the
128 annotation, mainly for human readability. It is not aimed
129 at being able to store/represent the annotation.
130 Example :
131 Returns : a string
132 Args : none
133  
134  
135 =cut
136  
137 0 ▶sub as_text{
Subroutine as_text: not called CC=1 SCAR=6.9
Pod documented
138 0 shift->throw_not_implemented();
139 }
140  
141 =head2 display_text
142  
143 Title : display_text
144 Usage : my $str = $ann->display_text();
145 Function: returns a string. Unlike as_text(), this method returns a string
146 formatted as would be expected for the specific implementation.
147  
148 Implementations should allow passing a callback as an argument which
149 allows custom text generation; the callback will be passed the
150 current implementation.
151  
152 Note that this is meant to be used as a simple representation
153 of the annotation data but probably shouldn't be used in cases
154 where more complex comparisons are needed or where data is
155 stored.
156 Example :
157 Returns : a string
158 Args : [optional] callback
159  
160 =cut
161  
162 0 ▶sub display_text {
Subroutine display_text: not called CC=1 SCAR=6.9
Pod documented
163 0 shift->throw_not_implemented();
164 }
165  
166 =head2 hash_tree
167  
168 Title : hash_tree
169 Usage :
170 Function: should return an anonymous hash with "XML-like" formatting
171 Example :
172 Returns : a hash reference
173 Args : none
174  
175 =cut
176  
177 0 ▶sub hash_tree{
Subroutine hash_tree: not called CC=1 SCAR=6.9
Pod documented
178 0 shift->throw_not_implemented();
179 }
180  
181 =head2 tagname
182  
183 Title : tagname
184 Usage : $obj->tagname($newval)
185 Function: Get/set the tagname for this annotation value.
186  
187 Setting this is optional. If set, it obviates the need to
188 provide a tag to Bio::AnnotationCollectionI when adding
189 this object. When obtaining an AnnotationI object from the
190 collection, the collection will set the value to the tag
191 under which it was stored unless the object has a tag
192 stored already.
193  
194 Example :
195 Returns : value of tagname (a scalar)
196 Args : new value (a scalar, optional)
197  
198  
199 =cut
200  
201 0 ▶sub tagname{
Subroutine tagname: not called CC=1 SCAR=6.9
Pod documented
202 0 shift->throw_not_implemented();
203 }
204  
205 346 1;
« Bio/Search/DatabaseI.pm ↑ Summary Bio/HandlerBaseI.pm »