File Coverage

blib/lib/HTML/Rainbow.pm

Criterion	Covered	Total	%
statement	44	44	100.0
branch	28	28	100.0
condition	5	5	100.0
subroutine	7	7	100.0
pod	2	2	100.0
total	86	86	100.0

# HTML::Rainbow.pm
#
# Copyright (c) 2005-2009 David Landgren
# All rights reserved

package HTML::Rainbow;

use strict;
use Exporter;
use Tie::Cycle::Sinewave;

use vars qw/$VERSION @PRIMES @ISA @EXPORT_OK/;

$VERSION = '0.06';
@ISA     = ('Exporter');
@PRIMES  = qw(17 19 23 29 31 37 41 43 47 53 59 61 67 71 73 79);

=head1 NAME

HTML::Rainbow - Put colour into your HTML

=head1 VERSION

This document describes version 0.06 of HTML::Rainbow, released
2009-10-04.

=head1 SYNOPSIS

  use HTML::Rainbow 'rainbow';
  print rainbow('hello, world');

=head1 DESCRIPTION

C will take plain text string (or array of strings)
and mark it up with C<<  >> tags (or C<<  >> tags
if you're feeling particularly orthodox), and produce text that
drifts endlessly from one colour to the next.

The intensity of the red, green and blue channels follow mutually
prime sinusoidal periods.

=for html
This comes in handy when you have the burning desire
to say
P
color="#7c797c">er
color="#8e878e">l i
color="#9f949f">s a
color="#afa0af">la
color="#beacbe">ng
color="#c9b7c9">ua
color="#d2c1d2">ge
color="#d8c9d8">op
color="#dbd0db">ti
color="#dbd5db">mi
color="#d9d9cc">ze
color="#d6dbad">d f
color="#d1db83">or
color="#ccd656">sc
color="#c5ca2e">an
color="#bdb813">ni
color="#b5a00a">ng
color="#ab860d">ar
color="#a16a0f">bi
color="#964f12">tr
color="#8b3615">ar
color="#802119">y t
color="#74131d">ex
color="#680b22">t f
color="#5d0a27">il
color="#52522c">es
color="#47c032">, e
color="#3cd338">xt
color="#33ce3f">ra
color="#2ac845">ct
color="#22c04c">in
color="#1bb854">g i
color="#15af5b">nf
color="#10a562">or
color="#0d9b6a">ma
color="#0b9072">ti
color="#0a8479">on
color="#0a7981">fr
color="#0b6d88">om
color="#0d6190">th
color="#0f5697">os
color="#134b9e">e t
color="#1740a5">ex
color="#1b36ab">t f
color="#202db2">il
color="#2625b8">es
color="#2d1ebd">, a
color="#3317c2">nd
color="#3b12c7">pr
color="#420ecb">in
color="#4a0bcf">ti
color="#530ad3">ng
color="#5b0ad5">re
color="#640cd8">po
color="#6d12d9">rt
color="#761adb">s b
color="#7e25db">as
color="#8733db">ed
color="#9043d7">on
color="#9854cc">th
color="#a066ba">at
color="#a879a3">in
color="#b08b89">fo
color="#b79d6d">rm
color="#bdad51">at
color="#c3bc38">io
color="#c8c823">n.
color="#cdd114">It
color="#d1d80b">'s
color="#d5db0a">al
color="#d8db10">so
color="#dad91d">a g
color="#dbd530">oo
color="#dbd048">d l
color="#dbc963">an
color="#d6c17f">gu
color="#c9b79a">ag
color="#b7acb2">e f
color="#9fa0c6">or
color="#8494d4">ma
color="#6986db">ny
color="#4d79da">sy
color="#356bd6">st
color="#205ece">em
color="#1251c4">ma
color="#0b44b7">na
color="#0a38a8">ge
color="#532e97">me
color="#c12485">nt
color="#d31c73">ta
color="#741560">sk
color="#140f4e">s.
color="#220c3e">Th
color="#460a2e">e l
color="#720a21">an
color="#9e0a17">gu
color="#c20c0f">ag
color="#d80d0b">e i
color="#da100a">s i
color="#d7120f">nt
color="#d21626">en
color="#cc1a4c">de
color="#c41e78">d t
color="#bb23a4">o b
color="#b128c6">e p
color="#a52dd9">ra
color="#9933d9">ct
color="#8c39d6">ic
color="#7f40d2">al
color="#7147cc">(e
color="#644ec5">as
color="#5655be">y t
color="#4a5cb5">o u
color="#3d64ac">se
color="#326ca2">, e
color="#287397">ff
color="#1f7b8c">ic
color="#178280">ie
color="#118a75">nt
color="#0d9169">, c
color="#0a985d">om
color="#0a9f52">pl
color="#0ba647">et
color="#15ad3d">e)
color="#24b333">ra
color="#39b92a">th
color="#53be22">er
color="#6ec31b">th
color="#8ac815">an
color="#a4cc10">be
color="#bbd00d">au
color="#cdd30b">ti
color="#d8d60a">fu
color="#dbd80a">l (
color="#dada0d">ti
color="#d7db13">ny
color="#d3db1c">, e
color="#cedb28">le
color="#c7d037">ga
color="#c0b447">nt
color="#b88b58">, m
color="#af5e6a">in
color="#a5357d">im
color="#9a178f">al
color="#8f0aa1">).

Win friends, and influence enemies, on your favourite
HTML bulletin board.

=head1 METHODS

=over 8

=item B

Creates a new C object. A set of key/value parameters
can be supplied to control the finer details of the object's
behaviour.

The colour-space of HTML is defined by a tuple of red, green and
blue components. Each component can vary between 0 and 255. Setting
all components to 0 produces black, and setting them all to 255
produces white. The parameters for C allow you to control
the behaviour of the components, either individually or as a whole.

Each value may be specifed as a number from 0 to 255, or as a
percentage (such as C<50%>). Percentages are rounded to the nearest
integer, and values out of range are clipped to the nearest bound.

=over 4

=item min

Sets the minimum value for all three components. For example, a
value of 0 (zero) may result in white being produced. This may
produce invisible text if the background colour is also white.
Hence, one may wish to use a value between 20 to 40 if this is the
case.

=item max

Sets the maximum value for all three components. Setting it to C<100%> or
255 may result in black being produced. A similar warning concerning a
background colour of black applies here.

=item min_red, min_green, min_blue

Sets the minimum value for the specified colour component.

=item max_red, max_green, max_blue

Sets the maximum value for the specified colour component.

=item red, green, blue

Sets the value of the specified colour component to a fixed value.
For example, the following call to new()...

  my $r = HTML::Rainbow->new(
    red      =>   0,
    green    =>   0,
    min_blue =>  10,
    max_blue => 240,
  );

... will result in a rainbow generator that moves through various
shades of blue.

=item period_list

Set the periods available to choose from. At each peak and trough
of the sine wave followed by each colour component, a new period
length is chosen at random. This is to ensure that the sequence
of colours does not repeat itself too rapidly. Prime numbers
are well suited, and the value of period should be at least 10 (ten) or
more for best results. A list of periods, from 17 to 79, is used by
default. Very long texts will benefit from longer periods. The
parameter is a reference to an array.

  my $r = HTML::Rainbow->new(
    min => 0,
    max => '80%',
    period_list => [qw[ 19 37 53 71 89 107 131 151 173 193 ]],
  );

=item use_span

Use the HTML C<<  >> element instead of the C<<  >>
element for specifying the colour. The result uses 6 more characters
per marked up character.

=back

The most specific parameter wins. If both, for example, a C
and a C parameter are found, the C parameter wins.
If a C and a C parameter is found, the C
parameter wins.

=cut

sub new {
    my $class = shift;
    my %args = @_;

    # sanity checks for %args
    for my $attr(
        qw(min max),
        map {( $_, "${_}_min", "${_}_max" )} qw( red green blue )
    ) {
        next unless exists $args{$attr};
        # reduce round-off errors
        # perl -le 'print 1/2+1/32+1/64+1/512+1/1024+1/4096'
        my $scale = 2 + 1/2 + 1/32 + 1/64 + 1/512 + 1/1024 + 1/4096;
        # 2.550048828125 approx 2.55
        # 43% => 43 / 100 * 255 => 43 * 2.55 => 110
        $args{$attr} =~ s{^(\d+(?:\.\d+)?)\s*%$}{sprintf('%d',sprintf('%0.2f',$1) * $scale)}e;
        $args{$attr} =   0 if $args{$attr} <   0;
        $args{$attr} = 255 if $args{$attr} > 255;
    }

    my $self = {
        period   => $args{period_list} ? $args{period_list} : \@PRIMES,
        use_span => $args{use_span } || 0,
    };

    my $change_period = sub {
        my $s = shift;
        $s->period( $self->{period}[rand @{$self->{period}}] );
    };

    tie $self->{$_}, 'Tie::Cycle::Sinewave', {
        min => defined $args{$_}
            ? $args{$_}
            : defined $args{"${_}_min"}
                ? $args{"${_}_min"}
                : defined $args{min}
                    ? $args{min}
                    : 16,
        max => defined $args{$_}
            ? $args{$_}
            : defined $args{"${_}_max"}
                ? $args{"${_}_max"}
                : defined $args{max}
                    ? $args{max}
                    : 240,
        period => $self->{period}[ rand @{$self->{period}} ],
        at_min => $change_period,
        at_max => $change_period,
    } for qw( red green blue );

    bless $self, $class;
}

=item B

Converts each passed parameter to rainbowed markup, and returns
a single scalar with the resulting marked up text.

  print $r->rainbow( 'somewhere over the rainbow, bluebirds fly' );

You can avoid using an intermediate variable by chaining the
C method on from the C method:

  print HTML::Rainbow->new(
    max => 127,
    min =>   0,
    period_list => [qw[ 11 29 47 71 97 113 149 173 ]],
  )->rainbow( $text );

=cut

push @EXPORT_OK, 'rainbow';
{
    my $ctx;
    sub rainbow {
        my $self = shift;
        my $out  = '';
        if (!($self and UNIVERSAL::isa($self,'HTML::Rainbow'))) {
            # called as a function, not a method
            unshift @_, $self;
            $self = $ctx ? $ctx : $ctx = HTML::Rainbow->new;
        }
        for my $str( grep defined, @_ ) {
            for my $ch( split //, $str ) {
                if( $ch =~ /^\s$/ ) {
                    $out .= $ch;
                }
                else {
                    my $triple = sprintf( "#%02x%02x%02x",
                        $self->{red}, $self->{green}, $self->{blue}
                    );
                    if( $self->{use_span} ) {
                        $out .= qq{$ch};
                    }
                    else {
                        $out .= qq{$ch};
                    }
                }
            }
        }
        $out
    }
}

=back

=head1 DIAGNOSTICS

None.

=head1 SEE ALSO

=over 8

=item L

The individual red, green and blue colour components follow
sinewaves produced by this module.

=item L

If you want to modify an existing HTML page, you'll probably have
to parse it in order to extract the text. The C directory
contains some examples to show how this may be done.

=back

=head1 EXAMPLE

The following example produces a valid HTML page.

  use strict;
  use warnings;

  use CGI ':standard';
  use HTML::Rainbow;

  print header(),
    start_html(),
    HTML::Rainbow->new->rainbow('hello, world'),
    end_html();

=head1 BUGS

None known.

Please report all bugs at
L

Make sure you include the output from the following two commands:

  perl -MHTML::Rainbow -le 'print $HTML::Rainbow::VERSION'
  perl -V

=head1 ACKNOWLEDGEMENTS

This module is dedicated to John Lang, someone I used to work
with back in the early days of the web. I found him one day
painstakingly writing HTML in a text editor and reviewing the
results in Netscape. He was trying to do something like this,
to post to a bulletin board, so I wrote some very ugly Perl
to help him out. Ten years later, I finally got around to
cleaning it up.

=head1 AUTHOR

David Landgren, copyright (C) 2005-2009. All rights reserved.

http://www.landgren.net/perl/

If you (find a) use this module, I'd love to hear about it.
If you want to be informed of updates, send me a note. You
know my first name, you know my domain. Can you guess my
e-mail address?

=head1 LICENSE

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut

'The Lusty Decadent Delights of Imperial Pompeii';
__END__