NAME

Number::RGB - Manipulate RGB Tuples

SYNOPSIS

use Number::RGB;
my $white :RGB(255);
my $black :RGB(0);

my $gray = $black + ( $white / 2 );

my @rgb = @{ $white->rgb };
my $hex = $black->hex;

my $blue   = Number::RGB->new(rgb => [0,0,255]);
my $green  = Number::RGB->new(hex => '#00FF00');

my $red :RGB(255,0,0);

my $purple = $blue + $green;
my $yellow = $red  + $green;

DESCRIPTION

This module creates RGB tuple objects and overloads their operators to make RGB math easier. An attribute is also exported to the caller to make construction shorter.

Methods

new

my $red   = Number::RGB->new(rgb => [255,0,0])
my $blue  = Number::RGB->new(hex => '#0000FF');
my $blue  = Number::RGB->new(hex => '#00F');
my $black = Number::RGB->new(rgb_number => 0);

This constructor accepts named parameters. One of three parameters are required.

rgb is a array reference containing three integers within the range of 0..255. In order, each integer represents red, green, and blue.

hex is a hexadecimal representation of an RGB tuple commonly used in Cascading Style Sheets. The format begins with an optional hash (#) and follows with three groups of hexadecimal numbers representing red, green, and blue in that order. A shorthand, 3-digit version can be used: #123 is equivalent to #112233.

rgb_number is a single integer to use for each of the three primary colors. This is shorthand to create white, black, and all shades of gray.

This method throws an exception on error.

new_from_guess

my $color = Number::RGB->new_from_guess( ... );

This constructor tries to guess the format being used and returns a tuple object. If it can't guess, an exception will be thrown.

Note: a single number between 0..255 will never be interpreted as a hex shorthand. You'll need to explicitly prepend # character to disambiguate and force hex mode.

r

Accessor and mutator for the red value.

g

Accessor and mutator for the green value.

b

Accessor and mutator for the blue value.

rgb

Returns a array reference containing three elements. In order they represent red, green, and blue.

hex

Returns a hexadecimal representation of the tuple conforming to the format used in Cascading Style Sheets.

hex_uc

Returns the same thing as "hex", but any hexadecimal numbers that include 'A'..'F' will be in upper case.

as_string

Returns a string representation of the tuple. For example, white would be the string 255,255,255.

Attributes

:RGB()

my $red   :RGB(255,0,0);
my $blue  :RGB(#0000FF);
my $white :RGB(0);

This attribute is exported to the caller and provides a shorthand wrapper around "new_from_guess".

Overloads

Number::RGB overloads the following operations:

""
+
-
*
/
%
**
<<
>>
&
^
|

Stringifying a Number::RGB object will produce a string with three RGB tuples joined with commas. All other operators operate on each individual RGB tuple number.

If the tuple value is below 0 after the operation, it will set to 0. If the tuple value is above 255 after the operation, it will set to 255.

Note: illegal operations (such us dividing by zero) result in the tuple value being set to 0.

Operations create new Number::RGB objects, which means that even something as strange as this still works:

my $color :RGB(5,10,50);
print 110 - $color; # prints '105,100,60'

REPOSITORY

BUGS

MAINTAINER

This module is currently maintained by:

ZOFFIX

AUTHOR

CWEST

LICENSE

You can use and distribute this module under the same terms as Perl itself. See the LICENSE file included in this distribution for complete details.