view release on metacpan or  search on metacpan

lib/Color/Fade.pm  view on Meta::CPAN

		$nodeStart++;
	}

	return wantarray ? @faded : join ("",@faded);
}

sub average_colors {
	my ($alpha,$beta) = @_;

	# This function, given two hex colors, returns the value of the color
	# directly between the two colors (an average of two).

	# Separate the hex values.
	my (@hexStart) = $alpha =~ /^(..)(..)(..)$/i;
	my (@hexEnd)   = $beta  =~ /^(..)(..)(..)$/i;

	# Get their numeric counterparts.
	my @decStart = (
		hex("0x" . $hexStart[0]),
		hex("0x" . $hexStart[1]),
		hex("0x" . $hexStart[2]),
	);
	my @decEnd = (
		hex("0x" . $hexEnd[0]),
		hex("0x" . $hexEnd[1]),
		hex("0x" . $hexEnd[2]),
	);

	# Get the averages of each color.
	my $avRed = int( ($decStart[0] + $decEnd[0]) / 2 );
	my $avGrn = int( ($decStart[1] + $decEnd[1]) / 2 );
	my $avBlu = int( ($decStart[2] + $decEnd[2]) / 2 );

	# And convert the averages back into hex.
	my @hexAvg = (
		sprintf ("%02x", $avRed),
		sprintf ("%02x", $avGrn),
		sprintf ("%02x", $avBlu),
	);
	return join("",@hexAvg);
}

1;
__END__

=head1 NAME

Color::Fade - Perl extension for fading text colors.

=head1 SYNOPSIS

  use Color::Fade qw(color_fade format_color);

  print format_color ("html", color_fade (
    'Jackdaws love my big sphynx of quartz.',
    '#FF0000', '#00FF00', '#0000FF',
  ));

=head1 DESCRIPTION

Color::Fade uses mathematical formulas to take an input string of virtually any length,
and virtually any number of colors, and assign an individual color to each character to
fade between each of the input colors.

In other words, it makes your sentences look really pretty. :)

=head2 EXPORT

Exports color_fade and format_color on demand.

=head1 METHODS

=head2 color_fade ($string, @colors)

Fade C<$string> among the colors in C<@colors>, where C<$string> is a string of length
greater than zero, and C<@colors> is an array of colors in six byte hexadecimal format,
with or without the leading octothorpe. C<@colors> must have at least two elements.

When called in array context, the method returns an array in which each element is of
the format:

  <color #xxxxxx>y

For each character, where C<xxxxxx> is a hexadecimal color code and C<y> is one character
from the original string.

When called in scalar context, this array is joined before being returned.

B<Note:> It is perfectly possible to have more colors than you have characters in the
original string. All that will happen is that each character of output will have a color
from the original array, in the order the array was passed in, until there are no characters
left.

B<Debug mode:> To activate debug mode, set the global variable C<$Color::Fade::debug>
to a true value.

=head2 format_color ($format,@codes)

Formats the color data for display. C<$format> is a format to use and C<@colors>
is the B<array> you got from C<color_fade()>. C<$format> can either be a format
or a built-in name of a predefined format. If given as a format, use the placeholders
C<$color> and C<$char> as literals.

The pre-defined formats are:

  html   <font color="$color">$char</font>
  ubb    [color=$color]$char[/color]
  css    <span style="color: $color">$char</span>

Some examples:

  # Get an array of color codes.
  my @codes = color_fade ("Hello, world!", '#FF0000', '#0000FF');

  # Format it for HTML using the built-in format.
  my $html = format_color ('html', @codes);

  # Format it for AOL IM (meaning: no </font> tags allowed, as these mess
  # up the whole format of the IM message, at least as of AIM 5.9)
  my $aim = format_color ('<font color="$color">$char', @codes);