Bio/Annotation/SimpleValue.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Annotation::SimpleValue
   4 #
   5 # Cared for by bioperl <bioperl-l@bioperl.org>
   6 #
   7 # Copyright bioperl
   8 #
   9 # You may distribute this module under the same terms as perl itself
  10
  11 # POD documentation - main docs before the code
  12
  13 =head1 NAME
  14
  15 Bio::Annotation::SimpleValue - A simple scalar
  16
  17 =head1 SYNOPSIS
  18
  19    use Bio::Annotation::SimpleValue;
  20    use Bio::Annotation::Collection;
  21
  22    my $col = Bio::Annotation::Collection->new();
  23    my $sv = Bio::Annotation::SimpleValue->new(-value => 'someval');
  24    $col->add_Annotation('tagname', $sv);
  25
  26 =head1 DESCRIPTION
  27
  28 Scalar value annotation object
  29
  30 =head1 FEEDBACK
  31
  32 =head2 Mailing Lists
  33
  34 User feedback is an integral part of the evolution of this and other
  35 Bioperl modules. Send your comments and suggestions preferably to one
  36 of the Bioperl mailing lists. Your participation is much appreciated.
  37
  38   bioperl-l@bioperl.org                  - General discussion
  39   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  40
  41 =head2 Reporting Bugs
  42
  43 Report bugs to the Bioperl bug tracking system to help us keep track
  44 the bugs and their resolution.  Bug reports can be submitted via
  45 the web:
  46
  47   http://bugzilla.open-bio.org/
  48
  49 =head1 AUTHOR  - Ewan Birney
  50
  51 Email birney@ebi.ac.uk
  52
  53 =head1 APPENDIX
  54
  55 The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _
  56
  57 =cut
  58
  59
  60 # Let the code begin...
  61
  62
  63 package Bio::Annotation::SimpleValue;
  64 use strict;
  65
  66 # Object preamble - inherits from Bio::Root::Root
  67
  68 #use Bio::Ontology::TermI;
  69
  70 use base qw(Bio::Root::Root Bio::AnnotationI);
  71
  72 =head2 new
  73
  74  Title   : new
  75  Usage   : my $sv = Bio::Annotation::SimpleValue->new();
  76  Function: Instantiate a new SimpleValue object
  77  Returns : Bio::Annotation::SimpleValue object
  78  Args    : -value    => $value to initialize the object data field [optional]
  79            -tagname  => $tag to initialize the tagname [optional]
  80            -tag_term => ontology term representation of the tag [optional]
  81
  82 =cut
  83
  84 sub new{
  85    my ($class,@args) = @_;
  86
  87    my $self = $class->SUPER::new(@args);
  88
  89    my ($value,$tag,$term) =
  90        $self->_rearrange([qw(VALUE TAGNAME TAG_TERM)], @args);
  91
  92    # set the term first
  93    defined $term   && $self->tag_term($term);
  94    defined $value  && $self->value($value);
  95    defined $tag    && $self->tagname($tag);
  96
  97    return $self;
  98 }
  99
 100
 101 =head1 AnnotationI implementing functions
 102
 103 =cut
 104
 105 =head2 as_text
 106
 107  Title   : as_text
 108  Usage   : my $text = $obj->as_text
 109  Function: return the string "Value: $v" where $v is the value
 110  Returns : string
 111  Args    : none
 112
 113
 114 =cut
 115
 116 sub as_text{
 117    my ($self) = @_;
 118
 119    return "Value: ".$self->value;
 120 }
 121
 122 =head2 display_text
 123
 124  Title   : display_text
 125  Usage   : my $str = $ann->display_text();
 126  Function: returns a string. Unlike as_text(), this method returns a string
 127            formatted as would be expected for te specific implementation.
 128
 129            One can pass a callback as an argument which allows custom text
 130            generation; the callback is passed the current instance and any text
 131            returned
 132  Example :
 133  Returns : a string
 134  Args    : [optional] callback
 135
 136 =cut
 137
 138 {
 139   my $DEFAULT_CB = sub { $_[0]->value};
 140
 141   sub display_text {
 142     my ($self, $cb) = @_;
 143     $cb ||= $DEFAULT_CB;
 144     $self->throw("") if ref $cb ne 'CODE';
 145     return $cb->($self);
 146   }
 147
 148 }
 149
 150 =head2 hash_tree
 151
 152  Title   : hash_tree
 153  Usage   : my $hashtree = $value->hash_tree
 154  Function: For supporting the AnnotationI interface just returns the value
 155            as a hashref with the key 'value' pointing to the value
 156  Returns : hashrf
 157  Args    : none
 158
 159
 160 =cut
 161
 162 sub hash_tree{
 163     my $self = shift;
 164
 165     my $h = {};
 166     $h->{'value'} = $self->value;
 167     return $h;
 168 }
 169
 170 =head2 tagname
 171
 172  Title   : tagname
 173  Usage   : $obj->tagname($newval)
 174  Function: Get/set the tagname for this annotation value.
 175
 176            Setting this is optional. If set, it obviates the need to
 177            provide a tag to AnnotationCollection when adding this
 178            object.
 179
 180  Example :
 181  Returns : value of tagname (a scalar)
 182  Args    : new value (a scalar, optional)
 183
 184
 185 =cut
 186
 187 sub tagname{
 188     my $self = shift;
 189
 190     # check for presence of an ontology term
 191     if($self->{'_tag_term'}) {
 192         # keep a copy in case the term is removed later
 193         $self->{'tagname'} = $_[0] if @_;
 194         # delegate to the ontology term object
 195         return $self->tag_term->name(@_);
 196     }
 197     return $self->{'tagname'} = shift if @_;
 198     return $self->{'tagname'};
 199 }
 200
 201
 202 =head1 Specific accessors for SimpleValue
 203
 204 =cut
 205
 206 =head2 value
 207
 208  Title   : value
 209  Usage   : $obj->value($newval)
 210  Function: Get/Set the value for simplevalue
 211  Returns : value of value
 212  Args    : newvalue (optional)
 213
 214
 215 =cut
 216
 217 sub value{
 218    my ($self,$value) = @_;
 219
 220    if( defined $value) {
 221       $self->{'value'} = $value;
 222     }
 223     return $self->{'value'};
 224 }
 225
 226 =head2 tag_term
 227
 228  Title   : tag_term
 229  Usage   : $obj->tag_term($newval)
 230  Function: Get/set the L<Bio::Ontology::TermI> object representing
 231            the tag name.
 232
 233            This is so you can specifically relate the tag of this
 234            annotation to an entry in an ontology. You may want to do
 235            this to associate an identifier with the tag, or a
 236            particular category, such that you can better match the tag
 237            against a controlled vocabulary.
 238
 239            This accessor will return undef if it has never been set
 240            before in order to allow this annotation to stay
 241            light-weight if an ontology term representation of the tag
 242            is not needed. Once it is set to a valid value, tagname()
 243            will actually delegate to the name() of this term.
 244
 245  Example :
 246  Returns : a L<Bio::Ontology::TermI> compliant object, or undef
 247  Args    : on set, new value (a L<Bio::Ontology::TermI> compliant
 248            object or undef, optional)
 249
 250
 251 =cut
 252
 253 sub tag_term{
 254     my $self = shift;
 255
 256     return $self->{'_tag_term'} = shift if @_;
 257     return $self->{'_tag_term'};
 258 }
 259
 260 1;