1Term::Chrome(3pm) User Contributed Perl Documentation Term::Chrome(3pm)
2
3
4
6 Term::Chrome - DSL for colors and other terminal chrome
7
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
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
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
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
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
194 See the warnings about "${}" and "&{}" above.
195
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
205 Comments on each modules are opinions of the author.
206
207 • Term::ANSIColor: the same basic features (and the others should not
208 be in Term::ANSIColor itself but in an extension), but with an
209 awful API I could never even consider to use while keeping my
210 sanity.
211
212 • Term::ScreenColor
213
214 • PerlIO::via::ANSIColor
215
216 • AngelPS1 or <https://github.com/dolmen/angel-PS1>: "The Angel's
217 Prompt" is the project for which "Term::Chrome" has been built.
218 AngelPS1::Compiler, the "angel-PS1" compiler has special support
219 for "Term::Chrome" values.
220
222 Did you know that chartreuse is one of the favorite colors of Larry
223 Wall?
224
226 Olivier Mengue <dolmen@cpan.org>
227
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.34.0 2022-01-21 Term::Chrome(3pm)