NAME

       Bio::Graphics::Browser2::Markup - Markup routines for sequences in text form

VERSION (CVS-info)

        $RCSfile: Markup.pm,v $
        $Revision$
        $Author: lstein $
        $Date: 2008-09-09 20:53:36 $

SYNOPSIS

        use Bio::Graphics::Browser2::Markup;

        my $string = join '','a'..'z','a'..'z','a'..'z';
        my $markup = Bio::Graphics::Browser2::Markup->new;

        $markup->add_style(cds=>'UPPERCASE');
        $markup->add_style(exon     =>'Text-decoration: underline');
        $markup->add_style(variation=>'Font-weight: bold');
        $markup->add_style(italic=>'Font-style: oblique');
        $markup->add_style(yellow=>'BGCOLOR blue');
        $markup->add_style(green=>'BGCOLOR red');
        $markup->add_style(orange=>'BGCOLOR orange');
        $markup->add_style(mango=>'FGCOLOR red');
        $markup->add_style(br=>'<br>');
        $markup->markup(\$string,[
                                 ['cds',1=>10],
                                 ['cds',12=>15],
                                 ['variation',20=>41],
                                 ['exon',0=>29],
                                 ['exon',32=>40],
                                 ['italic',18=>29],
                                 ['yellow',5=>40],
                                 ['green',20=>50],
                                 ['orange',30=>60],
                                 ['mango',0=>36],
                                 ['br',10=>10],
                                 ['br',20=>20],
                                 ['br',30=>30],
                                 ['br',40=>40],
                                 ['br',50=>50],
                                 ['br',60=>60],
                                 ]);
        print $string,"\n";

DESCRIPTION

       This module marks up a string with HTML cascading stylesheet styles in such a way that
       intersecting regions contain the union of the two intersecting styles.  It also handles
       colors in such a way that intersecting colors are added up.

METHODS

   $annotator = Bio::Graphics::Browser2::Markup->new
       Create a new Markup object.

   $old_style = $annotator->add_style($symbolic_name=>$style)
       Add an annotation style.

       $symbolic name is a unique identifier to be used for ornamenting the string.

       $style is one of:

          - a CSS/2 stylesheet entry of form "style: value"
          - the word   "UPPERCASE"         (make uppercase)
          - the word   "LOWERCASE"         (make lowercase)
          - the phrase "FGCOLOR #RRGGBB"   (foreground color)
          - the phrase "FGCOLOR color-name"
          - the phrase "BGCOLOR #RRGGBB"   (background color)
          - the phrase "BGCOLOR color-name"
          - an HTML tag, indicated by a leading "E<lt>" character
          - anything else, will be inserted blindly

       When calculating intersected regions, styles will be aggregated, upper and lowercasing
       will be performed directly on the data, colors will be additive, and HTML will be inserted
       blindly.

       An invalid color name will cause this module to die.  Valid color names can be obtained
       this way:

        perl -MBio::Graphics::Panel \
             -e 'print join "\n",sort Bio::Graphics::Panel->color_names'

   $style = $annotator->style($symbolic_name)
       Get the style corresponding to symbolic name, or undef if the name is unrecognized.

   $style = $annotator->get_style($symbolic_name)
       Get a list of CSS/2 styles corresponding to symbolic name.  Will die if the name is not
       recognized or does not correspond to an entry of type "style".

   $flag = $annotator->valid_symbol($symbolic_name)
       Return true if the symbolic name is valid.

   $result = $annotator->markup(\$sequence,\@annotated_regions)
       Mark up the string referenced by $sequence, according to the regions contained in
       $annotated_regions.

       $sequence is a scalar ref, which will be modified in place (make a copy of it if you need
       to).  $annotated_regions is a arrayref to the following list:

         ([symbolic_name,start,end], [symbolic_name,start,end], ....)

       The result indicates whether the markup was successful.

       IMPORTANT: Regions are numbered using space-oriented coordinates, which means that start=0
       means to insert in front of the first base pair, and an end equal to the sequence length
       will insert after the last base pair:

         0 1 2 3 4 5 6 7     perl string coordinates
         1 2 3 4 5 6 7 8     sequence coordinates
         g a t c g a t c     sequence
        0 1 2 3 4 5 6 7 8    space coordinates

        To select first base:                    start=0, end=1
        To insert markup between bases 1 and 2:  start=1, end=1
        To select last base:                     start=7, end=8
        To select entire sequence:               start=0, end=8

       This means that some munging of the sequence annotation must be performed, but it keeps
       the notation unambiguous.

   Internal Methods (not for external use; documentation incomplete)
       @events = $annotator->_add_colors($style_tag,$regions)
       $style_symbol = $annotator->_add_colors($style_tag,$regions)
       $color = $annotator->_add_color($color1,$color2)
       $color = $annotator->_subtract_color($color1,$color2)
       $html_color = $annotator->_to_html_color($color)
       @tag_positions = $annotator->_unify($region_definitions)
       $style_fragment = $annotator->_to_style($symbols)
       @tag_positions = $annotator->_linearize_html($region_definitions)
       \@events = $annotator->_regions_to_events($regions)
           turn a series of regions into a series of start and end events because of the problem
           of events that start/stop in the same place each event also gets a sequence that can
           be used to keep events matched in a nested way

       $annotator->_add_markup($string_to_modify,$tag_positions)

SEE ALSO

       Bio::Graphics::Panel, Bio::Graphics::Glyph, Bio::Graphics::Feature,
       Bio::Graphics::FeatureFile, Bio::Graphics::Browser, Bio::Graphics::Browser2::Plugin

AUTHOR

       Lincoln Stein <lstein@cshl.org>.

       Copyright (c) 2002 Cold Spring Harbor Laboratory

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.  See DISCLAIMER.txt for disclaimers of warranty.