1Graphics::ColorNames(3)User Contributed Perl DocumentatioGnraphics::ColorNames(3)
2
3
4

NAME

6       Graphics::ColorNames - defines RGB values for common color names
7

VERSION

9       version v3.5.0
10

SYNOPSIS

12         use Graphics::ColorNames;
13         use Graphics::ColorNames::WWW;
14
15         $pal = Graphics::ColorNames->new( qw[ X WWW ] );
16
17         $rgb = $pal->hex('green');          # returns '00ff00'
18         $rgb = $pal->hex('green', '0x');    # returns '0x00ff00'
19         $rgb = $pal->hex('green', '#');     # returns '#00ff00'
20
21         $rgb = $pal->rgb('green');          # returns '0,255,0'
22         @rgb = $pal->rgb('green');          # returns (0, 255, 0)
23

DESCRIPTION

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

METHODS

33   "new"
34       The constructor is as follows:
35
36         my $pal = Graphics::ColorNames->new( @schemes );
37
38       where @schemes is an array of color schemes (palettes, dictionaries).
39
40       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
45       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
50       Other color schemes are available on CPAN, e.g.
51       Graphics::ColorNames::WWW.
52
53       Since version 2.1002, Color::Library dictionaries can be used as well:
54
55         my $pal = Graphics::ColorNames->new( 'Color::Library::Dictionary::HTML' );
56
57   "rgb"
58         @rgb = $pal->rgb($name);
59
60         $rgb = $pal->rgb($name, $separator);
61
62       If called in a list context, returns a triplet.
63
64       If called in a scalar context, returns a string separated by an
65       optional separator (which defauls to a comma).  For example,
66
67         @rgb = $pal->rgb('blue');      # returns (0, 0, 255)
68
69         $rgb = $pal->rgb('blue', ','); # returns "0,0,255"
70
71       Unknown color names return empty lists or strings, depending on the
72       context.
73
74       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
79       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
84       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
87   "hex"
88         $hex = $pal->hex($name, $prefix);
89
90       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
94         $hex = $pal->hex('blue', '#'); # returns "#0000ff"
95
96       If the color does not exist, it will return an empty string.
97
98       A hexidecimal RGB value in the form of "#RRGGBB", "0xRRGGBB" or
99       "RRGGBB" will return itself:
100
101         $color = $pal->hex('#123abc');         # returns '123abc'
102
103   autoloaded color name methods
104       Autoloaded color name methods were removed in v3.4.0.
105
106   "load_scheme"
107         $pal->load_scheme( $scheme );
108
109       This dynamically loads a color scheme, which can be either a hash
110       reference or code reference.
111

EXPORTS

113   "all_schemes"
114         my @schemes = all_schemes();
115
116       Returns a list of all available color schemes installed on the machine
117       in the Graphics::ColorNames namespace.
118
119       The order has no significance.
120
121   "hex2tuple"
122       Converts a hexidecimal string to a tuple.
123
124   "tuple2hex"
125       Converts a tuple to a hexidecimal string.
126

TIED INTERFACE

128       The standard interface (prior to version 0.40) was through a tied hash:
129
130         tie %pal, 'Graphics::ColorNames', qw[ X WWW ];
131
132       This interface is deprecated, and will be moved to a separate module in
133       the future.
134

CUSTOM COLOR SCHEMES

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
142       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
146       An example naming schema is below:
147
148         package Graphics::ColorNames::Metallic;
149
150         sub NamesRgbTable() {
151           use integer;
152           return {
153             copper => 0xb87333,
154             gold   => 0xcd7f32,
155             silver => 0xe6e8fa,
156           };
157         }
158
159       You would use the above schema as follows:
160
161         tie %colors, 'Graphics::ColorNames', 'Metallic';
162
163       The behavior of specifying multiple keys with the same name is
164       undefined as to which one takes precedence.
165
166       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
172       An example of an additional module is the Graphics::ColorNames::Mozilla
173       module.
174
175       Since version 1.03, "NamesRgbTable" may also return a code reference:
176
177         package Graphics::ColorNames::Orange;
178
179         sub NamesRgbTable() {
180           return sub {
181             my $name = shift;
182             return 0xffa500;
183           };
184         }
185
186       See Graphics::ColorNames::GrayScale for an example.
187

ROADMAP

189       The following changes are planned in the future:
190
191       •   The tied interface will be removed, but implemented in a separate
192           module for users that wish to use it.
193
194       •   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
198           This will allow modules to be named like
199           "Graphics::ColorNames::Tied" without being confused for color
200           schemes.
201
202       •   This module will be rewritten to be a Moo-based class.
203

SEE ALSO

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
210       Color::Rgb has a similar function to this module, but parses an rgb.txt
211       file.
212
213       Graphics::ColorObject can convert between RGB and other color space
214       types.
215
216       Graphics::ColorUtils can also convert betweeb RGB and other color space
217       types, and supports RGB from names in various color schemes.
218
219       Acme::AutoColor provides subroutines corresponding to color names.
220

SOURCE

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
226       The SourceForge project for this module at
227       <http://sourceforge.net/projects/colornames/> is no longer maintained.
228

BUGS

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
235       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

AUTHOR

239       Robert Rothenberg <rrwo@cpan.org>
240

CONTRIBUTORS

242       •   Alan D. Salewski <alans@cji.com>
243
244       •   Steve Pomeroy <xavier@cpan.org>
245
246       •   "chemboy" <chemboy@perlmonk.org>
247
248       •   Magnus Cedergren <magnus@mbox604.swipnet.se>
249
250       •   Gary Vollink <gary@vollink.com>
251
252       •   Claus Färber <cfaerber@cpan.org>
253
254       •   Andreas J. König <andk@cpan.org>
255
256       •   Slaven Rezić <slaven@rezic.de>
257
259       This software is Copyright (c) 2001-2019 by Robert Rothenberg.
260
261       This is free software, licensed under:
262
263         The Artistic License 2.0 (GPL Compatible)
264
265
266
267perl v5.38.0                      2023-07-20           Graphics::ColorNames(3)
Impressum