Bio/AnnotationI.pm

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