NAME

       Bio::Annotation::StructuredValue - A scalar with embedded structured information

SYNOPSIS

          use Bio::Annotation::StructuredValue;
          use Bio::Annotation::Collection;

          my $col = Bio::Annotation::Collection->new();
          my $sv = Bio::Annotation::StructuredValue->new(-value => 'someval');
          $col->add_Annotation('tagname', $sv);

DESCRIPTION

       Scalar value annotation object.

FEEDBACK

   Mailing Lists
       User feedback is an integral part of the evolution of this and other Bioperl modules. Send
       your comments and suggestions preferably to one of the Bioperl mailing lists. Your
       participation is much appreciated.

         bioperl-l@bioperl.org                  - General discussion
         http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

   Support
       Please direct usage questions or support issues to the mailing list:

       bioperl-l@bioperl.org

       rather than to the module maintainer directly. Many experienced and reponsive experts will
       be able look at the problem and quickly address it. Please include a thorough description
       of the problem with code and data examples if at all possible.

   Reporting Bugs
       Report bugs to the Bioperl bug tracking system to help us keep track the bugs and their
       resolution.  Bug reports can be submitted via or the web:

         https://redmine.open-bio.org/projects/bioperl/

AUTHOR - Hilmar Lapp

       Email hlapp-at-gmx.net

APPENDIX

       The rest of the documentation details each of the object methods. Internal methods are
       usually preceded with a _

   new
        Title   : new
        Usage   : my $sv = Bio::Annotation::StructuredValue->new();
        Function: Instantiate a new StructuredValue object
        Returns : Bio::Annotation::StructuredValue object
        Args    : -value => $value to initialize the object data field [optional]
                  -tagname => $tag to initialize the tagname [optional]

AnnotationI implementing functions

   as_text
        Title   : as_text
        Usage   : my $text = $obj->as_text
        Function: return the string "Value: $v" where $v is the value
        Returns : string
        Args    : none

   display_text
        Title   : display_text
        Usage   : my $str = $ann->display_text();
        Function: returns a string. Unlike as_text(), this method returns a string
                  formatted as would be expected for te specific implementation.

                  One can pass a callback as an argument which allows custom text
                  generation; the callback is passed the current instance and any text
                  returned
        Example :
        Returns : a string
        Args    : [optional] callback

   hash_tree
        Title   : hash_tree
        Usage   : my $hashtree = $value->hash_tree
        Function: For supporting the AnnotationI interface just returns the value
                  as a hashref with the key 'value' pointing to the value
        Returns : hashrf
        Args    : none

   tagname
        Title   : tagname
        Usage   : $obj->tagname($newval)
        Function: Get/set the tagname for this annotation value.

                  Setting this is optional. If set, it obviates the need to provide
                  a tag to AnnotationCollection when adding this object.
        Example :
        Returns : value of tagname (a scalar)
        Args    : new value (a scalar, optional)

Specific accessors for StructuredValue

   value
        Title   : value
        Usage   : $obj->value($newval)
        Function: Get/set the value for this annotation.

                  Set mode is here only to retain compatibility with
                  SimpleValue. It is equivalent to calling
                  add_value([0], $newval).

                  In get mode, this implementation allows one to pass additional
                  parameters that control how the structured annotation
                  components will be joined together to form a
                  string. Recognized are presently
                      -joins     a reference to an array of join strings, the
                                 elements at index i applying to joining
                                 annotations at dimension i. The last element
                                 will be re-used for dimensions higher than i.
                                 Defaults to ['; '].
                      -brackets  a reference to an array of two strings
                                 denoting the opening and closing brackets for
                                 the elements of one dimension, if there is
                                 more than one element in the dimension.
                                 Defaults to ['(',')'].

        Returns : value of value
        Args    : newvalue (optional)

   get_values
        Title   : get_values
        Usage   :
        Function: Get the top-level array of values. Each of the elements will
                  recursively be a reference to an array or a scalar, depending
                  on the depth of this structured value annotation.
        Example :
        Returns : an array
        Args    : none

   get_all_values
        Title   : get_all_values
        Usage   :
        Function: Flattens all values in this structured annotation and
                  returns them as an array.
        Example :
        Returns : the (flat) array of values
        Args    : none

   add_value
        Title   : add_value
        Usage   :
        Function: Adds the given value to the structured annotation at the
                  given index.

                  The index is multi-dimensional, with the first dimension
                  applying to the first level, and so forth. If a particular
                  dimension or a particular index does not exist yet, it will
                  be created. If it does exist and adding the value would
                  mean replacing a scalar with an array reference, we throw
                  an exception to prevent unintended damage. An index of -1
                  at any dimension means append.

                  If an array of values is to be added, it will create an
                  additional dimension at the index specified, unless the
                  last index value is -1, in which case they will all be
                  appended to the last dimension.

        Example :
        Returns : none
        Args    : the index at which to add (a reference to an array)
                  the value(s) to add