1Graphics::ColorNames(3)User Contributed Perl DocumentatioGnraphics::ColorNames(3)
2
6 Graphics::ColorNames - defines RGB values for common color names
7
9 version v3.5.0
10
12 use Graphics::ColorNames;
13 use Graphics::ColorNames::WWW;
14 $pal = Graphics::ColorNames->new( qw[ X WWW ] );
16 $rgb = $pal->hex('green'); # returns '00ff00'
18 $rgb = $pal->hex('green', '0x'); # returns '0x00ff00'
19 $rgb = $pal->hex('green', '#'); # returns '#00ff00'
20 $rgb = $pal->rgb('green'); # returns '0,255,0'
22 @rgb = $pal->rgb('green'); # returns (0, 255, 0)
23
25 This module provides a common interface for obtaining the RGB values of
26 colors by standard names. The intention is to (1) provide a common
27 module that authors can use with other modules to specify colors by
28 name; and (2) free module authors from having to "re-invent the wheel"
29 whenever they decide to give the users the option of specifying a color
30 by name rather than RGB value.
31
33 "new"
34 The constructor is as follows:
35 my $pal = Graphics::ColorNames->new( @schemes );
37 where @schemes is an array of color schemes (palettes, dictionaries).
39 A valid color scheme may be the name of a color scheme (such as "X" or
41 a full module name such as "Graphics::ColorNames::X"), a reference to a
42 color scheme hash or subroutine, or to the path or open filehandle for
43 a rgb.txt file.
44 If none are specified, it uses the default "X" color scheme, which
46 corresponds to the X-Windows rgb.txt colors. For most purposes, this
47 is good enough. Since v3.2.0, it was updated to use the 2014-07-06
48 colors, so includes the standard CSS colors as well.
49 Other color schemes are available on CPAN, e.g.
51 Graphics::ColorNames::WWW.
52 Since version 2.1002, Color::Library dictionaries can be used as well:
54 my $pal = Graphics::ColorNames->new( 'Color::Library::Dictionary::HTML' );
56 "rgb"
58 @rgb = $pal->rgb($name);
59 $rgb = $pal->rgb($name, $separator);
61 If called in a list context, returns a triplet.
63 If called in a scalar context, returns a string separated by an
65 optional separator (which defauls to a comma). For example,
66 @rgb = $pal->rgb('blue'); # returns (0, 0, 255)
68 $rgb = $pal->rgb('blue', ','); # returns "0,0,255"
70 Unknown color names return empty lists or strings, depending on the
72 context.
73 Color names are case insensitive, and spaces or punctuation are
75 ignored. So "Alice Blue" returns the same value as "aliceblue", "ALICE-
76 BLUE" and "a*lICEbl-ue". (If you are using color names based on user
77 input, you should add additional validation of the color names.)
78 The value returned is in the six-digit hexidecimal format used in HTML
80 and CSS (without the initial '#'). To convert it to separate red,
81 green, and blue values (between 0 and 255), use the "hex2tuple"
82 function.
83 You may also specify an absolute filename as a color scheme, if the
85 file is in the same format as the standard rgb.txt file.
86 "hex"
88 $hex = $pal->hex($name, $prefix);
89 Returns a 6-digit hexidecimal RGB code for the color. If an optional
91 prefix is specified, it will prefix the code with that string. For
92 example,
93 $hex = $pal->hex('blue', '#'); # returns "#0000ff"
95 If the color does not exist, it will return an empty string.
97 A hexidecimal RGB value in the form of "#RRGGBB", "0xRRGGBB" or
99 "RRGGBB" will return itself:
100 $color = $pal->hex('#123abc'); # returns '123abc'
102 autoloaded color name methods
104 Autoloaded color name methods were removed in v3.4.0.
105 "load_scheme"
107 $pal->load_scheme( $scheme );
108 This dynamically loads a color scheme, which can be either a hash
110 reference or code reference.
111
113 "all_schemes"
114 my @schemes = all_schemes();
115 Returns a list of all available color schemes installed on the machine
117 in the Graphics::ColorNames namespace.
118 The order has no significance.
120 "hex2tuple"
122 Converts a hexidecimal string to a tuple.
123 "tuple2hex"
125 Converts a tuple to a hexidecimal string.
126
128 The standard interface (prior to version 0.40) was through a tied hash:
129 tie %pal, 'Graphics::ColorNames', qw[ X WWW ];
131 This interface is deprecated, and will be moved to a separate module in
133 the future.
134
136 You can add naming scheme files by creating a Perl module is the name
137 "Graphics::ColorNames::SCHEMENAME" which has a subroutine named
138 "NamesRgbTable" that returns a hash of color names and RGB values.
139 (Schemes with a different base namespace will require the fill
140 namespace to be given.)
141 The color names must be in all lower-case, and the RGB values must be
143 24-bit numbers containing the red, green, and blue values in most-
144 significant to least- significant byte order.
145 An example naming schema is below:
147 package Graphics::ColorNames::Metallic;
149 sub NamesRgbTable() {
151 use integer;
152 return {
153 copper => 0xb87333,
154 gold => 0xcd7f32,
155 silver => 0xe6e8fa,
156 };
157 }
158 You would use the above schema as follows:
160 tie %colors, 'Graphics::ColorNames', 'Metallic';
162 The behavior of specifying multiple keys with the same name is
164 undefined as to which one takes precedence.
165 As of version 2.10, case, spaces and punctuation are ignored in color
167 names. So a name like "Willy's Favorite Shade-of-Blue" is treated the
168 same as "willysfavoroteshadeofblue". (If your scheme does not include
169 duplicate entrieswith spaces and punctuation, then the minimum version
170 of Graphics::ColorNames should be 2.10 in your requirements.)
171 An example of an additional module is the Graphics::ColorNames::Mozilla
173 module.
174 Since version 1.03, "NamesRgbTable" may also return a code reference:
176 package Graphics::ColorNames::Orange;
178 sub NamesRgbTable() {
180 return sub {
181 my $name = shift;
182 return 0xffa500;
183 };
184 }
185 See Graphics::ColorNames::GrayScale for an example.
187
189 The following changes are planned in the future:
190 • The tied interface will be removed, but implemented in a separate
192 module for users that wish to use it.
193 • The namespace for color schemes will be moved to the
195 "Graphics::ColorNames::Schemes" but options will be added to use
196 the existing scheme.
197 This will allow modules to be named like
199 "Graphics::ColorNames::Tied" without being confused for color
200 schemes.
201 • This module will be rewritten to be a Moo-based class.
203
205 Color::Library provides an extensive library of color schemes. A
206 notable difference is that it supports more complex schemes which
207 contain additional information about individual colors and map multiple
208 colors to a single name.
209 Color::Rgb has a similar function to this module, but parses an rgb.txt
211 file.
212 Graphics::ColorObject can convert between RGB and other color space
214 types.
215 Graphics::ColorUtils can also convert betweeb RGB and other color space
217 types, and supports RGB from names in various color schemes.
218 Acme::AutoColor provides subroutines corresponding to color names.
220
222 The development version is on github at
223 <https://github.com/robrwo/Graphics-ColorNames> and may be cloned from
224 <git://github.com/robrwo/Graphics-ColorNames.git>
225 The SourceForge project for this module at
227 <http://sourceforge.net/projects/colornames/> is no longer maintained.
228
230 Please report any bugs or feature requests on the bugtracker website
231 <https://rt.cpan.org/Public/Dist/Display.html?Name=Graphics-ColorNames>
232 or by email to bug-Graphics-ColorNames@rt.cpan.org <mailto:bug-
233 Graphics-ColorNames@rt.cpan.org>.
234 When submitting a bug or request, please include a test-file or a patch
236 to an existing test-file that illustrates the bug or desired feature.
237
239 Robert Rothenberg <rrwo@cpan.org>
240
242 • Alan D. Salewski <alans@cji.com>
243 • Steve Pomeroy <xavier@cpan.org>
245 • "chemboy" <chemboy@perlmonk.org>
247 • Magnus Cedergren <magnus@mbox604.swipnet.se>
249 • Gary Vollink <gary@vollink.com>
251 • Claus Färber <cfaerber@cpan.org>
253 • Andreas J. König <andk@cpan.org>
255 • Slaven Rezić <slaven@rezic.de>
257
259 This software is Copyright (c) 2001-2019 by Robert Rothenberg.
260 This is free software, licensed under:
262 The Artistic License 2.0 (GPL Compatible)
264perl v5.38.0 2023-07-20 Graphics::ColorNames(3)