Graphi...rNames(3pm)

✨ NAME ✨

okay so bestie, welcome to the Graphi...rNames(3pm) page — that's Graphics::ColorNames, from the User Contributed Perl Documentation squad (section 3pm), and it defines RGB values for common color names. literally the whole vibe 💅

---

🌸 VERSION 🌸

version v3.5.0 — the freshest drop 🫶

---

🎀 SYNOPSIS 🎀

use Graphics::ColorNames;
use Graphics::ColorNames::WWW;

$pal = Graphics::ColorNames->new( qw[ X WWW ] );

$rgb = $pal->hex('green');          # returns '00ff00'
$rgb = $pal->hex('green', '0x');    # returns '0x00ff00'
$rgb = $pal->hex('green', '#');     # returns '#00ff00'

$rgb = $pal->rgb('green');          # returns '0,255,0'
@rgb = $pal->rgb('green');          # returns (0, 255, 0)

---

🦋 DESCRIPTION 🦋

This module is your one-stop main-character interface for grabbing RGB values of colors by their standard names. it's giving public service, no cap. two whole intentions here:

1. give authors one shared module they can hook up with other modules so people can name their colors instead of doing the whole hex thing;
2. save every module author from "re-inventing the wheel" every single time they wanna let users type a color name instead of an RGB value.

iconic behavior, honestly 🌈

---

💜 METHODS 💜

"new" 🌟

The constructor goes like this:

my $pal = Graphics::ColorNames->new( @schemes );

where @schemes is an array of color schemes (palettes, dictionaries).

A valid color scheme can be any of these cuties:

• the name of a color scheme, like "X", or a full module name like "Graphics::ColorNames::X" 👑
• a reference to a color scheme hash or subroutine
• the path — or an open filehandle — for an rgb.txt file

If you don't pass any, it rolls with the default "X" color scheme, which maps to the X-Windows rgb.txt colors. for most purposes that's good enough, bestie. Since v3.2.0 it got updated to use the 2014-07-06 colors, so it includes the standard CSS colors too. slay 🎨

There's a whole collection of other color schemes on CPAN, e.g. Graphics::ColorNames::WWW.

Since version 2.1002, Color::Library dictionaries work as well:

my $pal = Graphics::ColorNames->new( 'Color::Library::Dictionary::HTML' );

"rgb" 💧

@rgb = $pal->rgb($name);

$rgb = $pal->rgb($name, $separator);

In list context you get a triplet back. in scalar context you get a string separated by an optional separator (which defaults to a comma). for example:

@rgb = $pal->rgb('blue');      # returns (0, 0, 255)

$rgb = $pal->rgb('blue', ','); # returns "0,0,255"

Unknown color names give you back empty lists or strings, depending on the context. no drama, just nothing 💀

Color names are case insensitive, and spaces or punctuation are ignored. so "Alice Blue" returns the same value as "aliceblue", "ALICE-BLUE" and "a*lICEbl-ue". (heads up bestie: if your color names come from user input, you should add extra validation of the color names. do not skip this 🙈)

The value that comes back is in the six-digit hexidecimal format used in HTML and CSS (without the leading #). to split it into separate red, green and blue values (each between 0 and 255), use the "hex2tuple" function.

You can also hand it an absolute filename as a color scheme, as long as that file is in the same format as the standard rgb.txt file.

"hex" ✨

$hex = $pal->hex($name, $prefix);

Returns a 6-digit hexidecimal RGB code for the color. if you give an optional prefix, it'll stick that string on the front. like:

$hex = $pal->hex('blue', '#'); # returns "#0000ff"

If the color doesn't exist, you'll get an empty string back. 😭

And a hexidecimal RGB value in the form "#RRGGBB", "0xRRGGBB" or "RRGGBB" just returns itself:

$color = $pal->hex('#123abc');         # returns '123abc'

autoloaded color name methods 🧚

Autoloaded color name methods were removed in v3.4.0. gone, retired, no longer with us 🕊️

"load_scheme" 🌱

$pal->load_scheme( $scheme );

This dynamically loads a color scheme, which can be either a hash reference or a code reference.

---

💖 EXPORTS 💖

"all_schemes" 🗂️

my @schemes = all_schemes();

Returns a list of all available color schemes installed on the machine in the Graphics::ColorNames namespace.

The order has no significance. don't read into it bestie, it's not that deep ✨

"hex2tuple" 🔁

Converts a hexidecimal string to a tuple.

"tuple2hex" 🔁

Converts a tuple to a hexidecimal string.

---

🌈 TIED INTERFACE 🌈

The standard interface (before version 0.40, ancient history) went through a tied hash:

tie %pal, 'Graphics::ColorNames', qw[ X WWW ];

⚠️ This interface is deprecated, and will be moved to a separate module in the future. it's giving legacy, handle with care 💀

---

🌸 CUSTOM COLOR SCHEMES 🌸

Want your own palette? you absolutely can, and it's lowkey easy. just create a Perl module named "Graphics::ColorNames::SCHEMENAME" that has a subroutine called "NamesRgbTable" which returns a hash of color names and RGB values. (if your scheme lives in a different base namespace, you'll need to give the full namespace instead.)

