From a2e566370fe567940a85401ed7589d09d106d6a1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tadeusz=20So=C5=9Bnierz?= <tadzikes@gmail.com>
Date: Mon, 26 Jul 2010 19:02:52 +0000
Subject: [PATCH] Added docs, changed error messages to act as Perl5's
 Term::ANSIColor

---
 lib/Term/ANSIColor.pm | 69 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 67 insertions(+), 2 deletions(-)

diff --git a/lib/Term/ANSIColor.pm b/lib/Term/ANSIColor.pm
index ac3e7c5..ff91de7 100644
--- a/lib/Term/ANSIColor.pm
+++ b/lib/Term/ANSIColor.pm
@@ -42,7 +42,7 @@ sub color (Str $what) is export {
 		if %attrs.exists($attr) {
 			@res.push: %attrs{$attr}
 		} else {
-			die("No such attribute: '$attr'")
+			die("Invalid attribute name '$attr'")
 		}
 	}
 	return "\e[" ~ @res.join(';') ~ "m";
@@ -74,8 +74,73 @@ sub uncolor (Str $what) is export {
 		if %attrs.reverse.exists($elem) {
 			@res.push: %attrs.reverse{$elem}
 		} else {
-			die("No such sequence: {'\e[' ~ $elem ~ 'm'}")
+			die("Bad escape sequence: {'\e[' ~ $elem ~ 'm'}")
 		}
 	}
 	return @res.join(' ');
 }
+
+=begin pod
+
+=head1 NAME
+
+Term::ANSIColor - Color screen output using ANSI escape sequences
+
+=head1 SYNOPSIS
+
+	use Term::ANSIColor;
+	say color('bold'), "this is in bold", color('reset');
+	say colored('underline red on_green', 'what a lovely colours!');
+	say BOLD, 'good to be fat!', BOLD_OFF;
+	say 'ok' if colorvalid('magenta', 'on_black', 'inverse');
+	say '\e[36m is ', uncolor('\e36m');
+	say colorstrip("\e[1mThis is bold\e[0m");
+
+=head1 DESCRIPTION
+
+Term::ANSIColor provides an interface for using colored output
+in terminals. The following functions are available:
+
+=head2 C<color()>
+
+Given a string with color names, the output produced by C<color()>
+sets the terminal output so the text printed after it will be colored
+as specified. The following color names are recognised:
+
+	reset bold underline inverse black red green yellow blue
+	magenta cyan white default on_black on_red on_green on_yellow
+	on_blue on_magenta on_cyan on_white on_default
+
+The on_* family of colors correspond to the background colors.
+
+=head2 C<colored()>
+
+C<colored()> is similar to C<color()>. It takes two Str arguments,
+where the first is the colors to be used, and the second is the string
+to be colored. The C<reset> sequence is automagically placed after
+the string.
+
+=head2 C<colorvalid()>
+
+C<colorvalid()> gets an array of color specifications (like those
+passed to C<color()>) and returns true if all of them are valid,
+false otherwise.
+
+=head2 C<colorstrip()>
+
+C<colorstrip>, given a string, removes all the escape sequences
+in it, leaving the plain text without effects.
+
+=head2 C<uncolor()>
+
+Given escape sequences, C<uncolor()> returns a string with readable
+color names. E.g. passing "\e[36;44m" will result in "cyan on_blue".
+
+=head1 Constants
+
+C<Term::ANSIColor> provides constants which are just strings of
+appropriate escape sequences. The following constants are available:
+
+	RESET BOLD UNDERLINE INVERSE BOLD_OFF UNDERLINE_OFF INVERSE_OFF
+
+=end pod