file name : colour.bash
purpose   : provide canonical access to ANSI colour sequences in bash
          : scripts.
copyright : April, 2015
author    : Tom Legrady <Tom@TomLegrady.com> 

As demonstrated in colour.samples and colour.demo, 'source' the
colour.bash file and then use the routines.

The external API is the function ANSI_color(). It takes three
arguments: attribute, foreground colour and background colour. The
attribute is optional.

Attribute is one of following

	0	Reset All Attributes (return to normal mode)
	1	Bright (Usually turns on BOLD)
	2 	Dim
	3	Italic
	4	Underline
	5	Blink
	7 	Reverse
	8	Hidden

Documentation states the #3 underlines text, and does not define #4,
but my tests show the above. #6 is similarly not defined.

The foreground colour is one of the following:
	30	Black		31	Red	32	Green
	33	Yellow		34	Blue	35	Magenta
	36	Cyan		37	White

The background colour is the same as the foreground colour, shifted by 10:
	40	Black		41	Red	42	Green
	43	Yellow		44	Blue	45	Magenta
	46	Cyan		47	White

Quite simply, the colours are the result of bit-mapping red, green and
blue, added to 30 for the foreground colour, or 40 for the background
colour. Red is the least-significant bit, green is the next, and blue
the most significant. The primary colours are thus 1, 2 and 4. The
combination of red and green is yellow, with a value of 3. Blue and
red is 5, or magenta, known as purple. Blue and green, with a value of
6, makes cyan, a light greenish blue. No colour is bloack, or
zero. White is a combination of red, green and blue, or 1 + 2 + 4 = 7.

The return value from ANSI_color is a string of the form
"\e[1;32;43m". The first character is the ASCII "escape" character,
0X1B, also known as octal 033 or '\e'.  The second character, a
hard-coded opening square bracket, is followed by one, two or three of
the above codes, followed by a hard-coded 'm'.The colour/attribute
codes are separated by semi-colons. Returning to normal after color
codes uses not just one but two zeros: \e[00m.

There's also a hide_escape() routine, which wraps the escape sequence
in escaped square brackets: \[ \]. When calculating line width, the
square brackets allow the shell to know what characters to consider as
zero-width.

Released under
  * Artistic License (http://dev.perl.org/licenses/artistic.html)
  * GNU Lublic License v3 (http://www.gnu.org/licenses/).
Use it, just don't claim you wrote it.

# ----------------------------------------------------------------------
# End of File.
#