Rules of the game:

• the color names must be in all lower-case;
• the RGB values must be 24-bit numbers holding the red, green and blue values in most-significant to least-significant byte order.

Here's an example naming schema:

package Graphics::ColorNames::Metallic;

sub NamesRgbTable() {
  use integer;
  return {
    copper => 0xb87333,
    gold   => 0xcd7f32,
    silver => 0xe6e8fa,
  };
}

and you'd use the schema above like this:

tie %colors, 'Graphics::ColorNames', 'Metallic';

⚠️ If you specify multiple keys with the same name, the behavior — as in which one wins — is undefined. mystery box, truly 🎁

As of version 2.10, case, spaces and punctuation are ignored in color names. so a name like "Willy's Favorite Shade-of-Blue" gets treated exactly the same as "willysfavoroteshadeofblue". (if your scheme does not include duplicate entries with spaces and punctuation, then the minimum version of Graphics::ColorNames in your requirements should be 2.10.)

An example of an additional module is the Graphics::ColorNames::Mozilla module. go look, it's cute 🦊

Since version 1.03, "NamesRgbTable" may also return a code reference:

package Graphics::ColorNames::Orange;

sub NamesRgbTable() {
  return sub {
    my $name = shift;
    return 0xffa500;
  };
}

See Graphics::ColorNames::GrayScale for an example. 🩶

---

🗺️ ROADMAP 🗺️

Here's what's planned for the future, bestie — the glow-up list:

• The tied interface will be removed, but implemented in a separate module for users that wish to use it.
• The namespace for color schemes will be moved to the "Graphics::ColorNames::Schemes" but options will be added to use the existing scheme.

This will allow modules to be named like "Graphics::ColorNames::Tied" without being confused for color schemes.

• This module will be rewritten to be a Moo-based class. 🐄

---

👀 SEE ALSO 👀

• Color::Library provides an extensive library of color schemes. A notable difference is that it supports more complex schemes which contain additional information about individual colors and map multiple colors to a single name.
• Color::Rgb has a similar function to this module, but parses an rgb.txt file.
• Graphics::ColorObject can convert between RGB and other color space types.
• Graphics::ColorUtils can also convert betweeb RGB and other color space types, and supports RGB from names in various color schemes.
• Acme::AutoColor provides subroutines corresponding to color names.

---

📦 SOURCE 📦

The development version is on github at https://github.com/robrwo/Graphics-ColorNames and may be cloned from git://github.com/robrwo/Graphics-ColorNames.git

The SourceForge project for this module at http://sourceforge.net/projects/colornames/ is no longer maintained. rip 💀

---

🐛 BUGS 🐛

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Graphics-ColorNames or by email to bug-Graphics-ColorNames@rt.cpan.org (mailto:bug-Graphics-ColorNames@rt.cpan.org).

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. help us help you bestie 🙏

---

👑 AUTHOR 👑

Robert Rothenberg <rrwo@cpan.org>

---

🫶 CONTRIBUTORS 🫶

• Alan D. Salewski <alans@cji.com>
• Steve Pomeroy <xavier@cpan.org>
• "chemboy" <chemboy@perlmonk.org>
• Magnus Cedergren <magnus@mbox604.swipnet.se>
• Gary Vollink <gary@vollink.com>
• Claus Färber <cfaerber@cpan.org>
• Andreas J. König <andk@cpan.org>
• Slaven Rezić <slaven@rezic.de>

the way they all showed up for this module... legends, every one of them 🌟

---

💅 COPYRIGHT AND LICENSE 💅

This software is Copyright (c) 2001-2019 by Robert Rothenberg.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)

---

okay that's the whole page babes, you made it to the end, so proud of you 🥹 this was documented with perl v5.38.2, dated 2024-02-21 — take care of her and she'll take care of your colors fr fr 💖✨🎀