Commit | Line | Data |
---|---|---|
522ce57f | 1 | Term::ANSIColor version 4.02 |
2d1e314f | 2 | (A simple ANSI text attribute control module) |
110e9fb0 | 3 | |
ba5532d7 CBW |
4 | This program is free software; you may redistribute it and/or modify it |
5 | under the same terms as Perl itself. Please see the section LICENSE | |
6 | below for more information. | |
110e9fb0 | 7 | |
c23d8173 RGS |
8 | BLURB |
9 | ||
ba5532d7 | 10 | Term::ANSIColor provides constants and simple functions for setting ANSI |
c23d8173 RGS |
11 | text attributes, most notably colors. It can be used to set the current |
12 | text attributes or to apply a set of attributes to a string and reset | |
ba5532d7 CBW |
13 | the current text attributes at the end of that string. Eight-color, |
14 | sixteen-color, and 256-color escape sequences are all supported. | |
c23d8173 RGS |
15 | |
16 | DESCRIPTION | |
110e9fb0 | 17 | |
ba5532d7 CBW |
18 | This Perl module is a simple and convenient interface to the ANSI |
19 | terminal escape sequences for color (from ECMA-48, also included in ISO | |
20 | 6429). The color sequences are provided in two forms, either as | |
21 | constants for each color or via a function that takes the names of | |
22 | colors and returns the appropriate escape codes or wraps them around the | |
23 | provided text. The non-color text style codes from ANSI X3.64 (bold, | |
24 | dark, underline, and reverse, for example), which were also included in | |
25 | ECMA-48 and ISO 6429, are also supported. Also supported are the | |
26 | extended colors used for sixteen-color and 256-color emulators. | |
27 | ||
28 | This module is very stable, and I've used it in a wide variety of | |
29 | applications. It has been included in the core Perl distribution | |
30 | starting with version 5.6.0, so you don't need to download and install | |
31 | it yourself unless you have an old version of Perl or need a newer | |
32 | version of the module than comes with your version of Perl. I continue | |
33 | to maintain it as a separate module, and the version included in Perl is | |
34 | resynced with mine before each release. | |
35 | ||
36 | The original module came out of a discussion in comp.lang.perl.misc and | |
37 | is a combination of two approaches, one with constants by Zenin and one | |
38 | with functions that I wrote. I offered to maintain a combined module | |
39 | that included both approaches. | |
2d1e314f | 40 | |
110e9fb0 JH |
41 | See the POD documentation for complete details, features, and usage. |
42 | ||
c23d8173 RGS |
43 | REQUIREMENTS |
44 | ||
45 | Term::ANSIColor is written in pure Perl and has no module dependencies | |
46 | that aren't found in Perl core. It should work with any version of Perl | |
ba5532d7 | 47 | after 5.6, although it hasn't been tested with old versions in some |
c23d8173 RGS |
48 | time. |
49 | ||
ba5532d7 CBW |
50 | In order to actually see color, you will need to use a terminal window |
51 | that supports the ANSI escape sequences for color. Any recent version | |
52 | of xterm, most xterm derivatives and replacements, and most telnet and | |
53 | ssh clients for Windows and Macintosh should work, as will the MacOS X | |
54 | Terminal application (although Terminal.app reportedly doesn't support | |
55 | 256 colors). The console windows for Windows NT and Windows 2000 will | |
56 | not work, as they do not even attempt to support ANSI X3.64. | |
57 | ||
58 | For a complete (to my current knowledge) compatibility list, see the | |
59 | Term::ANSIColor module documentation. If you have any additions to the | |
60 | table in the documentation, please send them to me. | |
61 | ||
62 | The test suite requires Perl and Test::More (part of Perl since 5.6.2). | |
63 | It also makes use of additional Perl modules for some tests. These | |
64 | tests will be skipped automatically if the modules aren't available. To | |
65 | run the full set of default tests, you will need the Perl modules: | |
66 | ||
67 | Perl::Critic | |
68 | Test::MinimumVersion | |
69 | Test::Pod | |
70 | Test::Pod::Coverage | |
71 | Test::Strict | |
72 | Test::Synopsis | |
73 | Test::Warn | |
74 | ||
75 | and their dependencies. These modules are all available from CPAN. | |
76 | ||
77 | Some parts of the test suite are suppressed by default because those | |
78 | tests are normally only useful for the maintainer. This includes tests | |
79 | of POD spelling and Perl coding style. To enable those tests, set the | |
80 | environment variable RRA_MAINTAINER_TESTS to a true value. For these | |
81 | tests, the additional Perl modules: | |
82 | ||
83 | Devel::Cover | |
84 | Test::Perl::Critic | |
85 | Test::Spelling | |
86 | ||
87 | and their dependencies as well as a spell-checking program (several are | |
88 | supported by Test::Spelling) are required. These modules are all | |
89 | available from CPAN. | |
c23d8173 | 90 | |
110e9fb0 JH |
91 | INSTALLATION |
92 | ||
c23d8173 | 93 | WARNING: Installation of this package will replace the Term::ANSIColor |
ba5532d7 CBW |
94 | that came with Perl. You may want to save a backup copy of the standard |
95 | version first. | |
c23d8173 | 96 | |
110e9fb0 JH |
97 | Follow the standard installation procedure for Perl modules, which is to |
98 | type the following commands: | |
99 | ||
2d1e314f JH |
100 | perl Makefile.PL |
101 | make | |
102 | make test | |
103 | make install | |
110e9fb0 JH |
104 | |
105 | You'll probably need to do the last as root. If instead you wish to | |
2d1e314f JH |
106 | install the module by hand, simply copy it into a directory named Term |
107 | in your Perl library directory. | |
110e9fb0 | 108 | |
ba5532d7 | 109 | SUPPORT |
c23d8173 RGS |
110 | |
111 | The Term::ANSIColor web page at: | |
112 | ||
113 | http://www.eyrie.org/~eagle/software/ansicolor/ | |
114 | ||
115 | will always have the current version of this package, the current | |
116 | documentation, and pointers to any additional resources. | |
117 | ||
ba5532d7 CBW |
118 | For bug tracking, this package uses the CPAN bug tracker at: |
119 | ||
522ce57f | 120 | https://rt.cpan.org/Public/Dist/Display.html?Name=Term-ANSIColor |
ba5532d7 CBW |
121 | |
122 | I welcome bug reports and patches for this package at rra@stanford.edu | |
522ce57f CBW |
123 | or via the CPAN bug tracker. However, please be aware that I tend to be |
124 | extremely busy and work projects often take priority. I'll save your | |
125 | mail and get to it as soon as I can, but it may take me a couple of | |
126 | months. | |
ba5532d7 CBW |
127 | |
128 | SOURCE REPOSITORY | |
129 | ||
c23d8173 RGS |
130 | Term::ANSIColor is maintained using Git. You can access the current |
131 | source by cloning the repository at: | |
132 | ||
133 | git://git.eyrie.org/perl/ansicolor.git | |
134 | ||
135 | or view the repository on the web at: | |
136 | ||
137 | http://git.eyrie.org/?p=perl/ansicolor.git | |
110e9fb0 | 138 | |
ba5532d7 CBW |
139 | When contributing modifications, patches (possibly generated by |
140 | git-format-patch) are preferred to Git pull requests. | |
00196a0f | 141 | |
110e9fb0 JH |
142 | THANKS |
143 | ||
144 | To Jon Lennox for looking at early versions of this module, providing | |
145 | feedback, and offering suggestions for improvement. | |
146 | ||
147 | To Jesse Taylor for writing the first significant script to use this | |
148 | module (colorized calsplit), thus offering innumerable opportunities to | |
149 | test and debug. | |
150 | ||
151 | To Jean Delvare for providing documentation of what the various | |
152 | attributes do on various different terminal emulators, and for noting | |
153 | that attribute 2 is dark. | |
154 | ||
155 | To Edward Avis for the implementation of uncolor. | |
156 | ||
157 | To Rani Pinchuk for the idea of ANSI_COLORS_DISABLED and an initial | |
158 | implementation. | |
159 | ||
2d1e314f JH |
160 | To ATricket for the information about what PuTTY, Windows telnet, and |
161 | OpenSSH under Cygwin support. | |
110e9fb0 | 162 | |
2e589669 RGS |
163 | To Richard Maus for pointing out DARK was missing from the exported |
164 | constants list and CYAN and WHITE were missing from the documentation. | |
165 | ||
92c7d2a2 RGS |
166 | To Autrijus Tang for noticing a problem with string comparisons in the |
167 | test suite. | |
168 | ||
169 | To Daniel Lindsley for the information about what Mac OS X Terminal | |
170 | supports. | |
171 | ||
ba5532d7 CBW |
172 | To Joe Smith for the original test files that exercise a wide variety of |
173 | VT100 escape sequences including the ECMA-48 color control codes. These | |
174 | have been replaced by an example script, but they were very useful. | |
51da1d85 RGS |
175 | |
176 | To James Bowlin for catching a bug in colored when $EACHLINE is set that | |
177 | caused it to not color lines consisting solely of 0. | |
178 | ||
cd07961b SP |
179 | To Helge Kreutzmann for pointing out the need for warnings in the |
180 | documentation about background colors that span newlines. | |
181 | ||
7cd34c57 RGS |
182 | To Baron Schwartz for pointing out that cyan and white were missing from |
183 | the documentation. | |
184 | ||
c23d8173 RGS |
185 | To Michael R. Wolf for pointing out that Wikipedia and the ECMA standard |
186 | use faint instead of dark as the name of attribute 2. | |
187 | ||
188 | To openmethods.com voice solutions for contributing PUSHCOLOR, POPCOLOR, | |
189 | and LOCALCOLOR support. | |
190 | ||
b5b25974 RGS |
191 | To Tim Bellinghausen for the AUTOLOAD taint fix for Perl 5.10. |
192 | ||
193 | To Paul Miller for the idea and initial implementation of colorstrip. | |
194 | ||
2c33c767 CBW |
195 | To Jakob Ilves for sixteen-color support and the initial documentation |
196 | of bright color issues. | |
197 | ||
5213914c CBW |
198 | To Revilo Reegiles for reporting problems with the colored function and |
199 | non-array references with stringification defined, and providing a test | |
200 | case. | |
201 | ||
00196a0f CBW |
202 | To Kent Fredric for the request for italic and the report of a terminal |
203 | emulator that supports it. | |
204 | ||
205 | To Simon Wistow for reporting that Term::ANSIColor was inadvertantly | |
206 | clobbering $@ when generating constant subs. | |
207 | ||
ba5532d7 CBW |
208 | To Kurt Starsinic for the initial implementation of 256-color support. |
209 | ||
210 | To Magnus Woldrich for Term::ExtendedColor and for research on which | |
211 | emulators support 256 colors. | |
212 | ||
213 | To Stephen Thirlwall for the initial implementation of custom color | |
214 | support. | |
215 | ||
216 | To BlueT - Matthew Lien - 練喆明 for quick testing of 4.00 and reporting | |
217 | a problem with skipping one of the tests. | |
218 | ||
522ce57f CBW |
219 | To David Cantrell for testing with Perl 5.6.2 and debugging why a test |
220 | case didn't work with its version of Exporter. | |
221 | ||
2d1e314f | 222 | To Larry Wall, as always, for Perl. |
ba5532d7 CBW |
223 | |
224 | LICENSE | |
225 | ||
226 | The Term-ANSIColor distribution as a whole is covered by the following | |
227 | copyright statement and license: | |
228 | ||
229 | Copyright 1996 Zenin | |
230 | Copyright 1996, 1997, 1998, 2000, 2001, 2002, 2005, 2006, 2008, 2009, | |
522ce57f | 231 | 2010, 2011, 2012, 2013 Russ Allbery <rra@stanford.edu> |
ba5532d7 CBW |
232 | Copyright 2012 Kurt Starsinic <kstarsinic@gmail.com> |
233 | ||
234 | This program is free software; you may redistribute it and/or modify | |
235 | it under the same terms as Perl itself. This means that you may | |
236 | choose between the two licenses that Perl is released under: the GNU | |
237 | GPL and the Artistic License. Please see your Perl distribution for | |
238 | the details and copies of the licenses. | |
239 | ||
240 | PUSH/POP support submitted 2007 by openmethods.com voice solutions | |
241 | ||
242 | All individual files without an explicit exception below are released | |
243 | under this license. Some files may have additional copyright holders as | |
244 | noted in those files. There is detailed information about the licensing | |
245 | of each file in the LICENSE file in this distribution. | |
246 | ||
247 | Some files in this distribution are individually released under | |
248 | different licenses, all of which are compatible with the above general | |
249 | package license but which may require preservation of additional | |
250 | notices. All required notices are preserved in the LICENSE file. |