File Coverage

lib/Term/Chrome.pod
Criterion Covered Total %
statement 9 9 100.0
branch n/a
condition n/a
subroutine 3 3 100.0
pod n/a
total 12 12 100.0


line stmt bran cond sub pod time code
1             =encoding UTF-8
2              
3             =head1 NAME
4              
5             Term::Chrome - DSL for colors and other terminal chrome
6              
7             =head1 SYNOPSIS
8              
9             use Term::Chrome qw;
10             use feature qw; # Just for this example
11              
12             # Base color constant and attribute
13             say Red, 'red text', Reset;
14              
15             # Composition, using operator overloading
16             say Red/Blue+Bold, 'red on blue', Reset;
17              
18             # Extended xterm-256 colors
19             say color(125) + Underline, 'Purple', Reset;
20              
21             # Define your own constants
22             use constant Pink => color 213;
23              
24             # Use ${} around Chrome expression inside strings
25             say "normal ${ Red+Bold } RED ${ +Reset } normal";
26              
27             # Extract components
28             say( (Red/Blue)->bg, "blue text", (Green+Reset)->flags );
29              
30 1     1   7605 # Get an efficient chromizer sub (applies given chrome before, and
  1         3  
  1         87  
31 1     1   6 # Reset after the argument)
  1         1  
  1         169  
32             my $boldifier = \&{ +Bold };
33             # Use the chromizer
34             say $boldifier->("bold text");
35              
36             =head1 DESCRIPTION
37              
38             C is a domain-specific language (DSL) for terminal decoration
39             (colors and other attributes).
40              
41             In the current implementation stringification to ANSI sequences for C
42             and C is hard-coded (which means it doesn't use the L
43 1     1   5 database), but this gives optimized (short) strings.
  1         1  
  1         3  
44              
45             Colors and attributes are exposed as objects that have overloading for
46             arithmetic operators.
47              
48             =head1 EXPORTS
49              
50             =head2 Functions
51              
52             C)>
53              
54             Build a L object with the given color number. You can use this
55             constructor to create your own set of color constants.
56              
57             For example, C gives the same result as C (but not the same
58             object).
59              
60             =head2 Colors
61              
62             Each of these function return a Chrome object.
63              
64             =over 4
65              
66             =item *
67              
68             C: C
69              
70             =item *
71              
72             C: C
73              
74             =item *
75              
76             C: C
77              
78             =item *
79              
80             C: C
81              
82             =item *
83              
84             C: C
85              
86             =item *
87              
88             C: C
89              
90             =item *
91              
92             C: C
93              
94             =item *
95              
96             C: C
97              
98             =cut
99              
100             # Secret: Chartreuse
101              
102             =back
103              
104             =head2 Decoration flags
105              
106             The exact rendering of each flag is dependent on how the terminal implements
107             them. For example C and C may do nothing.
108              
109             =over 4
110              
111             =item *
112              
113             C
114              
115             =item *
116              
117             C
118              
119             =item *
120              
121             C
122              
123             =item *
124              
125             C
126              
127             =back
128              
129             =head2 Special flags
130              
131             =over 4
132              
133             =item *
134              
135             C : reset all colors and flags
136              
137             =back
138              
139             =head1 METHODS
140              
141             Here are the methods on C objects:
142              
143             =over 4
144              
145             =item C
146              
147             Extract the Chrome object of just the foreground color. Maybe C.
148              
149             =item C
150              
151             Extract the Chrome object of the just background color. Maybe C.
152              
153             =item C
154              
155             Extract a Chrome object of just the decoration flags. Maybe C.
156              
157             =back
158              
159             =head1 OVERLOADED OPERATORS
160              
161             =over 4
162              
163             =item C (mnemonic: "over")
164              
165             Conmbine a foreground color (on the left) with a background color.
166              
167             =item C<+>
168              
169             Add decoration flags (on the right) to colors (on the left).
170              
171             =item C<""> (stringification)
172              
173             Transform the object into a sting of ANSI sequences. This is
174             particularly useful to directly use a Chrome object in a double quoted string.
175              
176             =item C<${}> (scalar dereference)
177              
178             Same result as C<""> (stringification). This operator is overloaded because
179             it is convenient to interpolate Chrome expressions in double-quoted strings.
180              
181             Example:
182              
183             say "normal ${ Red } red ${ Reset }";
184              
185             =item C<&{}> (code dereference, or "codulation")
186              
187             Wrap some text with the given chrome and C.
188              
189             Example:
190              
191             say Red->("red text");
192             # Same result as:
193             say Red, "red text", Reset;
194              
195             Unfortunately perl had a bug
196             (L) that makes this feature not much usable in practice when applied to constants. That bug
197             is fixed in perl 5.21.4+.
198              
199             This can also be used to extract a colorizer sub that will be more efficient
200             if you reuse it:
201              
202             my $redifier = \&{ Red };
203             say $redifier->("red text");
204              
205             =back
206              
207             =head1 BUGS
208              
209             See the warning about C<&{}> above.
210              
211             =head1 SEE ALSO
212              
213             Comments on each modules are opinions of the author.
214              
215             =over 4
216              
217             =item *
218              
219             L: the same basic features (and the others should not be in
220             Term::ANSIColor itself but in an extension), but with an awful API I could never
221             even consider to use while keeping my sanity.
222              
223             =item *
224              
225             L
226              
227             =item *
228              
229             L
230              
231             =item *
232              
233             L or L: "The Angel's Prompt" is
234             the project for which C has been built. L,
235             the C compiler has special support for C values.
236              
237             =back
238              
239             =head1 TRIVIA
240              
241             Did you know that I is one of the favorite color of Larry Wall?
242              
243             =head1 AUTHOR
244              
245             Olivier MenguE, L
246              
247             =head1 COPYRIGHT & LICENSE
248              
249             Copyright E 2013-2014 Olivier MenguE.
250              
251             This library is free software; you can redistribute it and/or modify it under
252             the same terms as Perl 5 itself.
253              
254             =cut
255             # vim:set et ts=8 sw=4 sts=4: