NAME
   Number::RGB - Manipulate RGB Tuples

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

     my $gray = $black + (($white - $black) / 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 $black = Number::RGB->new(rgb_number => 0);

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

       "rgb" is a list reference containing three intergers within the
       range of 0..255. In order, each interger represents *red*, *green*,
       and *blue*.

       "hex" is a hexidecimal representation of an RGB tuple commonly used
       in Cascading Style Sheets. The format begins with an optional hash
       ("#") and follows with three groups of hexidecimal numbers
       represending *red*, *green*, and *blue* in that order.

       "rgb_number" is a single integer which represents all primary
       colors. This is shorthand to create *white*, *black*, and all shades
       of *gray*.

       This method throws and exception on error, which should be caught
       with "eval".

   "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 list reference containing three elements. In order they
       represent *red*, *green*, and *blue*.

   "hex()"
       Returns a hexidecimal represention of the tuple conforming to the
       format used in Cascading Style Sheets.

   "hex_uc()"
       Returns the same thing as "hex()", but any hexidecimal numbers that
       include 'A'..'F' will be uppercased.

   "as_string()"
       Returns a string representation of the tuple. For example, *black*
       would be the string "255,255,255".

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

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

 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()".

AUTHOR
   Casey West, <[email protected]>.

COPYRIGHT
     Copyright (c) 2004 Casey West.  All rights reserved.
     This module is free software; you can redistribute it and/or modify it
     under the same terms as Perl itself.