Upgrade to ANSIColor-1.11

[p5sagit/p5-mst-13.2.git] / lib / Term / ANSIColor.pm

diff --git a/lib/Term/ANSIColor.pm b/lib/Term/ANSIColor.pm
index ef27ae9..9832c41 100644 (file)
--- a/lib/Term/ANSIColor.pm
+++ b/lib/Term/ANSIColor.pm
@@ -1,7 +1,7 @@
 # Term::ANSIColor -- Color screen output using ANSI escape sequences.
-# $Id: ANSIColor.pm,v 1.10 2005/08/21 18:31:58 eagle Exp $
+# $Id: ANSIColor.pm 58 2006-07-12 22:30:55Z eagle $
 #
-# Copyright 1996, 1997, 1998, 2000, 2001, 2002, 2005
+# Copyright 1996, 1997, 1998, 2000, 2001, 2002, 2005, 2006
 #   by Russ Allbery <rra@stanford.edu> and Zenin
 #
 # This program is free software; you may redistribute it and/or modify it
@@ -32,9 +32,7 @@ use Exporter ();
                                  ON_CYAN ON_WHITE)]);
 Exporter::export_ok_tags ('constants');
 
-# Don't use the CVS revision as the version, since this module is also in Perl
-# core and too many things could munge CVS magic revision strings.
-$VERSION = '1.10';
+$VERSION = '1.11';
 
 ##############################################################################
 # Internal data structures
@@ -209,9 +207,10 @@ Term::ANSIColor - Color screen output using ANSI escape sequences
     print "This text is bold blue.\n";
     print color 'reset';
     print "This text is normal.\n";
-    print colored ("Yellow on magenta.\n", 'yellow on_magenta');
+    print colored ("Yellow on magenta.", 'yellow on_magenta'), "\n";
     print "This text is normal.\n";
-    print colored ['yellow on_magenta'], "Yellow on magenta.\n";
+    print colored ['yellow on_magenta'], 'Yellow on magenta.';
+    print "\n";
 
     use Term::ANSIColor qw(uncolor);
     print uncolor '01;31', "\n";
@@ -269,10 +268,12 @@ 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 is being sent to a program
-like a pager that can be confused by attributes that span lines.  Normally
-you'll want to set $Term::ANSIColor::EACHLINE to C<"\n"> to use this
-feature.
+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.
 
 Alternately, if you import C<:constants>, you can use the constants CLEAR,
 RESET, BOLD, DARK, UNDERLINE, UNDERSCORE, BLINK, REVERSE, CONCEALED, BLACK,
@@ -280,11 +281,14 @@ 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\n", RESET;
+    print BOLD BLUE ON_WHITE "Text", RESET, "\n";
 
 to
 
-    print colored ("Text\n", 'bold blue on_white');
+    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
@@ -298,7 +302,9 @@ will reset the display mode afterwards, whereas:
 
     print BOLD, BLUE, "Text\n";
 
-will not.
+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
@@ -465,8 +471,8 @@ with input from Zenin.  Russ Allbery now maintains this module.
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 1996, 1997, 1998, 2000, 2001, 2002 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.
+Copyright 1996, 1997, 1998, 2000, 2001, 2002, 2005, 2006 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.
 
 =cut