Debian Codegraph @

README

raw
1 NAME
2 Term::ExtendedColor - Color screen output using 256 colors
3
4 SYNOPSIS
5 use Term::ExtendedColor qw(:all);
6
7 # Or use the 'attributes' tag to only import the functions for setting
8 # attributes.
9 # This will import the following functions:
10
11 # fg(), bg(), bold(), underline(), inverse(), italic(), clear()
12 use Term::ExtendedColor ':attributes';
13
14 ## Foreground colors
15
16 my $red_text = fg('red2', 'this is in red');
17 my $spring = fg('springgreen3', 'this is green');
18
19 ## Background colors
20
21 print bg('red5', "Default foreground text on dark red background"), "\n";
22 my $red_on_green = fg('red3', bg('green12', 'Red text on green background'));
23 print "$red_on_green\n";
24
25 ## Fall-through attributes
26
27 Term::ExtendedColor::autoreset(0);
28 my $bold = fg('bold', 'This is bold');
29 my $red = fg('red2', 'This is red... and bold');
30 my $green = bg('green28', 'This is bold red on green background');
31
32 # Make sure to clear all attributes when autoreset turned OFF,
33 # or else the users shell will be messed up
34
35 my $clear = clear();
36 print "$bold\n";
37 print "$red\n";
38 print "$green $clear\n";
39
40 ## Non-color attributes
41
42 # Turn on autoreset again
43 Term::ExtendedColor::autoreset(1);
44
45 for(qw(italic underline blink reverse bold)) {
46 print fg($_, $_), "\n";
47 }
48
49 # For convenience
50
51 my $bolded = bold("Bold text!");
52 my $italic = italic("Text in italics!");
53
54 ## Remove all attributes from input data
55 my @colored;
56 push(@colored, fg('bold', fg('red2', 'Bold and red')));
57 push(@colored, fg('green13', fg('italic', 'Green, italic')));
58
59 print "$_\n" for @colored;
60 print "$_\n" for uncolor(@colored);
61
62 DESCRIPTION
63 Term::ExtendedColor provides functions for sending so called extended
64 escape sequences to the terminal. This ought to be used with a 256-color
65 compatible terminal; see the NOTES section for a matrix of terminal
66 emulators currently supporting this.
67
68 EXPORTS
69 None by default.
70
71 Two tags are provided for convience:
72
73 # Import all functions
74 use Term::ExtendedColor qw(:all);
75
76 # Import functions for setting attributes
77 # fg(), bg(), bold(), italic(), underline(), inverse(), clear()
78 use Term::ExtendedColor qw(:attributes);
79
80 FUNCTIONS
81 fg($color, $string)
82 my $green = fg('green2', 'green foreground');
83 my @blue = fg('blue4', ['takes arrayrefs as well']);
84
85 my $x_color = fg('mediumorchid1', 'Using mappings from the X11 rgb.txt');
86
87 my $arbitary_color = fg(4, 'This is colored in the fifth ANSI color');
88
89 my $raw_seq = fg('38;5;197;48;5;53;1;3;4;5;7', 'this works too');
90
91 Set foreground colors and attributes.
92
93 See "COLORS AND ATTRIBUTES" for valid first arguments. Additionally,
94 colors can be specified using their index value:
95
96 my $yellow = fg(220, 'Yellow');
97
98 If the internal $AUTORESET variable is non-zero (default), every element
99 in the list of strings will be wrapped in escape sequences in such a way
100 that the requested attributes will be set before the string and reset to
101 defaults after the string.
102
103 Fall-through attributes can be enabled by setting $AUTORESET to a false
104 value.
105
106 Term::ExtendedColor::autoreset( 0 );
107 my $red = fg('red1', 'Red');
108 my $green = fg('green1', 'Green');
109
110 print "Text after $red is red until $green\n";
111 print "Text is still green, ", bold('and now bold as well!');
112
113 # If you exit now without resetting the colors and attributes, chances are
114 # your prompt will be messed up.
115
116 clear(); # All back to normal
117
118 If an invalid attribute is passed, the original data will be returned
119 unmodified.
120
121 If no attribute is passed, thrown an exception.
122
123 bg($color, $string)
124 my $green_bg = bg('green4', 'green background');
125 my @blue_bg = bg('blue6', ['blue background']);
126
127 Like "fg()", but sets background colors.
128
129 uncolor($string) | uncolour($string)
130 my $stripped = uncolor($colored_data);
131 my @no_color = uncolor(\@colored);
132 my @no_color = uncolor(@colored);
133
134 Remove all attribute and color escape sequences from the input.
135
136 See uncolor for a command-line utility using this function.
137
138 get_colors() | get_colours()
139 my $colors = get_colors();
140
141 Returns a hash reference with all available attributes and colors.
142
143 clear()
144 When called in scalar context, returns the escape sequence that resets
145 all attributes to their defaults.
146
147 When called in void context, prints it directly.
148
149 autoreset()
150 Turn autoreset on/off. Enabled by default.
151
152 Term::ExtendedColor::autoreset( 0 ); # Turn off autoreset
153
154 bold(\@data)
155 Convenience function that might be used in place of "fg('bold',
156 \@data)";
157
158 When called without arguments, returns a a string that turns off the
159 bold attribute.
160
161 italic(\@data)
162 Convenience function that might be used in place of "fg('italic',
163 \@data)";
164
165 When called without arguments, returns a a string that turns off the
166 italics attribute.
167
168 underline(\@data)
169 Convenience function that might be used in place of "fg('underline',
170 \@data)";
171
172 When called without arguments, returns a a string that turns off the
173 underline attribute.
174
175 inverse(\@data)
176 Reverse video / inverse. Convenience function that might be used in
177 place of "fg('inverse', \@data)";
178
179 When called without arguments, returns a a string that turns off the
180 inverse attribute.
181
182 NOTES
183 The codes generated by this module complies to the extension of the ANSI
184 colors standard first implemented in xterm in 1999. The first 16 color
185 indexes (0 - 15) is the regular ANSI colors, while index 16 - 255 is the
186 extension. Not all terminal emulators support this extension, though
187 I've had a hard time finding one that doesn't. :)
188
189 Terminal 256 colors
190 ----------------------
191 aterm no
192 eterm yes
193 gnome-terminal yes
194 konsole yes
195 lxterminal yes
196 mrxvt yes
197 roxterm yes
198 rxvt no
199 rxvt-unicode yes *
200 sakura yes
201 terminal yes
202 terminator yes
203 vte yes
204 xterm yes
205 iTerm2 yes
206 Terminal.app no
207
208 GNU Screen yes
209 tmux yes
210 TTY/VC no
211
212 * Previously needed a patch. Full support was added in version 9.09.
213
214 There's no way to give these extended colors meaningful names.
215
216 Our first thought was to map them against some standard color names,
217 like those in the HTML 4.0 specification or the SVG one. They didn't
218 match.
219
220 Therefore, they are named by their base color (red, green, magenta) plus
221 index; The first index (always 1) is the brightest shade of that
222 particular color, while the last index is the darkest.
223
224 It's also possible to use some X color names, as defined in "rgb.txt".
225 Do note that the color values do not match exactly; it's just an
226 approximation.
227
228 A full list of available colors can be retrieved with "get_colors()".
229 See "COLORS AND ATTRIBUTES" for full list. All mapped colors can also be
230 retrieved programmatically with "get_colors()".
231
232 COLORS AND ATTRIBUTES
233 Attributes
234 reset, clear, normal reset all attributes
235 bold, bright bold or bright, depending on implementation
236 faint decreased intensity (not widely supported)
237 italic, cursive italic or cursive
238 underline, underscore underline
239 blink slow blink
240 blink_ms rapid blink (only supported in MS DOS)
241 reverse, inverse, negative reverse video
242 conceal conceal, or hide (not widely supported)
243
244 Standard color map
245 FIRST LAST
246
247 red1 red5
248 blue1 blue17
249 cyan1 cyan24
250 gray1 gray24
251 green1 green28
252 orange1 orange5
253 purple1 purple30
254 yellow1 yellow18
255 magenta1 magenta26
256
257 X color names
258 aquamarine1
259 aquamarine3
260 blueviolet
261 cadetblue1
262 cadetblue2
263 chartreuse1
264 chartreuse2
265 chartreuse3
266 chartreuse4
267 cornflowerblue
268 cornsilk1
269 darkblue
270 darkcyan
271 darkgoldenrod
272 darkgreen
273 darkkhaki
274 darkmagenta1
275 darkmagenta2
276 darkolivegreen1
277 darkolivegreen2
278 darkolivegreen3
279 darkolivegreen4
280 darkolivegreen5
281 darkorange3
282 darkorange4
283 darkorange1
284 darkred1
285 darkred2
286 darkseagreen1
287 darkseagreen2
288 darkseagreen3
289 darkseagreen4
290 darkslategray1
291 darkslategray2
292 darkslategray3
293 darkturquoise
294 darkviolet
295 deeppink1
296 deeppink2
297 deeppink3
298 deeppink4
299 deepskyblue1
300 deepskyblue2
301 deepskyblue3
302 deepskyblue4
303 deepskyblue4
304 dodgerblue1
305 dodgerblue2
306 dodgerblue3
307 gold1
308 gold3
309 greenyellow
310 grey0
311 grey100
312 grey11
313 grey15
314 grey19
315 grey23
316 grey27
317 grey30
318 grey3
319 grey35
320 grey37
321 grey39
322 grey42
323 grey46
324 grey50
325 grey53
326 grey54
327 grey58
328 grey62
329 grey63
330 grey66
331 grey69
332 grey70
333 grey74
334 grey7
335 grey78
336 grey82
337 grey84
338 grey85
339 grey89
340 grey93
341 honeydew2
342 hotpink2
343 hotpink3
344 hotpink
345 indianred1
346 indianred
347 khaki1
348 khaki3
349 lightcoral
350 lightcyan1
351 lightcyan3
352 lightgoldenrod1
353 lightgoldenrod2
354 lightgoldenrod3
355 lightgreen
356 lightpink1
357 lightpink3
358 lightpink4
359 lightsalmon1
360 lightsalmon3
361 lightsalmon3
362 lightseagreen
363 lightskyblue1
364 lightskyblue3
365 lightskyblue3
366 lightslateblue
367 lightslategrey
368 lightsteelblue1
369 lightsteelblue3
370 lightsteelblue
371 lightyellow3
372 mediumorchid1
373 mediumorchid3
374 mediumorchid
375 mediumpurple1
376 mediumpurple2
377 mediumpurple3
378 mediumpurple4
379 mediumpurple
380 mediumspringgreen
381 mediumturquoise
382 mediumvioletred
383 mistyrose1
384 mistyrose3
385 navajowhite1
386 navajowhite3
387 navyblue
388 orangered1
389 orchid1
390 orchid2
391 orchid
392 palegreen1
393 palegreen3
394 paleturquoise1
395 paleturquoise4
396 palevioletred1
397 pink1
398 pink3
399 plum1
400 plum2
401 plum3
402 plum4
403 purple
404 rosybrown
405 royalblue1
406 salmon1
407 sandybrown
408 seagreen1
409 seagreen2
410 seagreen3
411 skyblue1
412 skyblue2
413 skyblue3
414 slateblue1
415 slateblue3
416 springgreen1
417 springgreen2
418 springgreen3
419 springgreen4
420 steelblue1
421 steelblue3
422 steelblue
423 tan
424 thistle1
425 thistle3
426 turquoise2
427 turquoise4
428 violet
429 wheat1
430 wheat4
431
432 In addition, it's also possible to pass raw color;attr strings like so:
433
434 my $foo = fg('48;5;89;38;5;197;1;3;4;7', 'foo');
435
436 Even though the fg() function is used, we set the following attributes:
437
438 background => 89
439 foreground => 197
440 bold
441 italic
442 underline
443 reverse
444
445 SEE ALSO
446 Term::ExtendedColor::Xresources Term::ExtendedColor::TTY Term::ANSIColor
447
448 AUTHOR
449 Magnus Woldrich
450 CPAN ID: WOLDRICH
451 [email protected]
452 http://github.com/trapd00r
453 http://japh.se
454
455 CONTRIBUTORS
456 Varadinsky <https://github.com/Varadinsky>
457
458 COPYRIGHT
459 Copyright 2010, 2011, 2018, 2019- the Term::ExtendedColor "AUTHOR" and
460 "CONTRIBUTORS" as listed above.
461
462 LICENSE
463 This library is free software; you may redistribute it and/or modify it
464 under the same terms as Perl itself.
465