# $EPIC: cparse.txt,v 1.5 2010/01/10 01:08:22 jnelson Exp $
======Synopsis======
$__cparse__(<text>) \\
$__cparse__("<text>" <arguments>...)

======Technical:======
In the first form, <text> is a string that can contain embeded color directives.
In the second form, <text> is a [[what is a word|dword]] that can contain 
embedded color directives *and* references to $* which are satisfied by the
following <arguments>.  Don't forget to double up your $'s in this second
format when refering to $*.

This function parses <text> according to the following table:

^ Color Code(s) ^ Text	^ Text		^ Background |
| %k %K %0	| black	| bold black	| black |
| %r %R %1	| red	| bold red	| red |
| %g %G %2	| green	| bold green	| green |
| %y %Y %3	| yellow | bold yellow	| yellow |
| %b %B %4	| blue	| bold blue	| blue |
| %m %M %5	| magenta | bold magenta | magenta |
| %p %P		| magenta (purple) | magenta (purple) | |
| %c %C %6	| cyan	| bold cyan	| cyan |
| %w %W %7	| while	| bold white	| white |

These codes have special meanings
^ Color Code	^ Meaning ^
| %F		| flashing |
| %n		| Turn all colors off |
| %N		| Don't reset colors at end of string |
| %X            | Insert a literal Control-X (see example below) |
| %%		| Insert a literal % |

======Practical:======
This is a convenient way add color to scripts without actually using
the control-c character.

======Returns:======
<text> parsed according to the rules in the above table

======Examples:======
Example 1: basic colors
  $cparse(bl%Bah)
returns
  bl^C4ah
where ^C4 is the control-c color code for blue.

Example 2: interpolation
  $cparse("This is a $$0 test" cparse)
returns
  This is a cparse test
Remember that $'s are expanded before a function is called, so you have to
double up the $'s to make it work properly.

Example 3: 256-colors
  $cparse(%X80Testing)
returns
  ^X80Testing
which will render your Testing in color 80 (usually some kind of blue)

======Disclaimer:======
"Bold Colors" is implementation defined by your terminal emulator.
You might expect any of these outcomes
  - Bold text but ordinary color
  - Ordinary text but bold color
  - Bold text and bold color
  - Ordinary text and ordinary color
(That last one is pretty lame, but believe it or not there are emulators that actually do that.)
You can use 256 colors to work around this