diff options
author | Nicholas Clark <nick@ccl4.org> | 2009-09-26 16:59:53 +0100 |
---|---|---|
committer | Nicholas Clark <nick@ccl4.org> | 2009-09-26 17:51:17 +0100 |
commit | 0b29b2838a20fccb78eeb72804f1dde93533707a (patch) | |
tree | 76578122b6602853399e43d973fe74530bad2005 /cpan/Term-ANSIColor | |
parent | f4e6b6923ba5d1ff0ca1ddc96955a42cab82e1e4 (diff) | |
download | perl-0b29b2838a20fccb78eeb72804f1dde93533707a.tar.gz |
Move Term::ANSIColor from ext/ to cpan/
Diffstat (limited to 'cpan/Term-ANSIColor')
-rw-r--r-- | cpan/Term-ANSIColor/ANSIColor.pm | 609 | ||||
-rw-r--r-- | cpan/Term-ANSIColor/ChangeLog | 305 | ||||
-rw-r--r-- | cpan/Term-ANSIColor/README | 155 | ||||
-rw-r--r-- | cpan/Term-ANSIColor/t/basic.t | 133 |
4 files changed, 1202 insertions, 0 deletions
diff --git a/cpan/Term-ANSIColor/ANSIColor.pm b/cpan/Term-ANSIColor/ANSIColor.pm new file mode 100644 index 0000000000..1ee7a1ef7a --- /dev/null +++ b/cpan/Term-ANSIColor/ANSIColor.pm @@ -0,0 +1,609 @@ +# Term::ANSIColor -- Color screen output using ANSI escape sequences. +# +# Copyright 1996, 1997, 1998, 2000, 2001, 2002, 2005, 2006, 2008, 2009 +# Russ Allbery <rra@stanford.edu> and Zenin +# PUSH/POP support submitted 2007 by openmethods.com voice solutions +# +# This program is free software; you may redistribute it and/or modify it +# under the same terms as Perl itself. +# +# Ah, September, when the sysadmins turn colors and fall off the trees.... +# -- Dave Van Domelen + +############################################################################## +# Modules and declarations +############################################################################## + +package Term::ANSIColor; +require 5.001; + +$VERSION = '2.02'; + +use strict; +use vars qw($AUTOLOAD $AUTOLOCAL $AUTORESET @COLORLIST @COLORSTACK $EACHLINE + @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS $VERSION %ATTRIBUTES + %ATTRIBUTES_R); + +use Exporter (); +BEGIN { + @COLORLIST = qw(CLEAR RESET BOLD DARK FAINT UNDERLINE UNDERSCORE BLINK + REVERSE CONCEALED BLACK RED GREEN YELLOW BLUE MAGENTA + CYAN WHITE ON_BLACK ON_RED ON_GREEN ON_YELLOW ON_BLUE + ON_MAGENTA ON_CYAN ON_WHITE); + @ISA = qw(Exporter); + @EXPORT = qw(color colored); + @EXPORT_OK = qw(uncolor colorstrip colorvalid); + %EXPORT_TAGS = (constants => \@COLORLIST, + pushpop => [ @COLORLIST, + qw(PUSHCOLOR POPCOLOR LOCALCOLOR) ]); + Exporter::export_ok_tags ('pushpop'); +} + +############################################################################## +# Internal data structures +############################################################################## + +%ATTRIBUTES = ('clear' => 0, + 'reset' => 0, + 'bold' => 1, + 'dark' => 2, + 'faint' => 2, + 'underline' => 4, + 'underscore' => 4, + 'blink' => 5, + 'reverse' => 7, + 'concealed' => 8, + + 'black' => 30, 'on_black' => 40, + 'red' => 31, 'on_red' => 41, + 'green' => 32, 'on_green' => 42, + 'yellow' => 33, 'on_yellow' => 43, + 'blue' => 34, 'on_blue' => 44, + 'magenta' => 35, 'on_magenta' => 45, + 'cyan' => 36, 'on_cyan' => 46, + 'white' => 37, 'on_white' => 47); + +# Reverse lookup. Alphabetically first name for a sequence is preferred. +for (reverse sort keys %ATTRIBUTES) { + $ATTRIBUTES_R{$ATTRIBUTES{$_}} = $_; +} + +############################################################################## +# Implementation (constant form) +############################################################################## + +# Time to have fun! We now want to define the constant subs, which are named +# the same as the attributes above but in all caps. Each constant sub needs +# to act differently depending on whether $AUTORESET is set. Without +# autoreset: +# +# BLUE "text\n" ==> "\e[34mtext\n" +# +# If $AUTORESET is set, we should instead get: +# +# BLUE "text\n" ==> "\e[34mtext\n\e[0m" +# +# The sub also needs to handle the case where it has no arguments correctly. +# Maintaining all of this as separate subs would be a major nightmare, as well +# as duplicate the %ATTRIBUTES hash, so instead we define an AUTOLOAD sub to +# define the constant subs on demand. To do that, we check the name of the +# called sub against the list of attributes, and if it's an all-caps version +# of one of them, we define the sub on the fly and then run it. +# +# If the environment variable ANSI_COLORS_DISABLED is set, just return the +# arguments without adding any escape sequences. This is to make it easier to +# write scripts that also work on systems without any ANSI support, like +# Windows consoles. +sub AUTOLOAD { + if (defined $ENV{ANSI_COLORS_DISABLED}) { + return join ('', @_); + } + if ($AUTOLOAD =~ /^([\w:]*::([A-Z_]+))$/ and defined $ATTRIBUTES{lc $2}) { + $AUTOLOAD = $1; + my $attr = "\e[" . $ATTRIBUTES{lc $2} . 'm'; + eval qq { + sub $AUTOLOAD { + if (\$AUTORESET && \@_) { + return '$attr' . join ('', \@_) . "\e[0m"; + } elsif (\$AUTOLOCAL && \@_) { + return PUSHCOLOR ('$attr') . join ('', \@_) . POPCOLOR; + } else { + return '$attr' . join ('', \@_); + } + } + }; + goto &$AUTOLOAD; + } else { + require Carp; + Carp::croak ("undefined subroutine &$AUTOLOAD called"); + } +} + +# Append a new color to the top of the color stack and return the top of +# the stack. +sub PUSHCOLOR { + my ($text) = @_; + my ($color) = ($text =~ m/^((?:\e\[[\d;]+m)+)/); + if (@COLORSTACK) { + $color = $COLORSTACK[-1] . $color; + } + push (@COLORSTACK, $color); + return $text; +} + +# Pop the color stack and return the new top of the stack (or reset, if +# the stack is empty). +sub POPCOLOR { + pop @COLORSTACK; + if (@COLORSTACK) { + return $COLORSTACK[-1] . join ('', @_); + } else { + return RESET (@_); + } +} + +# Surround arguments with a push and a pop. +sub LOCALCOLOR { + return PUSHCOLOR (join ('', @_)) . POPCOLOR (); +} + +############################################################################## +# Implementation (attribute string form) +############################################################################## + +# Return the escape code for a given set of color attributes. +sub color { + return '' if defined $ENV{ANSI_COLORS_DISABLED}; + my @codes = map { split } @_; + my $attribute = ''; + foreach (@codes) { + $_ = lc $_; + unless (defined $ATTRIBUTES{$_}) { + require Carp; + Carp::croak ("Invalid attribute name $_"); + } + $attribute .= $ATTRIBUTES{$_} . ';'; + } + chop $attribute; + return ($attribute ne '') ? "\e[${attribute}m" : undef; +} + +# Return a list of named color attributes for a given set of escape codes. +# Escape sequences can be given with or without enclosing "\e[" and "m". The +# empty escape sequence '' or "\e[m" gives an empty list of attrs. +sub uncolor { + my (@nums, @result); + for (@_) { + my $escape = $_; + $escape =~ s/^\e\[//; + $escape =~ s/m$//; + unless ($escape =~ /^((?:\d+;)*\d*)$/) { + require Carp; + Carp::croak ("Bad escape sequence $escape"); + } + push (@nums, split (/;/, $1)); + } + for (@nums) { + $_ += 0; # Strip leading zeroes + my $name = $ATTRIBUTES_R{$_}; + if (!defined $name) { + require Carp; + Carp::croak ("No name for escape sequence $_" ); + } + push (@result, $name); + } + return @result; +} + +# Given a string and a set of attributes, returns the string surrounded by +# escape codes to set those attributes and then clear them at the end of the +# string. The attributes can be given either as an array ref as the first +# argument or as a list as the second and subsequent arguments. If $EACHLINE +# is set, insert a reset before each occurrence of the string $EACHLINE and +# the starting attribute code after the string $EACHLINE, so that no attribute +# crosses line delimiters (this is often desirable if the output is to be +# piped to a pager or some other program). +sub colored { + my ($string, @codes); + if (ref $_[0]) { + @codes = @{+shift}; + $string = join ('', @_); + } else { + $string = shift; + @codes = @_; + } + return $string if defined $ENV{ANSI_COLORS_DISABLED}; + if (defined $EACHLINE) { + my $attr = color (@codes); + return join '', + map { ($_ ne $EACHLINE) ? $attr . $_ . "\e[0m" : $_ } + grep { length ($_) > 0 } + split (/(\Q$EACHLINE\E)/, $string); + } else { + return color (@codes) . $string . "\e[0m"; + } +} + +# Given a string, strip the ANSI color codes out of that string and return the +# result. This removes only ANSI color codes, not movement codes and other +# escape sequences. +sub colorstrip { + my (@string) = @_; + for my $string (@string) { + $string =~ s/\e\[[\d;]*m//g; + } + return wantarray ? @string : join ('', @string); +} + +# Given a list of color attributes (arguments for color, for instance), return +# true if they're all valid or false if any of them are invalid. +sub colorvalid { + my @codes = map { split } @_; + for (@codes) { + unless (defined $ATTRIBUTES{lc $_}) { + return; + } + } + return 1; +} + +############################################################################## +# Module return value and documentation +############################################################################## + +# Ensure we evaluate to true. +1; +__END__ + +=head1 NAME + +Term::ANSIColor - Color screen output using ANSI escape sequences + +=for stopwords +cyan colorize namespace runtime TMTOWTDI cmd.exe 4nt.exe command.com NT +ESC Delvare SSH OpenSSH aixterm ECMA-048 Fraktur overlining Zenin +reimplemented Allbery PUSHCOLOR POPCOLOR LOCALCOLOR openmethods.com + +=head1 SYNOPSIS + + use Term::ANSIColor; + print color 'bold blue'; + print "This text is bold blue.\n"; + print color 'reset'; + print "This text is normal.\n"; + print colored ("Yellow on magenta.", 'yellow on_magenta'), "\n"; + print "This text is normal.\n"; + print colored ['yellow on_magenta'], 'Yellow on magenta.'; + print "\n"; + + use Term::ANSIColor qw(uncolor); + print uncolor ('01;31'), "\n"; + + use Term::ANSIColor qw(colorstrip); + print colorstrip '\e[1mThis is bold\e[0m', "\n"; + + use Term::ANSIColor qw(colorvalid); + my $valid = colorvalid ('blue bold', 'on_magenta'); + print "Color string is ", $valid ? "valid\n" : "invalid\n"; + + use Term::ANSIColor qw(:constants); + print BOLD, BLUE, "This text is in bold blue.\n", RESET; + + use Term::ANSIColor qw(:constants); + { + local $Term::ANSIColor::AUTORESET = 1; + print BOLD BLUE "This text is in bold blue.\n"; + print "This text is normal.\n"; + } + + use Term::ANSIColor qw(:pushpop); + print PUSHCOLOR RED ON_GREEN "This text is red on green.\n"; + print PUSHCOLOR BLUE "This text is blue on green.\n"; + print RESET BLUE "This text is just blue.\n"; + print POPCOLOR "Back to red on green.\n"; + print LOCALCOLOR GREEN ON_BLUE "This text is green on blue.\n"; + print "This text is red on green.\n"; + { + local $Term::ANSIColor::AUTOLOCAL = 1; + print ON_BLUE "This text is red on blue.\n"; + print "This text is red on green.\n"; + } + print POPCOLOR "Back to whatever we started as.\n"; + +=head1 DESCRIPTION + +This module has two interfaces, one through color() and colored() and the +other through constants. It also offers the utility functions uncolor(), +colorstrip(), and colorvalid(), which have to be explicitly imported to be +used (see L</SYNOPSIS>). + +=head2 Function Interface + +color() takes any number of strings as arguments and considers them to be +space-separated lists of attributes. It then forms and returns the escape +sequence to set those attributes. It doesn't print it out, just returns +it, so you'll have to print it yourself if you want to (this is so that +you can save it as a string, pass it to something else, send it to a file +handle, or do anything else with it that you might care to). color() +throws an exception if given an invalid attribute, so you can also use it +to check attribute names for validity (see L</EXAMPLES>). + +uncolor() performs the opposite translation, turning escape sequences +into a list of strings. + +colorstrip() removes all color escape sequences from the provided strings, +returning the modified strings separately in array context or joined +together in scalar context. Its arguments are not modified. + +colorvalid() takes attribute strings the same as color() and returns true +if all attributes are known and false otherwise. + +The recognized non-color attributes are clear, reset, bold, dark, faint, +underline, underscore, blink, reverse, and concealed. Clear and reset +(reset to default attributes), dark and faint (dim and saturated), and +underline and underscore are equivalent, so use whichever is the most +intuitive to you. The recognized foreground color attributes are black, +red, green, yellow, blue, magenta, cyan, and white. The recognized +background color attributes are on_black, on_red, on_green, on_yellow, +on_blue, on_magenta, on_cyan, and on_white. Case is not significant. + +Note that not all attributes are supported by all terminal types, and some +terminals may not support any of these sequences. Dark and faint, blink, +and concealed in particular are frequently not implemented. + +Attributes, once set, last until they are unset (by sending the attribute +C<clear> or C<reset>). Be careful to do this, or otherwise your attribute +will last after your script is done running, and people get very annoyed +at having their prompt and typing changed to weird colors. + +As an aid to help with this, colored() takes a scalar as the first +argument and any number of attribute strings as the second argument and +returns the scalar wrapped in escape codes so that the attributes will be +set as requested before the string and reset to normal after the string. +Alternately, you can pass a reference to an array as the first argument, +and then the contents of that array will be taken as attributes and color +codes and the remainder of the arguments as text to colorize. + +Normally, colored() just puts attribute codes at the beginning and end of +the string, but if you set $Term::ANSIColor::EACHLINE to some string, that +string will be considered the line delimiter and the attribute will be set +at the beginning of each line of the passed string and reset at the end of +each line. This is often desirable if the output contains newlines and +you're using background colors, since a background color that persists +across a newline is often interpreted by the terminal as providing the +default background color for the next line. Programs like pagers can also +be confused by attributes that span lines. Normally you'll want to set +$Term::ANSIColor::EACHLINE to C<"\n"> to use this feature. + +=head2 Constant Interface + +Alternately, if you import C<:constants>, you can use the constants CLEAR, +RESET, BOLD, DARK, FAINT, UNDERLINE, UNDERSCORE, BLINK, REVERSE, +CONCEALED, BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, +ON_BLACK, ON_RED, ON_GREEN, ON_YELLOW, ON_BLUE, ON_MAGENTA, ON_CYAN, and +ON_WHITE directly. These are the same as color('attribute') and can be +used if you prefer typing: + + print BOLD BLUE ON_WHITE "Text", RESET, "\n"; + +to + + print colored ("Text", 'bold blue on_white'), "\n"; + +(Note that the newline is kept separate to avoid confusing the terminal as +described above since a background color is being used.) + +When using the constants, if you don't want to have to remember to add the +C<, RESET> at the end of each print line, you can set +$Term::ANSIColor::AUTORESET to a true value. Then, the display mode will +automatically be reset if there is no comma after the constant. In other +words, with that variable set: + + print BOLD BLUE "Text\n"; + +will reset the display mode afterward, whereas: + + print BOLD, BLUE, "Text\n"; + +will not. If you are using background colors, you will probably want to +print the newline with a separate print statement to avoid confusing the +terminal. + +The subroutine interface has the advantage over the constants interface in +that only two subroutines are exported into your namespace, versus +twenty-two in the constants interface. On the flip side, the constants +interface has the advantage of better compile time error checking, since +misspelled names of colors or attributes in calls to color() and colored() +won't be caught until runtime whereas misspelled names of constants will +be caught at compile time. So, pollute your namespace with almost two +dozen subroutines that you may not even use that often, or risk a silly +bug by mistyping an attribute. Your choice, TMTOWTDI after all. + +=head2 The Color Stack + +As of Term::ANSIColor 2.0, you can import C<:pushpop> and maintain a stack +of colors using PUSHCOLOR, POPCOLOR, and LOCALCOLOR. PUSHCOLOR takes the +attribute string that starts its argument and pushes it onto a stack of +attributes. POPCOLOR removes the top of the stack and restores the +previous attributes set by the argument of a prior PUSHCOLOR. LOCALCOLOR +surrounds its argument in a PUSHCOLOR and POPCOLOR so that the color +resets afterward. + +When using PUSHCOLOR, POPCOLOR, and LOCALCOLOR, it's particularly +important to not put commas between the constants. + + print PUSHCOLOR BLUE "Text\n"; + +will correctly push BLUE onto the top of the stack. + + print PUSHCOLOR, BLUE, "Text\n"; # wrong! + +will not, and a subsequent pop won't restore the correct attributes. +PUSHCOLOR pushes the attributes set by its argument, which is normally a +string of color constants. It can't ask the terminal what the current +attributes are. + +=head1 DIAGNOSTICS + +=over 4 + +=item Bad escape sequence %s + +(F) You passed an invalid ANSI escape sequence to uncolor(). + +=item Bareword "%s" not allowed while "strict subs" in use + +(F) You probably mistyped a constant color name such as: + + $Foobar = FOOBAR . "This line should be blue\n"; + +or: + + @Foobar = FOOBAR, "This line should be blue\n"; + +This will only show up under use strict (another good reason to run under +use strict). + +=item Invalid attribute name %s + +(F) You passed an invalid attribute name to either color() or colored(). + +=item Name "%s" used only once: possible typo + +(W) You probably mistyped a constant color name such as: + + print FOOBAR "This text is color FOOBAR\n"; + +It's probably better to always use commas after constant names in order to +force the next error. + +=item No comma allowed after filehandle + +(F) You probably mistyped a constant color name such as: + + print FOOBAR, "This text is color FOOBAR\n"; + +Generating this fatal compile error is one of the main advantages of using +the constants interface, since you'll immediately know if you mistype a +color name. + +=item No name for escape sequence %s + +(F) The ANSI escape sequence passed to uncolor() contains escapes which +aren't recognized and can't be translated to names. + +=back + +=head1 ENVIRONMENT + +=over 4 + +=item ANSI_COLORS_DISABLED + +If this environment variable is set, all of the functions defined by this +module (color(), colored(), and all of the constants not previously used +in the program) will not output any escape sequences and instead will just +return the empty string or pass through the original text as appropriate. +This is intended to support easy use of scripts using this module on +platforms that don't support ANSI escape sequences. + +For it to have its proper effect, this environment variable must be set +before any color constants are used in the program. + +=back + +=head1 RESTRICTIONS + +It would be nice if one could leave off the commas around the constants +entirely and just say: + + print BOLD BLUE ON_WHITE "Text\n" RESET; + +but the syntax of Perl doesn't allow this. You need a comma after the +string. (Of course, you may consider it a bug that commas between all the +constants aren't required, in which case you may feel free to insert +commas unless you're using $Term::ANSIColor::AUTORESET or +PUSHCOLOR/POPCOLOR.) + +For easier debugging, you may prefer to always use the commas when not +setting $Term::ANSIColor::AUTORESET or PUSHCOLOR/POPCOLOR so that you'll +get a fatal compile error rather than a warning. + +=head1 NOTES + +The codes generated by this module are standard terminal control codes, +complying with ECMA-048 and ISO 6429 (generally referred to as "ANSI +color" for the color codes). The non-color control codes (bold, dark, +italic, underline, and reverse) are part of the earlier ANSI X3.64 +standard for control sequences for video terminals and peripherals. + +Note that not all displays are ISO 6429-compliant, or even X3.64-compliant +(or are even attempting to be so). This module will not work as expected +on displays that do not honor these escape sequences, such as cmd.exe, +4nt.exe, and command.com under either Windows NT or Windows 2000. They +may just be ignored, or they may display as an ESC character followed by +some apparent garbage. + +Jean Delvare provided the following table of different common terminal +emulators and their support for the various attributes and others have +helped me flesh it out: + + clear bold faint under blink reverse conceal + ------------------------------------------------------------------------ + xterm yes yes no yes yes yes yes + linux yes yes yes bold yes yes no + rxvt yes yes no yes bold/black yes no + dtterm yes yes yes yes reverse yes yes + teraterm yes reverse no yes rev/red yes no + aixterm kinda normal no yes no yes yes + PuTTY yes color no yes no yes no + Windows yes no no no no yes no + Cygwin SSH yes yes no color color color yes + Mac Terminal yes yes no yes yes yes yes + +Windows is Windows telnet, Cygwin SSH is the OpenSSH implementation under +Cygwin on Windows NT, and Mac Terminal is the Terminal application in Mac +OS X. Where the entry is other than yes or no, that emulator displays the +given attribute as something else instead. Note that on an aixterm, clear +doesn't reset colors; you have to explicitly set the colors back to what +you want. More entries in this table are welcome. + +Note that codes 3 (italic), 6 (rapid blink), and 9 (strike-through) are +specified in ANSI X3.64 and ECMA-048 but are not commonly supported by +most displays and emulators and therefore aren't supported by this module +at the present time. ECMA-048 also specifies a large number of other +attributes, including a sequence of attributes for font changes, Fraktur +characters, double-underlining, framing, circling, and overlining. As +none of these attributes are widely supported or useful, they also aren't +currently supported by this module. + +=head1 SEE ALSO + +ECMA-048 is available on-line (at least at the time of this writing) at +L<http://www.ecma-international.org/publications/standards/ECMA-048.HTM>. + +ISO 6429 is available from ISO for a charge; the author of this module +does not own a copy of it. Since the source material for ISO 6429 was +ECMA-048 and the latter is available for free, there seems little reason +to obtain the ISO standard. + +The current version of this module is always available from its web site +at L<http://www.eyrie.org/~eagle/software/ansicolor/>. It is also part of +the Perl core distribution as of 5.6.0. + +=head1 AUTHORS + +Original idea (using constants) by Zenin, reimplemented using subs by Russ +Allbery <rra@stanford.edu>, and then combined with the original idea by +Russ with input from Zenin. Russ Allbery now maintains this module. + +=head1 COPYRIGHT AND LICENSE + +Copyright 1996, 1997, 1998, 2000, 2001, 2002, 2005, 2006, 2008, 2009 Russ +Allbery <rra@stanford.edu> and Zenin. This program is free software; you +may redistribute it and/or modify it under the same terms as Perl itself. + +PUSHCOLOR, POPCOLOR, and LOCALCOLOR were contributed by openmethods.com +voice solutions. + +=cut diff --git a/cpan/Term-ANSIColor/ChangeLog b/cpan/Term-ANSIColor/ChangeLog new file mode 100644 index 0000000000..9888ad1afb --- /dev/null +++ b/cpan/Term-ANSIColor/ChangeLog @@ -0,0 +1,305 @@ +2009-08-30 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: Version 2.02 released. + + * ANSIColor.pm: Update compatibility matrix to reflect that xterm + now supports blink. + + * ANSIColor.pm (colorvalid): New function to check whether an + attribute is known. + * t/basic.t: Test colorvalid. + +2009-07-04 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: Add an example of checking color attributes by + catching exceptions from color() to the documentation. + + * ANSIColor.pm: Add FAINT as a synonym for DARK and export it when + constants are requested. + * t/basic.t: Test faint and FAINT as a synonym for dark/DARK. + + * ANSIColor.pm: Version 2.01 released. + + * t/basic.t: Test error handling in color, colored, and uncolor. + + * ANSIColor.pm (uncolor): When reporting errors for bad escape + sequences, don't include the leading \e[ or trailing m in the + error message. + + * ANSIColor.pm: Add section headings to the DESCRIPTION section of + the module since it's getting rather long. + (colorstrip): New function to remove ANSI color codes from + strings. Thanks, Paul Miller. + * t/basic.t: New tests for colorstrip. + + * ANSIColor.pm (AUTOLOAD): Untaint $AUTOLOAD, required by Perl + 5.10 when running in taint mode. Thanks, Tim Bellinghausen. + * t/basic.t: Two new tests for AUTOLOAD error handling. Enable + warnings and taint mode. + +2009-02-28 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: Version 2.00 released. + + * Makefile.PL: Add LICENSE to the distribution metadata for Perl + 5.10 and later. + + * ANSIColor.pm: Add explicit return statements instead of relying + on the implicit return of the last expression. Use all caps for + all global variables. + + * ANSIColor.pm: Add the new functions to a :pushpop export tag. + (PUSHCOLOR): New function that stores in an internal stack the + attributes that are being set. + (POPCOLOR): New function that pops the attributes being set and + sets the attributes previously found on the stack. + (LOCALCOLOR): New function that surrounds its argument in + PUSHCOLOR and POPCOLOR. + (AUTOLOAD): If $AUTOLOCAL is set, surround all color constants + with an implicit LOCALCOLOR. + * t/basic.t: Test PUSHCOLOR, POPCOLOR, and LOCALCOLOR. + + * t/pod-spelling.t: Rewrite to use Test::More. Support and prefer + aspell. + + * ANSIColor.pm: Fix additional spelling errors and rewrap the POD + documentation to a 74-character margin. + + * t/basic.t: Rewrite to use Test::More. + * t/pod.t: Likewise. + + * ANSIColor.pm (AUTOLOAD): If ANSI_COLORS_DISABLED is set, return + the stringified arguments rather than creating a sub. This allows + colors to work later if ANSI_COLORS_DISABLED is unset rather than + making its effects permanent. It also avoids adding a reset + escape sequence when $AUTORESET and ANSI_COLORS_DISABLED are both + set. + +2008-09-14 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: Add faint as a synonym for dark and improve the + documentation of text attributes. + + * t/pod-spelling.t: New check to spell-check POD documentation + using ispell with Pod::Spell. + * ANSIColor.pm: Fix spelling and markup errors in documentation + and add stop-words where appropriate. + +2007-04-22 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: Version 1.12 released. + +2007-03-23 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: Use the right syntax for internal POD links. + Thanks, Rafael Garcia-Suarez. + +2007-02-10 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: Add cyan and white to the list of supported + attributes. Not sure how I managed to omit them before. + +2006-07-12 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: Version 1.11 released. + +2006-06-22 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: Clarify in the documentation the behavior of + terminals when background colors are set across newlines, and + rewrite some of the examples to avoid doing things that confuse + the terminal. Fix a couple of spelling errors. + + * test.pl: Moved to... + * t/basic.t: ...here. + * t/pod.t: New test for POD validity. + +2005-08-21 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: Version 1.10 released. + + * ANSIColor.pm (colored): Fix the $EACHLINE support to work + properly with a line consisting solely of "0". Remove Zenin's + now-defunct e-mail address from the documentation. + * test.pl: Test 0 and the empty string in combination with + $EACHLINE. + + * tests/ansicolor: Add terminal test file from Joe Smith. + * tests/vt100-torture: Likewise. + * tests/README: Add an explanation of the test files. + +2004-12-03 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: Version 1.09 released. + + * ANSIColor.pm: Add compatibility information for Mac OS X + Terminal from Daniel Lindsley. + +2004-02-20 Russ Allbery <rra@stanford.edu> + + * test.pl: Always use eq, not ==, for string comparisons. + +2004-02-19 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: Version 1.08 released. + + * ANSIColor.pm: Add DARK to %EXPORT_TAGS and add CYAN and WHITE to + the list of documented constants. + * test.pl: Add a test for DARK. Redo the leading comment. + +2003-03-25 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: Version 1.07 released. + + * ANSIColor.pm: Add PuTTY, Windows telnet, and Cygwin OpenSSH + information to the terminal emulators table, and update the URL to + the ECMA standard. + +2002-12-09 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: Version 1.06 released to synchronize the version + on CPAN with the version in Perl core. + + * ANSIColor.pm: Fix typo in L<> link in documentation. + +2002-06-28 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: Version 1.05 released. + + * ANSIColor.pm: Update the formatting style, add a pointer to the + module web site, use L<> for URLs, and use naked <>s where + permissible rather than E<lt> and E<gt>. Renamed LICENSE to + COPYRIGHT AND LICENSE. + +2002-02-14 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: Added a mention of the specific Windows consoles + that don't work with this module. + +2001-07-10 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: Version 1.04 released. + + * ANSIColor.pm: Add documentation, examples, and diagnostics for + uncolor. Document ANSI_COLORS_DISABLED. Add information about + the relevant standards for these escape sequences and the + additional ones that aren't supported by this module. Add a + pointer to the relevant standards. Add a LICENSE section. Update + Zenin's e-mail address. + + * ANSIColor.pm (AUTOLOAD): Add support for ANSI_COLORS_DISABLED. + (color): Likewise. + (colored): Likewise. + * test.pl: Add tests for ANSI_COLORS_DISABLED. + + * ANSIColor.pm (uncolor): New function. + * test.pl: Add a test for it. + +2000-08-06 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: Version 1.03 released. + + * Makefile.PL: Install in the Perl library directory for Perl + versions >= 5.6.0. + + * test.pl: Added a new test for the array reference syntax for + colored. + + * ANSIColor.pm: Changed $VERSION to a static string. Added dark + to the attributes. Updated the documentation to include a table + of supported attributes on different terminal emulators, to add + dark, to document the new optional way to call colored, and to + mark the diagnostics as fatal errors or warnings. + (colored): Allow the attributes to be passed as an initial array + reference as well as a final list, and for that calling syntax + take the rest of the arguments as text to be colored. + +1998-11-27 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: Version 1.02 released. + + * Makefile.PL: Added a 5.005-only section giving ABSTRACT and + AUTHOR settings for generating a PPD to go with a binary + distribution or the Perl Resource Kits. + +1998-04-14 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: croak() instead of die() on AUTOLOAD failure to + get the right error text, fixed a bunch of typos in the + documentation, added a quote. + +1997-12-10 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: Version 1.01 released. + + * ANSIColor.pm (color): Carp::croak() isn't predeclared, so it + needs parens around its argument. This bug will only show up in + versions of Perl >5.004_04 since up until then strict.pm imports + Carp which predeclares the function. + +1997-11-29 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: Version 1.00 released. + + * Makefile.PL: Now gets version information from the module, has + the correct rules to build a distribution. + + * test.pl: Comments trimmed, minor test modifications. + + * ANSIColor.pm: Changed my e-mail address, fixed to deal correctly + with trailing delimiters when EACHLINE is being used, die() + changed to croak() if the caller uses an invalid attribute name, + getting $VERSION from RCS updated to my current method, source + detabified. + + * test.pl: Added test for EACHLINE with trailing delimiters. + +1997-02-17 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: Version 0.9 released. + + * ANSIColor.pm: Changed the runtime error message to start with an + uppercase letter, reworked the documentation considerably + including adding more comparison between the two interfaces, + fixing some formatting bugs, fixing a typo, adding more + diagnostics, and generally being more verbose. + +1997-01-08 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: Version 0.8 released. + + * test.pl: Fixed the test numbering in the BEGIN block. + + * test.pl: Reformatted and commented to fit my programming style. + + * ANSIColor.pm: Changed the method by which $VERSION is set so + that it will always have two digits after the decimal point. + + * test.pl: New file. + + * ANSIColor.pm: [Revision 0.7] Changed the codes so that reset is + always consistantly "\e[0m". + + * ANSIColor.pm: [Revision 0.6] Added $EACHLINE and support to + colored() for it so that attributes can be reset around every + newline (or other line delimiter -- we're flexible). Documented + this as well. + + * ANSIColor.pm: [Revision 0.5] Changed implementation of the + constants to autoloaded subs, added the $AUTORESET variable for + use with the constants, and documented this. + +1996-12-07 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: [Revision 0.4] Added POD documentation. + + * ANSIColor.pm: [Revision 0.3] Added constant forms, modified to + allow a space-separated string of attributes to be passed to + color() and colored(), added Zenin to the credits. + +1996-12-04 Russ Allbery <rra@stanford.edu> + + * ANSIColor.pm: [Revision 0.2] Changed return syntax and check for + the null attribute string. + + * ANSIColor.pm: New file. diff --git a/cpan/Term-ANSIColor/README b/cpan/Term-ANSIColor/README new file mode 100644 index 0000000000..94391c006f --- /dev/null +++ b/cpan/Term-ANSIColor/README @@ -0,0 +1,155 @@ + Term::ANSIColor version 2.02 + (A simple ANSI text attribute control module) + + Copyright 1996, 1997, 1998, 2000, 2001, 2002, 2005, 2006, 2007, 2009 + Russ Allbery <rra@stanford.edu> and Zenin. This program is free + software; you may redistribute it and/or modify it under the same terms + as Perl itself. + + I welcome bug reports and patches for this package at rra@stanford.edu. + However, please be aware that I tend to be extremely busy and to get a + lot of mail. I'll save your mail and get to it as soon as I can, but + depending on how busy I am it may take me a couple of months. + +BLURB + + Term::ANSIColor provides constants and simple functions for sending ANSI + text attributes, most notably colors. It can be used to set the current + text attributes or to apply a set of attributes to a string and reset + the current text attributes at the end of that string. + +DESCRIPTION + + This module grew out of a thread on comp.lang.perl.misc where several of + us were throwing around different ways to print colored text from Perl + scripts and Zenin posted his old library to do that. I (Russ) disagreed + with the implementation and offered my own (the color() and colored() + functions implemented in this package), Zenin convinced me that the + constants had their place as well, and we started figuring out the best + ways of implementing both. + + While ANSI color escape codes are fairly simple, it can be hard to + remember the codes for all of the attributes and the code resulting from + hard-coding them into your script is definitely difficult to read. This + module is designed to fix those problems, as well as provide a + convenient interface to do a few things for you automatically (like + resetting attributes after the text you print out so that you don't + accidentally leave attributes set). + + Despite its name, this module can also handle non-color ANSI text + attributes (bold, underline, reverse video, and blink). It uses either + of two interfaces, one of which uses "constants" for each different + attribute and the other of which uses two subs which take strings of + attributes as arguments. + + See the POD documentation for complete details, features, and usage. + + This module is distributed as part of the Perl core distribution as of + Perl 5.6.0. You only need to install this module if you want a newer + version than came with Perl or if you have an old version of Perl. + +REQUIREMENTS + + Term::ANSIColor is written in pure Perl and has no module dependencies + that aren't found in Perl core. It should work with any version of Perl + after 5.001, although it hasn't been tested with old versions in some + time. + + The test suite requires the Test::More module. To check the POD + documentation, Test::Pod is also required. To check spelling, + Pod::Spell and either aspell or ispell with the american dictionary are + also required. The user's path is searched for aspell or ispell and + aspell is preferred. Spelling tests are disabled by default since + spelling dictionaries differ too much between systems. To enable those + tests, set RRA_MAINTAINER_TESTS to a true value. + +INSTALLATION + + WARNING: Installation of this package will replace the Term::ANSIColor + that came with Perl for Perl 5.6.0 or later. Term::ANSIColor that came + with Perl. You may want to save a backup copy of the standard version + first. + + Follow the standard installation procedure for Perl modules, which is to + type the following commands: + + perl Makefile.PL + make + make test + make install + + You'll probably need to do the last as root. If instead you wish to + install the module by hand, simply copy it into a directory named Term + in your Perl library directory. + +HOMEPAGE AND SOURCE REPOSITORY + + The Term::ANSIColor web page at: + + http://www.eyrie.org/~eagle/software/ansicolor/ + + will always have the current version of this package, the current + documentation, and pointers to any additional resources. + + Term::ANSIColor is maintained using Git. You can access the current + source by cloning the repository at: + + git://git.eyrie.org/perl/ansicolor.git + + or view the repository on the web at: + + http://git.eyrie.org/?p=perl/ansicolor.git + +THANKS + + To Jon Lennox for looking at early versions of this module, providing + feedback, and offering suggestions for improvement. + + To Jesse Taylor for writing the first significant script to use this + module (colorized calsplit), thus offering innumerable opportunities to + test and debug. + + To Jean Delvare for providing documentation of what the various + attributes do on various different terminal emulators, and for noting + that attribute 2 is dark. + + To Edward Avis for the implementation of uncolor. + + To Rani Pinchuk for the idea of ANSI_COLORS_DISABLED and an initial + implementation. + + To ATricket for the information about what PuTTY, Windows telnet, and + OpenSSH under Cygwin support. + + To Richard Maus for pointing out DARK was missing from the exported + constants list and CYAN and WHITE were missing from the documentation. + + To Autrijus Tang for noticing a problem with string comparisons in the + test suite. + + To Daniel Lindsley for the information about what Mac OS X Terminal + supports. + + To Joe Smith for the test files that exercise a wide variety of VT100 + escape sequences including the ECMA-48 color control codes. + + To James Bowlin for catching a bug in colored when $EACHLINE is set that + caused it to not color lines consisting solely of 0. + + To Helge Kreutzmann for pointing out the need for warnings in the + documentation about background colors that span newlines. + + To Baron Schwartz for pointing out that cyan and white were missing from + the documentation. + + To Michael R. Wolf for pointing out that Wikipedia and the ECMA standard + use faint instead of dark as the name of attribute 2. + + To openmethods.com voice solutions for contributing PUSHCOLOR, POPCOLOR, + and LOCALCOLOR support. + + To Tim Bellinghausen for the AUTOLOAD taint fix for Perl 5.10. + + To Paul Miller for the idea and initial implementation of colorstrip. + + To Larry Wall, as always, for Perl. diff --git a/cpan/Term-ANSIColor/t/basic.t b/cpan/Term-ANSIColor/t/basic.t new file mode 100644 index 0000000000..748cdcc723 --- /dev/null +++ b/cpan/Term-ANSIColor/t/basic.t @@ -0,0 +1,133 @@ +#!/usr/bin/perl -Tw +# +# t/basic.t -- Test suite for the Term::ANSIColor Perl module. +# +# Copyright 1997, 1998, 2000, 2001, 2002, 2005, 2006, 2009 +# Russ Allbery <rra@stanford.edu> +# +# This program is free software; you may redistribute it and/or modify it +# under the same terms as Perl itself. + +use strict; +use Test::More tests => 47; + +BEGIN { + delete $ENV{ANSI_COLORS_DISABLED}; + use_ok ('Term::ANSIColor', + qw/:pushpop color colored uncolor colorstrip colorvalid/); +} + +# Various basic tests. +is (color ('blue on_green', 'bold'), "\e[34;42;1m", 'Simple attributes'); +is (colored ('testing', 'blue', 'bold'), "\e[34;1mtesting\e[0m", 'colored'); +is ((BLUE BOLD "testing"), "\e[34m\e[1mtesting", 'Constants'); +$Term::ANSIColor::AUTORESET = 1; +is ((BLUE BOLD "testing"), "\e[34m\e[1mtesting\e[0m\e[0m", 'AUTORESET'); +$Term::ANSIColor::EACHLINE = "\n"; +is (colored ("test\n\ntest", 'bold'), "\e[1mtest\e[0m\n\n\e[1mtest\e[0m", + 'EACHLINE'); +$Term::ANSIColor::EACHLINE = "\r\n"; +is (colored ("test\ntest\r\r\n\r\n", 'bold'), + "\e[1mtest\ntest\r\e[0m\r\n\r\n", + 'EACHLINE with multiple delimiters'); +$Term::ANSIColor::EACHLINE = "\n"; +is (colored (['bold', 'on_green'], "test\n", "\n", "test"), + "\e[1;42mtest\e[0m\n\n\e[1;42mtest\e[0m", + 'colored with reference to array'); +is_deeply ([ uncolor ('1;42', "\e[m", '', "\e[0m") ], + [ qw/bold on_green clear/ ], 'uncolor'); + +# Several tests for ANSI_COLORS_DISABLED. +$ENV{ANSI_COLORS_DISABLED} = 1; +is (color ('blue'), '', 'color support for ANSI_COLORS_DISABLED'); +is (colored ('testing', 'blue', 'on_red'), 'testing', + 'colored support for ANSI_COLORS_DISABLED'); +is ((GREEN 'testing'), 'testing', 'Constant support for ANSI_COLORS_DISABLED'); +delete $ENV{ANSI_COLORS_DISABLED}; + +# Make sure DARK is exported. This was omitted in versions prior to 1.07. +is ((DARK "testing"), "\e[2mtesting\e[0m", 'DARK'); + +# Check faint as a synonym for dark. +is (colored ('test', 'faint'), "\e[2mtest\e[0m", 'colored supports faint'); +is ((FAINT "test"), "\e[2mtest\e[0m", '...and the FAINT constant works'); + +# Test colored with 0 and EACHLINE. +$Term::ANSIColor::EACHLINE = "\n"; +is (colored ('0', 'blue', 'bold'), "\e[34;1m0\e[0m", + 'colored with 0 and EACHLINE'); +is (colored ("0\n0\n\n", 'blue', 'bold'), "\e[34;1m0\e[0m\n\e[34;1m0\e[0m\n\n", + 'colored with 0, EACHLINE, and multiple lines'); + +# Test colored with the empty string and EACHLINE. +is (colored ('', 'blue', 'bold'), '', + 'colored with an empty string and EACHLINE'); + +# Test push and pop support. +$Term::ANSIColor::AUTORESET = 0; +is ((PUSHCOLOR RED ON_GREEN "text"), "\e[31m\e[42mtext", + 'PUSHCOLOR does not break constants'); +is ((PUSHCOLOR BLUE "text"), "\e[34mtext", '...and adding another level'); +is ((RESET BLUE "text"), "\e[0m\e[34mtext", '...and using reset'); +is ((POPCOLOR "text"), "\e[31m\e[42mtext", '...and POPCOLOR works'); +is ((LOCALCOLOR GREEN ON_BLUE "text"), "\e[32m\e[44mtext\e[31m\e[42m", + 'LOCALCOLOR'); +$Term::ANSIColor::AUTOLOCAL = 1; +is ((ON_BLUE "text"), "\e[44mtext\e[31m\e[42m", 'AUTOLOCAL'); +$Term::ANSIColor::AUTOLOCAL = 0; +is ((POPCOLOR "text"), "\e[0mtext", 'POPCOLOR with empty stack'); + +# Test push and pop support with the syntax from the original openmethods.com +# submission, which uses a different coding style. +is (PUSHCOLOR (RED ON_GREEN), "\e[31m\e[42m", + 'PUSHCOLOR with explict argument'); +is (PUSHCOLOR (BLUE), "\e[34m", '...and another explicit argument'); +is (RESET . BLUE . "text", "\e[0m\e[34mtext", + '...and constants with concatenation'); +is (POPCOLOR . "text", "\e[31m\e[42mtext", + '...and POPCOLOR works without an argument'); +is (LOCALCOLOR(GREEN . ON_BLUE . "text"), "\e[32m\e[44mtext\e[31m\e[42m", + 'LOCALCOLOR with two arguments'); +is (POPCOLOR . "text", "\e[0mtext", 'POPCOLOR with no arguments'); + +# Test colorstrip. +is (colorstrip ("\e[1mBold \e[31;42mon green\e[0m\e[m"), 'Bold on green', + 'Basic color stripping'); +is (colorstrip ("\e[1m", 'bold', "\e[0m"), 'bold', + 'Color stripping across multiple strings'); +is_deeply ([ colorstrip ("\e[1m", 'bold', "\e[0m") ], + [ '', 'bold', '' ], '...and in an array context'); +is (colorstrip ("\e[2cSome other code\e and stray [0m stuff"), + "\e[2cSome other code\e and stray [0m stuff", + 'colorstrip does not remove non-color stuff'); + +# Test colorvalid. +is (colorvalid ("blue bold dark", "blink on_green"), 1, + 'colorvalid returns true for valid attributes'); +is (colorvalid ("green orange"), undef, + '...and false for invalid attributes'); + +# Test error handling. +my $output = eval { color 'chartreuse' }; +is ($output, undef, 'color on unknown color name fails'); +like ($@, qr/^Invalid attribute name chartreuse at /, + '...with the right error'); +$output = eval { colored "Stuff", 'chartreuse' }; +is ($output, undef, 'colored on unknown color name fails'); +like ($@, qr/^Invalid attribute name chartreuse at /, + '...with the right error'); +$output = eval { uncolor "\e[28m" }; +is ($output, undef, 'uncolor on unknown color code fails'); +like ($@, qr/^No name for escape sequence 28 at /, '...with the right error'); +$output = eval { uncolor "\e[foom" }; +is ($output, undef, 'uncolor on bad escape sequence fails'); +like ($@, qr/^Bad escape sequence foo at /, '...with the right error'); + +# Test error reporting when calling unrecognized Term::ANSIColor subs that go +# through AUTOLOAD. +eval { Term::ANSIColor::RSET () }; +like ($@, qr/^undefined subroutine \&Term::ANSIColor::RSET called at /, + 'Correct error from an attribute that is not defined'); +eval { Term::ANSIColor::reset () }; +like ($@, qr/^undefined subroutine \&Term::ANSIColor::reset called at /, + 'Correct error from a lowercase attribute'); |