Bio/AnnotationI.pm

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