lib/Bio/Annotation/SimpleValue.pm

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