package ANSI;

=head1 NAME

ANSI - A simple ANSI hash and routine.

=head1 SYNOPSIS

  use ANSI;

  print ansi(qw(bold flash underline red));
  print ("Some text.\n");
  print ansi('normal');

  use ANSI '%ANSI';

  print "$ANSI{'color'}";

=head1 DESCRIPTIOIN

C<ANSI> is a very simple module designed to provide raw ANSI codes by name so
you don't have to remember them yourself.

You can use the hash %ANSI, or use the function ansi().  The advantage of the
functin is that it can be given multiple arguments, and it returns a string of
all the related elements of %ANSI concatenated together.

The color codes are as follows:

 Variable:        ANSI #:  What it does:

 $ANSI{'normal'}       0   Restores default color.
 $ANSI{'bright'}       1   Brighter colors.
 $ANSI{'bold'}         1   Same as $ANSI{'bright'}.
 $ANSI{'underline'}    4   Underlined text.
 $ANSI{'flash'}        5   Flashing text.
 $ANSI{'blink'}        5   Same as $ANSI{'flash'}.
 $ANSI{'reverse'}      7   Reverse video.

 $ANSI{'nounderline'} 24   No-underline.
 $ANSI{'noflash'}     25   No-flash.
 $ANSI{'noreverse'}   27   No-reverse.

 $ANSI{'black'}       30   Black foreground.
 $ANSI{'red'}         31   Red foreground.
 $ANSI{'green'}       32   Green foreground.
 $ANSI{'yellow'}      33   Yellow (or brown) foreground.
 $ANSI{'blue'}        34   Blue foreground.
 $ANSI{'magenta'}     35   Purple foreground.
 $ANSI{'cyan'}        36   Cyan foreground.
 $ANSI{'white'}       37   White (or gray) foreground.

 $ANSI{'BLACK'}       40   Black background.
 $ANSI{'RED'}         41   Red background.
 $ANSI{'GREEN'}       42   Green background.
 $ANSI{'YELLOW'}      43   Yellow (or brown) background.
 $ANSI{'BLUE'}        44   Blue background.
 $ANSI{'MAGENTA'}     45   Purple background.
 $ANSI{'CYAN'}        46   Cyan background.
 $ANSI{'WHITE'}       47   White (or gray) background.

You can get translations of the numbers (without the raw escapes) to color
names or vice-versa by exporting the %COLOR_NUMBERS hash.

In addition, there's some cursor handling codes:

 $ANSI{'clear'}       Clear the screen, put cursor at the top left.
 $ANSI{'cleareol'}    Clear from the cursor position to the end of the line.
 $ANSI{'cleartoeol'}  Same as $ANSI{'cleareol'}
 $ANSI{'save'}        Save che cursor position.
 $ANSI{'restore'}     Restore the cursor to the saved position.
 ansi(up => N)        Move the cursor up N lines.         (*)
 ansi(down => N)      Move the cursor down N lines.       (*)
 ansi(right => N)     Move the cursor right N columns.    (*)
 ansi(left => N)      Move the cursor left N columns.     (*)
 ansi(forward => N)   Same as ansi(right => N)            (*)
 ansi(backward => N)  Same as ansi(left => N)             (*)
 ansi(move => I, J)   Move the cursor to row I, column J. (*)

B<(*)> These codes aren't useful when used directly from the %ANSI hash
(they're a reference).  They can be used by the ansi() function with
subsequent arguments. e.g.:

 ansi(move => 5, 15);  # Return the code to move to row 5, column 15.

=head1 EXAMPLE

The following will give a simple demo of ANSI colors.

 #!/usr/bin/perl
 
 use lib qw(/location/of/this/file);
 
 use ANSI;
 
 foreach $color (qw/normal bright underline flash/)
 {
   print ansi($color), "$color", ansi('normal');
   print "\n";
 }
 
 foreach $color (qw/black red green yellow blue magenta cyan white/)
 {
   print ansi($color), "normal $color", ansi('normal'), ", ";
   print ansi('bright', $color), "bright $color", ansi(normal), ", ";
   print ansi ( ("\U$color" eq "BLACK" ? 'white' : 'black'), "\U$color");
   print "reverse $color", ansi('normal'), "\n";
 }

=head1 TODO

Add the following ANSI escapes:

 22 normal (how is this different from 0?)

=head1 AUTHOR

Christian J. Robinson <infynity@onewest.net>

=head1 COPYRIGHT

Copyright (C) 1999, 2002, 2003 Christian J. Robinson <infynity@onewest.net>

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.

=cut

use 5.004;
use strict;
use Exporter;
use Carp;

use vars qw(@ISA @EXPORT @EXPORT_OK $VERSION %ANSI %COLOR_NUMBERS);

$VERSION   = 1.2;

@ISA       = qw(Exporter);
@EXPORT    = qw(ansi);
@EXPORT_OK = qw(%ANSI %COLOR_NUMBERS);

sub c_escape($);

%COLOR_NUMBERS = (
	'normal'    => 0,   'bright'      => 1,
	'underline' => 4,   'nounderline' => 24,
	'flash'     => 5,   'noflash'     => 25,
	'reverse'   => 7,   'noreverse'   => 27,

	'black'     => 30,  'BLACK'   => 40,
	'red'       => 31,  'RED'     => 41,
	'green'     => 32,  'GREEN'   => 42,
	'yellow'    => 33,  'YELLOW'  => 43,
	'blue'      => 34,  'BLUE'    => 44,
	'magenta'   => 35,  'MAGENTA' => 45,
	'cyan'      => 36,  'CYAN'    => 46,
	'white'     => 37,  'WHITE'   => 47,
);

# Aliases:
$COLOR_NUMBERS{'blink'} = $COLOR_NUMBERS{'flash'};
$COLOR_NUMBERS{'bold'}  = $COLOR_NUMBERS{'bright'};

%ANSI = (
	'clear'   => "\033[H\033[2J",   'cleareol' => "\033[K",
	'save'    => "\033[s",          'restore'  => "\033[u",
	'up'      => [1,"\033[%iA"],    'down'     => [1,"\033[%iB"],
	'right'   => [1,"\033[%iC"],    'left'     => [1,"\033[%iD"],
	'move'    => [2,"\033[%i;%iH"],
);

foreach my $color (keys %COLOR_NUMBERS)
{
	$ANSI{$color} = c_escape($COLOR_NUMBERS{$color});
	$COLOR_NUMBERS{$COLOR_NUMBERS{$color}} = $color;
}

# Aliases:
$ANSI{'cleartoeol'} = $ANSI{'cleareol'};
$ANSI{'forward'}    = $ANSI{'right'};
$ANSI{'backward'}   = $ANSI{'left'};

sub c_escape($)
{
	my $number = shift;

	return "\033[${number}m";
}

sub ansi
{
	my @args = @_;
	my ($str, $arg);

	#foreach (@_) { $str .= $ANSI{$_}; }

	while (@args)
	{
		$arg = shift @args;
		if (ref($ANSI{$arg}))
		{
			$str .= sprintf($ANSI{$arg}->[1], @args[0 .. ($ANSI{$arg}->[0] - 1)]);
			if ($#args < $ANSI{$arg}->[0])
			{
				@args = ();
			} else {
				@args = @args[$ANSI{$arg}->[0] .. $#args];
			}
		} elsif (defined($ANSI{$arg})) {
			$str .= $ANSI{$arg};
		} else {
			carp "No such ANSI value: $arg";
		}
	}

	$str;
}


1;

# vim600:fdl=1: