Term::Chrome(3pm)

1Term::Chrome(3pm)     User Contributed Perl Documentation    Term::Chrome(3pm)
2
3
4

NAME

6       Term::Chrome - DSL for colors and other terminal chrome
7

SYNOPSIS

9           use Term::Chrome qw<Red Blue Bold Reset Underline Green color>;
10
11           # Base color constant and attribute
12           say Red, 'red text', Reset;
13
14           # Composition, using operator overloading
15           say Red/Blue+Bold, 'red on blue', Reset;
16
17           # Undo
18           say Bold, 'bold', !Bold, 'not bold';
19
20           # Extended xterm-256 colors
21           say color(125) + Underline, 'Purple', Reset;
22
23           # Define your own constants
24           use constant Pink => color 213;
25
26           # Use ${} around Chrome expression inside strings
27           say "normal ${ Red+Bold } RED ${ +Reset } normal";
28
29           # Extract components
30           say( (Red/Blue)->bg, "blue text", (Green+Reset)->flags );
31
32       Chromizer: get a closure that applies given chrome before, and undo
33       after the argument.
34
35           # Get an efficient chromizer
36           my $boldifier = \&{ +Bold };
37           # Use the chromizer
38           say $boldifier->("bold text");
39           # Same as:
40           say Bold, "bold text", !Bold;
41
42           # Short lived chromizers using color literals:
43           say(&{+Red}('red'));
44           say(&{ Red/Blue + Bold }('red on blue'));
45           # Same, but requires perl 5.21.4+
46           #say(( Red/Blue + Bold )->('red on blue'));
47

DESCRIPTION

49       "Term::Chrome" is a domain-specific language (DSL) for terminal
50       decoration (colors and other attributes).
51
52       In the current implementation stringification to ANSI sequences for
53       "xterm" and "xterm-256" is hard-coded (which means it doesn't use the
54       terminfo(5) database), but this gives optimized (short) strings.
55
56       Colors and attributes are exposed as objects that have overloading for
57       arithmetic operators.
58

EXPORTS

60   Functions
61       "color(0-255)"
62
63       Build a Term::Chrome object with the given color number. You can use
64       this constructor to create your own set of color constants.
65
66       For example, color(0) gives the same result as "Black" (but not the
67       same object).
68
69   Colors
70       Each of these function return a Chrome object.
71
72       •   "Black": "color 0"
73
74       •   "Red": "color 1"
75
76       •   "Green": "color 2"
77
78       •   "Yellow": "color 3"
79
80       •   "Blue": "color 4"
81
82       •   "Magenta": "color 5"
83
84       •   "Cyan": "color 6"
85
86       •   "White": "color 7"
87
88   Decoration flags
89       The exact rendering of each flag is dependent on how the terminal
90       implements them. For example "Underline" and "Blink" may do nothing.
91
92       •   "Bold"
93
94       •   "Underline"
95
96       •   "Blink"
97
98       •   "Reverse"
99
100   Special flags
101       •   "Reset": reset all colors and flags
102
103       •   "ResetFlags": reset (undo) all chrome flags (Bold, Underline,
104           Blink, Reverse)
105
106       •   "ResetFg": reset (undo) foreground color
107
108       •   "ResetBg": reset (undo) background color
109

METHODS

111       Here are the methods on "Term::Chrome" objects:
112
113       "fg"
114           Extract the Chrome object of just the foreground color. Maybe
115           "undef".
116
117       "bg"
118           Extract the Chrome object of the just background color. Maybe
119           "undef".
120
121       "flags"
122           Extract a Chrome object of just the decoration flags. Maybe
123           "undef".
124

OVERLOADED OPERATORS

126       "/" (mnemonic: "over")
127           Combine a foreground color (on the left) with a background color.
128
129           Example:
130
131               my $red_on_black = Red / Black;
132
133       "+" Add decoration flags (on the right) to colors (on the left).
134
135           Example:
136
137               my $bold_red = Red + Bold;
138
139       "!" (negation)
140           Returns a chrome which is the reverse of chrome to which negation
141           is applied.
142
143               my $reset_foreground = ! Red;
144               my $reset_colors = ! (Red / Black);
145
146           The reverse of "Reset", "ResetFg", "ResetBg", "ResetFlags" is
147           nothing.
148
149       "" (stringification)
150           Transform the object into a string of ANSI sequences. This is
151           particularly useful to directly use a Chrome object in a double
152           quoted string.
153
154       "${}" (scalar dereference)
155           Same result as "" (stringification). This operator is overloaded
156           because it is convenient to interpolate Chrome expressions in
157           double-quoted strings.
158
159           Examples:
160
161               say "normal ${ +Red } red ${ +Reset }";
162               say "normal ${ Red + Bold } red ${ +Reset }";
163
164           Note that you must force expression parsing context when a Chrome
165           constant is used alone inside "${ }": "${ +Red }" or "${ (Red) }"
166           or "${ Red() }".  "use strict 'vars';" will detect those cases, but
167           you may miss them in one-liners.
168
169       "&{}" (code dereference, or codulation)
170           Wrap some text with the given chrome and "Reset".
171
172           Example:
173
174               say Red->("red text");
175               # Same result as:
176               say Red, "red text", Reset;
177
178           Unfortunately perl had a bug (perl RT#122607
179           <https://rt.perl.org/Ticket/Display.html?id=122607>) that makes
180           this feature not much usable in practice when applied to constants.
181           That bug is fixed in perl 5.21.4+.  On perl < 5.21.4 you have to
182           wrap the chrome constant in a "do {}" or use "&{}()":
183
184               say do{ Red }->("red text");
185               say &{ +Red }("red text");
186
187           Codulation can also be used to extract a colorizer sub that will be
188           more efficient if you use it multiple times:
189
190               my $redifier = \&{ Red };
191               say $redifier->("red text");
192

BUGS

194       See the warnings about "${}" and "&{}" above.
195

REFERENCES

197       •   ISO 6429 / ECMA 48:
198           https://www.ecma-international.org/publications/files/ECMA-ST/Ecma-048.pdf
199           (reference for SGR is at page 61, numbered 75 in PDF)
200
201       •   XTerm Control Sequences:
202           http://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Functions-using-CSI-_-ordered-by-the-final-character_s_
203

TRIVIA

222       Did you know that chartreuse is one of the favorite colors of Larry
223       Wall?
224

AUTHOR

226       Olivier Mengue <dolmen@cpan.org>
227

COPYRIGHT & LICENSE

229       Copyright X 2013-2018 Olivier Mengue.
230
231       This library is free software; you can redistribute it and/or modify it
232       under the same terms as Perl 5 itself.
233
234
235
236perl v5.32.1                      2021-01-27                 Term::Chrome(3pm)