#!/usr/bin/env perl

#######################################################################
#            _   _  _____ _____   ______                     _        #
#      ╱╲   | ╲ | |╱ ____|_   _| |  ____|                   | |       #
#     ╱  ╲  |  ╲| | (___   | |   | |__   _ __   ___ ___   __| | ___   #
#    ╱ ╱╲ ╲ | . ` |╲___ ╲  | |   |  __| | '_ ╲ ╱ __╱ _ \ / _` |╱ _ ╲  #
#   ╱ ____ ╲| |╲  |____) |_| |_  | |____| | | | (_| (_) | (_| |  __╱  #
#  ╱_╱    ╲_╲_| ╲_|_____╱|_____| |______|_| |_|╲___╲___╱ ╲__,_|╲___|  #
#######################################################################
#                     Written By Richard Kelsch                       #
#                  © Copyright 2025 Richard Kelsch                    #
#                        All Rights Reserved                          #
#######################################################################

use strict;
use utf8;
use charnames();
use constant {
    TRUE  => 1,
    FALSE => 0,
    YES   => 1,
    NO    => 0,
};

use Term::ANSIScreen qw( :cursor :screen );
use Term::ANSIColor;
use Time::HiRes qw( sleep );
use Term::ANSIEncode;
use Getopt::Long;
use List::Util qw(max);

# use Data::Dumper::Simple;$Data::Dumper::Terse=TRUE;$Data::Dumper::Indent=TRUE;$Data::Dumper::Useqq=TRUE;$Data::Dumper::Deparse=TRUE;$Data::Dumper::Quotekeys=TRUE;$Data::Dumper::Trailingcomma=TRUE;$Data::Dumper::Sortkeys=TRUE;$Data::Dumper::Purity=TRUE;$Data::Dumper::Deparse=TRUE;

# Since UTF-8 is the norm, it's enabled for all needed handles
binmode(STDERR, ":encoding(UTF-8)");
binmode(STDOUT, ":encoding(UTF-8)");
binmode(STDIN,  ":encoding(UTF-8)");

our $VERSION = $Term::ANSIEncode::VERSION;    # Pull in the version from Term::ANSIEncode

my $version   = FALSE;
my $help      = FALSE;
my $tokens    = FALSE;
my $rawtokens = FALSE;
my $symbols   = FALSE;
my $unicode   = FALSE;
my $colors    = FALSE;
my $Dump      = FALSE;

GetOptions(
    'version'   => \$version,
    'help'      => \$help,
    'tokens'    => \$tokens,
    'rawtokens' => \$rawtokens,
    'colors'    => \$colors,
    'symbols'   => \$symbols,
    'dump'      => \$Dump,
    'unicode'   => \$unicode,
);
###
my $text = <<'VERSION';
[% CLS %][% ORANGE %]╔═════════════════════════════════════════════════════════════════════════════╗[% RESET %]
[% ORANGE %]║[% B_BLACK %][% RED %]               [% BRIGHT YELLOW %] _   _ [% GREEN %] _____ [% BRIGHT BLUE %]_____  [% BRIGHT WHITE %] ______                     _            [% RESET %][% ORANGE %]║[% RESET %]
[% ORANGE %]║[% B_BLACK %][% RED %]          ╱╲   [% BRIGHT YELLOW %]│ ╲ │ │[% GREEN %]╱ ____│[% BRIGHT BLUE %]_   _│ [% BRIGHT WHITE %]│  ____│                   │ │           [% RESET %][% ORANGE %]║[% RESET %]
[% ORANGE %]║[% B_BLACK %][% RED %]         ╱  ╲  [% BRIGHT YELLOW %]│  ╲│ │[% GREEN %] (___  [% BRIGHT BLUE %] │ │   [% BRIGHT WHITE %]│ │__   _ __   ___ ___   __│ │ ___       [% RESET %][% ORANGE %]║[% RESET %]
[% ORANGE %]║[% B_BLACK %][% RED %]        ╱ ╱╲ ╲ [% BRIGHT YELLOW %]│ . ` │[% GREEN %]╲___ ╲ [% BRIGHT BLUE %] │ │   [% BRIGHT WHITE %]│  __│ │ '_ ╲ ╱ __╱ _ ╲ ╱ _` │╱ _ ╲      [% RESET %][% ORANGE %]║[% RESET %]
[% ORANGE %]║[% B_BLACK %][% RED %]       ╱ ____ ╲[% BRIGHT YELLOW %]│ │╲  │[% GREEN %]____) │[% BRIGHT BLUE %]_│ │_  [% BRIGHT WHITE %]│ │____│ │ │ │ (_│ (_) │ (_│ │  __╱      [% RESET %][% ORANGE %]║[% RESET %]
[% ORANGE %]║[% B_BLACK %][% RED %]      ╱_╱    ╲_╲[% BRIGHT YELLOW %]_│ ╲_│[% GREEN %]_____╱[% BRIGHT BLUE %]│_____│ [% BRIGHT WHITE %]│______│_│ │_│╲___╲___╱ ╲__,_│╲___│      [% RESET %][% ORANGE %]║[% RESET %]
[% ORANGE %]║[% B_BLACK %]                                                                             [% ORANGE %]║[% B_BLACK %]
[% ORANGE %]╠═════════════════════════════════════════════════════════════════════════════╣[% RESET %]
[% ORANGE %]║[% RESET %][% B_COLOR 17 %]                         Written By [% BRIGHT YELLOW %]Richard Kelsch[% RESET %][% B_COLOR 17 %]                           [% RESET %][% ORANGE %]║[% RESET %]
[% ORANGE %]║[% RESET %][% B_COLOR 17 %]                       Copyright ©[% GREEN %]2025 [% BRIGHT YELLOW %]Richard Kelsch[% RESET %][% B_COLOR 17 %]                        [% RESET %][% ORANGE %]║[% RESET %]
[% ORANGE %]║[% RESET %][% B_COLOR 17 %]                            All Rights Reserved                              [% RESET %][% ORANGE %]║[% RESET %]
[% ORANGE %]║[% RESET %][% B_COLOR 17 %]                           Perl Artistic License                             [% RESET %][% ORANGE %]║[% RESET %]
[% ORANGE %]║[% RESET %][% B_COLOR 17 %]                               Version [% GREEN %]XXXX[% RESET %][% B_COLOR 17 %]                                  [% RESET %][% ORANGE %]║[% RESET %]
[% ORANGE %]║[% RESET %][% B_COLOR 17 %]              GitHub:  https://github.com/richcsst/ansi-encode               [% RESET %][% ORANGE %]║[% RESET %]
[% ORANGE %]╚═════════════════════════════════════════════════════════════════════════════╝[% RESET %]

VERSION
###
$text =~ s/XXXX/$VERSION/gs;

my $ansi = Term::ANSIEncode->new('mode' => 'full');

###
my $small = <<'SMALL';
[% CLS %]╔═════════════════════════════════════════════════════════════════════════╗
║[% B_BLACK %]                     [% RED %]┏━┓[% BRIGHT YELLOW %]┏┓╻[% GREEN %]┏━┓[% BRIGHT BLUE %]╻   [% BRIGHT WHITE %]┏━╸┏┓╻┏━╸┏━┓╺┳┓┏━╸                     [% RESET %]║
║[% B_BLACK %]                     [% RED %]┣━┫[% BRIGHT YELLOW %]┃┗┫[% GREEN %]┗━┓[% BRIGHT BLUE %]┃   [% BRIGHT WHITE %]┣╸ ┃┗┫┃  ┃ ┃ ┃┃┣╸                      [% RESET %]║
║[% B_BLACK %]                     [% RED %]╹ ╹[% BRIGHT YELLOW %]╹ ╹[% GREEN %]┗━┛[% BRIGHT BLUE %]╹   [% BRIGHT WHITE %]┗━╸╹ ╹┗━╸┗━┛╺┻┛┗━╸                     [% RESET %]║
╠═════════════════════════════════════════════════════════════════════════╣
║[% B_COLOR 52 %][% BRIGHT YELLOW %] DESCRIPTION                                                             [% RESET %]║
║     Markup text to ANSI encoder.                                        ║
║                                                                         ║
║[% B_COLOR 52 %][% BRIGHT YELLOW %] USAGE                                                                   [% RESET %]║
║     [% CYAN %]ansi-encode[% RESET %] [options] [text file]                                   ║
║                                                                         ║
║[% B_COLOR 52 %][% BRIGHT YELLOW %] OPTIONS                                                                 [% RESET %]║
║     -[% PINK %]v[% RESET %] or --[% PINK %]version[% RESET %]                                                     ║
║         Shows version and licensing info                                ║
║                                                                         ║
║     -[% PINK %]h[% RESET %] or --[% PINK %]help[% RESET %]                                                        ║
║         Usage information                                               ║
║                                                                         ║
║     -[% PINK %]t[% RESET %] or --[% PINK %]tokens[% RESET %]                                                      ║
║         Show most used tokens                                           ║
║                                                                         ║
║     -[% PINK %]r[% RESET %] or --[% PINK %]rawtokens[% RESET %]                                                   ║
║         Raw dump of available tokens.                                   ║
║                                                                         ║
║     -[% PINK %]c[% RESET %] or --[% PINK %]colors[% RESET %]                                                      ║
║         Show available colors and tokens                                ║
║                                                                         ║
║     -[% PINK %]s[% RESET %] or --[% PINK %]symbols[% RESET %] [search]                                            ║
║         Show available symbols and character tokens by name             ║
║                                                                         ║
║     -[% PINK %]u[% RESET %] or --[% PINK %]unicode[% RESET %] [search]                                            ║
║         Show available symbols and character tokens by unicode          ║
║                                                                         ║
║     -[% PINK %]d[% RESET %] or --[% PINK %]dump[% RESET %] [search]                                               ║
║         Dump available sysmbols                                         ║
╚═════════════════════════════════════════════════════════════════════════╝
SMALL
###
my $greydient = '';    # Yes, the spelling is intentional
foreach my $c (0 .. 23) {
    $greydient .= "[% B_GREY $c %] ";
}
$greydient .= '[% RESET %]';
###
my $to = <<'TOKENS';
[% CLS %]Tokens have to be encapsulated inside [ % TOKEN % ] (the TOKEN must be
surrounded by at least one space on each side).  Colors beyond the standard 8
will require a terminal that supports 256 colors.  It is also recommended that
your terminal supports UTF-8 for advanced character/symbol support.  Some
terminals may not support some features.

NOTE:  Use "less -r" to view ANSI in "less"

[% BRIGHT WHITE %]╭────────────────────────────────────────────────────────────────────────────╮[% RESET %]
[% BRIGHT WHITE %]│[% B_BLACK %][% RED           %]     ::::::::::::   ...      :::  .   .,:::::::::.    :::. .::::::.         [% RESET %][% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% B_BLACK %][% ORANGE        %]     ;;;;;;;;''''.;;;;;;;.   ;;; .;;,.;;;;''''`;;;;,  `;;;;;;`    `         [% RESET %][% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% B_BLACK %][% BRIGHT YELLOW %]          [[    ,[[     \[[, [[[[[/'   [[cccc   [[[[[. '[['[==/[[[[,        [% RESET %][% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% B_BLACK %][% GREEN         %]          $$    $$$,     $$$_$$$$,     $$""""   $$$ "Y$c$$  '''    $        [% RESET %][% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% B_BLACK %][% CYAN          %]          88,   "888,_ _,88P"888"88o,  888oo,__ 888    Y88 88b    dP        [% RESET %][% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% B_BLACK %][% BLUE          %]          MMM     "YMMMMMP"  MMM "MMP" """"YUMMMMMM     YM  "YMmMY"         [% RESET %][% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]╞══[% B_BLACK %] [% BOLD %][% MAGENTA %]GENERAL [% RESET %][% BRIGHT WHITE %]═════════════════════╤═══════════════════════════════════════════╡[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] RETURN                         [% BRIGHT WHITE %]│[% RESET %] ASCII RETURN (13)                         [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] LINEFEED                       [% BRIGHT WHITE %]│[% RESET %] ASCII LINEFEED (10)                       [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] NEWLINE                        [% BRIGHT WHITE %]│[% RESET %] RETURN + LINEFEED (13 + 10)               [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] CLEAR                          [% BRIGHT WHITE %]│[% RESET %] Places cursor at top left, screen cleared [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] CLS                            [% BRIGHT WHITE %]│[% RESET %] Same as CLEAR                             [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] CLEAR LINE                     [% BRIGHT WHITE %]│[% RESET %] Clear to the end of line                  [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] CLEAR DOWN                     [% BRIGHT WHITE %]│[% RESET %] Clear down from current cursor position   [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] CLEAR UP                       [% BRIGHT WHITE %]│[% RESET %] Clear up from current cursor position     [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] RESET                          [% BRIGHT WHITE %]│[% RESET %] Reset all colors and attributes           [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]╞══[% B_BLACK %] [% BOLD %][% CYAN %]CURSOR [% RESET %][% BRIGHT WHITE %]══════════════════════╪═══════════════════════════════════════════╡[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] UP                             [% BRIGHT WHITE %]│[% RESET %] Moves cursor up one step                  [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] DOWN                           [% BRIGHT WHITE %]│[% RESET %] Moves cursor down one step                [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] RIGHT                          [% BRIGHT WHITE %]│[% RESET %] Moves cursor right one step               [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] LEFT                           [% BRIGHT WHITE %]│[% RESET %] Moves cursor left one step                [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] LOCATE row,column              [% BRIGHT WHITE %]│[% RESET %] Moves cursor to specified position        [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] SAVE                           [% BRIGHT WHITE %]│[% RESET %] Save cursor position                      [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] RESTORE                        [% BRIGHT WHITE %]│[% RESET %] Place cursor at saved position            [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] BOLD                           [% BRIGHT WHITE %]│[% RESET %] [% BOLD %]Bold text[% RESET %]                                 [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] FAINT                          [% BRIGHT WHITE %]│[% RESET %] [% FAINT %]Faded text[% RESET %]                                [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] ITALIC                         [% BRIGHT WHITE %]│[% RESET %] [% ITALIC %]Italicized text[% RESET %]                           [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] UNDERLINE                      [% BRIGHT WHITE %]│[% RESET %] [% UNDERLINE %]Underlined text[% RESET %]                           [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] SLOW BLINK                     [% BRIGHT WHITE %]│[% RESET %] Slow cursor [% SLOW BLINK %]blink[% RESET %]                         [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] RAPID BLINK                    [% BRIGHT WHITE %]│[% RESET %] Rapid cursor [% RAPID BLINK %]blink[% RESET %]                        [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]╞══[% B_BLACK %] [% BOLD %][% BRIGHT YELLOW %]ATTRIBUTES [% RESET %][% BRIGHT WHITE %]══════════════════╪═══════════════════════════════════════════╡[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] INVERT                         [% BRIGHT WHITE %]│[% RESET %] [% INVERT %] Invert text [% RESET %]                             [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] REVERSE                        [% BRIGHT WHITE %]│[% RESET %] [% REVERSE %] Reverse [% RESET %]                                 [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] CROSSED OUT                    [% BRIGHT WHITE %]│[% RESET %] [% CROSSED OUT %]Crossed out[% RESET %]                               [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] DEFAULT FONT                   [% BRIGHT WHITE %]│[% RESET %] Default font                              [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]╞══[% B_BLACK %] [% BOLD %][% BRIGHT RED %]FRAMES [% RESET %][% BRIGHT WHITE %]══════════════════════╪═══════════════════════════════════════════╡[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] BOX color,x,y,w,h,type         [% BRIGHT WHITE %]│[% RESET %] Define a box color, dimensions and type   [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] [% GREY 7 %]------------------------------[% RESET %] [% BRIGHT WHITE %]│[% RESET %] Types:  DEFAULT, THICK, THIN, ROUNDED     [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] ENDBOX                         [% BRIGHT WHITE %]│[% RESET %] Terminator for encapsulated text in a box [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]╞══[% B_BLACK %] [% BOLD %][% GREEN %]COLORS [% RESET %][% BRIGHT WHITE %]══════════════════════╪═══════════════════════════════════════════╡[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] NORMAL                         [% BRIGHT WHITE %]│[% RESET %] Sets colors to default                    [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]╞══[% B_BLACK %] [% BOLD %][% PINK %]FOREGROUND [% RESET %][% BRIGHT WHITE %]══════════════════╪═══════════════════════════════════════════╡[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] DEFAULT                        [% BRIGHT WHITE %]│[% RESET %] Default foreground color[% RESET %]                  [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] BLACK                          [% BRIGHT WHITE %]│[% RESET %] [% B_GREY 8       %][% BLACK %] Black [% RESET %]                                   [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] RED                            [% BRIGHT WHITE %]│[% RESET %] [% RED            %]Red[% RESET %]                                       [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] PINK                           [% BRIGHT WHITE %]│[% RESET %] [% PINK           %]Hot pink[% RESET %]                                  [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] ORANGE                         [% BRIGHT WHITE %]│[% RESET %] [% ORANGE         %]Orange[% RESET %]                                    [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] NAVY                           [% BRIGHT WHITE %]│[% RESET %] [% NAVY           %]Deep blue[% RESET %]                                 [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] GREEN                          [% BRIGHT WHITE %]│[% RESET %] [% GREEN          %]Green[% RESET %]                                     [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] YELLOW                         [% BRIGHT WHITE %]│[% RESET %] [% YELLOW         %]Yellow[% RESET %]                                    [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] BLUE                           [% BRIGHT WHITE %]│[% RESET %] [% BLUE           %]Blue[% RESET %]                                      [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] MAGENTA                        [% BRIGHT WHITE %]│[% RESET %] [% MAGENTA        %]Magenta[% RESET %]                                   [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] CYAN                           [% BRIGHT WHITE %]│[% RESET %] [% CYAN           %]Cyan[% RESET %]                                      [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] WHITE                          [% BRIGHT WHITE %]│[% RESET %] [% WHITE          %]White[% RESET %]                                     [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] BRIGHT BLACK                   [% BRIGHT WHITE %]│[% RESET %] [% BRIGHT BLACK   %]Bright black[% RESET %]                   (dim grey) [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] BRIGHT RED                     [% BRIGHT WHITE %]│[% RESET %] [% BRIGHT RED     %]Bright red[% RESET %]                                [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] BRIGHT GREEN                   [% BRIGHT WHITE %]│[% RESET %] [% BRIGHT GREEN   %]Lime[% RESET %]                                      [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] BRIGHT YELLOW                  [% BRIGHT WHITE %]│[% RESET %] [% BRIGHT YELLOW  %]Bright Yellow[% RESET %]                             [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] BRIGHT BLUE                    [% BRIGHT WHITE %]│[% RESET %] [% BRIGHT BLUE    %]Bright blue[% RESET %]                               [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] BRIGHT MAGENTA                 [% BRIGHT WHITE %]│[% RESET %] [% BRIGHT MAGENTA %]Bright magenta[% RESET %]                            [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] BRIGHT CYAN                    [% BRIGHT WHITE %]│[% RESET %] [% BRIGHT CYAN    %]Bright cyan[% RESET %]                               [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] BRIGHT WHITE                   [% BRIGHT WHITE %]│[% RESET %] [% BRIGHT WHITE   %]Bright white[% RESET %]                              [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] COLOR 0 - 231                  [% BRIGHT WHITE %]│[% RESET %] X-Term256 colors    (use -c to see these) [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] GREY 0 - 23                    [% BRIGHT WHITE %]│[% RESET %] Levels of grey  [% GREYDIENT %]  [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] RGB 0-255,0-255,0-255          [% BRIGHT WHITE %]│[% RESET %] X-Term256 24 bit color (R,G,B)            [% BRIGHT WHITE %]│[% RESET %]
╞══[% B_BLACK %] [% BOLD %][% ORANGE %]BACKGROUND [% RESET %][% BRIGHT WHITE %]══════════════════╪═══════════════════════════════════════════╡[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] B_DEFAULT                      [% BRIGHT WHITE %]│[% RESET %] Default background color                  [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] B_BLACK                        [% BRIGHT WHITE %]│[% RESET %] [% B_BLACK          %] Black          [% RESET %]                          [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] B_RED                          [% BRIGHT WHITE %]│[% RESET %] [% B_RED            %] Red            [% RESET %]                          [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] B_GREEN                        [% BRIGHT WHITE %]│[% RESET %] [% B_GREEN          %][% BLACK %] Green          [% RESET %]                          [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] B_YELLOW                       [% BRIGHT WHITE %]│[% RESET %] [% B_YELLOW         %] Yellow         [% RESET %]                          [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] B_BLUE                         [% BRIGHT WHITE %]│[% RESET %] [% B_BLUE           %] Blue           [% RESET %]                          [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] B_MAGENTA                      [% BRIGHT WHITE %]│[% RESET %] [% B_MAGENTA        %] Magenta        [% RESET %]                          [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] B_CYAN                         [% BRIGHT WHITE %]│[% RESET %] [% B_CYAN           %][% BLACK %] Cyan           [% RESET %]                          [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] B_WHITE                        [% BRIGHT WHITE %]│[% RESET %] [% B_WHITE          %][% BLACK %] White          [% RESET %]                          [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] B_PINK                         [% BRIGHT WHITE %]│[% RESET %] [% B_PINK           %][% BLACK %] Hot pink       [% RESET %]                          [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] B_ORANGE                       [% BRIGHT WHITE %]│[% RESET %] [% B_ORANGE         %][% BLACK %] Orange         [% RESET %]                          [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] B_NAVY                         [% BRIGHT WHITE %]│[% RESET %] [% B_NAVY           %] Deep blue      [% RESET %]                          [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] BRIGHT B_BLACK                 [% BRIGHT WHITE %]│[% RESET %] [% BRIGHT B_BLACK   %] Bright black   [% RESET %]                   (grey) [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] BRIGHT B_RED                   [% BRIGHT WHITE %]│[% RESET %] [% BRIGHT B_RED     %][% BLACK %] Bright red     [% RESET %]                          [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] BRIGHT B_GREEN                 [% BRIGHT WHITE %]│[% RESET %] [% BRIGHT B_GREEN   %][% BLACK %] Lime           [% RESET %]                          [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] BRIGHT B_YELLOW                [% BRIGHT WHITE %]│[% RESET %] [% BRIGHT B_YELLOW  %][% BLACK %] Bright yellow  [% RESET %]                          [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] BRIGHT B_BLUE                  [% BRIGHT WHITE %]│[% RESET %] [% BRIGHT B_BLUE    %][% BLACK %] Bright blue    [% RESET %]                          [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] BRIGHT B_MAGENTA               [% BRIGHT WHITE %]│[% RESET %] [% BRIGHT B_MAGENTA %][% BLACK %] Bright magenta [% RESET %]                          [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] BRIGHT B_CYAN                  [% BRIGHT WHITE %]│[% RESET %] [% BRIGHT B_CYAN    %][% BLACK %] Bright cyan    [% RESET %]                          [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] BRIGHT B_WHITE                 [% BRIGHT WHITE %]│[% RESET %] [% BRIGHT B_WHITE   %][% BLACK %] [% BLACK %]Bright white   [% RESET %]                          [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] B_COLOR 0 - 231                [% BRIGHT WHITE %]│[% RESET %] X-Term256 background colors               [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] B_GREY 0 - 23                  [% BRIGHT WHITE %]│[% RESET %] Levels of grey  [% GREYDIENT %]  [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] B_RGB 0-255,0-255,0-255        [% BRIGHT WHITE %]│[% RESET %] X-Term256 24 bit color (R,G,B)            [% BRIGHT WHITE %]│[% RESET %]
╞══[% B_BLACK %] [% BOLD %][% BRIGHT BLUE %]HORIZONTAL RULES [% RESET %][% BRIGHT WHITE %]════════════╪═══════════════════════════════════════════╡[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] HORIZONTAL RULE RED            [% BRIGHT WHITE %]│[% BLACK %][% B_RED            %] A solid line of red background            [% RESET %][% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] HORIZONTAL RULE GREEN          [% BRIGHT WHITE %]│[% BLACK %][% B_GREEN          %] A solid line of green background          [% RESET %][% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] HORIZONTAL RULE YELLOW         [% BRIGHT WHITE %]│[% BLACK %][% B_YELLOW         %] A solid line of yellow background         [% RESET %][% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] HORIZONTAL RULE BLUE           [% BRIGHT WHITE %]│[% BLACK %][% B_BLUE           %] A solid line of blue background           [% RESET %][% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] HORIZONTAL RULE MAGENTA        [% BRIGHT WHITE %]│[% BLACK %][% B_MAGENTA        %] A solid line of magenta background        [% RESET %][% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] HORIZONTAL RULE CYAN           [% BRIGHT WHITE %]│[% BLACK %][% B_CYAN           %] A solid line of cyan background           [% RESET %][% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] HORIZONTAL RULE PINK           [% BRIGHT WHITE %]│[% BLACK %][% B_PINK           %] A solid line of hot pink background       [% RESET %][% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] HORIZONTAL RULE ORANGE         [% BRIGHT WHITE %]│[% BLACK %][% B_ORANGE         %] A solid line of orange background         [% RESET %][% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] HORIZONTAL RULE WHITE          [% BRIGHT WHITE %]│[% BLACK %][% B_WHITE          %] A solid line of white background          [% RESET %][% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] HORIZONTAL RULE BRIGHT RED     [% BRIGHT WHITE %]│[% BLACK %][% BRIGHT B_RED     %] A solid line of bright red background     [% RESET %][% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] HORIZONTAL RULE BRIGHT GREEN   [% BRIGHT WHITE %]│[% BLACK %][% BRIGHT B_GREEN   %] A solid line of bright green background   [% RESET %][% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] HORIZONTAL RULE BRIGHT YELLOW  [% BRIGHT WHITE %]│[% BLACK %][% BRIGHT B_YELLOW  %] A solid line of bright yellow background  [% RESET %][% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] HORIZONTAL RULE BRIGHT BLUE    [% BRIGHT WHITE %]│[% BLACK %][% BRIGHT B_BLUE    %] A solid line of bright blue background    [% RESET %][% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] HORIZONTAL RULE BRIGHT MAGENTA [% BRIGHT WHITE %]│[% BLACK %][% BRIGHT B_MAGENTA %] A solid line of bright magenta background [% RESET %][% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] HORIZONTAL RULE BRIGHT CYAN    [% BRIGHT WHITE %]│[% BLACK %][% BRIGHT B_CYAN    %] A solid line of bright cyan background    [% RESET %][% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] HORIZONTAL RULE BRIGHT WHITE   [% BRIGHT WHITE %]│[% BLACK %][% BRIGHT B_WHITE   %] A solid line of bright white background   [% RESET %][% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]╰────────────────────────────────┴───────────────────────────────────────────╯[% RESET %]

TOKENS
###

$to =~ s/\[\% GREYDIENT \%\]/$greydient/g;
if ($version) {
    $| = 1;
    $ansi->ansi_output($text);
} elsif ($help) {
    $| = 1;
    $ansi->ansi_output($small);
} elsif ($tokens) {
    $ansi->ansi_output($to);
} elsif ($rawtokens) {
    print "\n╔", '═' x 131, "╗\n";
    $ansi->ansi_output('║[% B_BLACK %][% BRIGHT YELLOW %]' . ' ' x 46 . 'THE FOLLOWING ARE THE AVAILABLE TOKENS' . ' ' x 47 . "[% RESET %]║\n");
    print '╠', '═' x 32, '╦', '═' x 32, '╦', '═' x 32, '╦', '═' x 32, '╣', "\n";
    printf('║ %-31s║ %-31s║ %-31s║ %-31s║', 'COLOR 0 - COLOR 231', 'B_COLOR 0 - B_COLOR 231', 'GREY 0 - GREY 28', 'B_GREY 0 - B_GREY 28');
    print "\n║";
    my $width = 4;
    my $count = 1;
    foreach my $token (sort(keys %{ $ansi->{'ansi_sequences'} })) {
        next if ($token =~ /COLOR |GREY /);
        printf(' %-31s', $token);
        $count++;
        if ($count > $width) {
            $count = 1;
            print "║\n║";
        } else {
            print '║';
        }
    } ## end foreach my $token (sort(keys...))
    print "\r╚", '═' x 32, '╩', '═' x 32, '╩', '═' x 32, '╩', '═' x 32, '╝', "\n\n";
} elsif ($Dump) {
    my $temp = "\n\n";
    my @names;
    my $search = (scalar(@ARGV)) ? pop(@ARGV) : undef;
    if (defined($search) && $search ne '') {
		$ansi->ansi_output(charnames::string_vianame($search));
    } else {
        my $start = $ansi->{'start'};
        my $finish = $ansi->{'finish'};
		foreach my $code ($start .. $finish) {
            next if (($code >= 0x2BFF && $code <= 0x1F2FF) || ($code >= 0x1F8C0 && $code <= 0x1F8FF));
            my $name = charnames::viacode($code);
			$ansi->ansi_output(charnames::string_vianame($name) . ' ');
        }
    }
} elsif ($unicode) {
    my $search = (scalar(@ARGV)) ? pop(@ARGV) : undef;
    $ansi->ansi_output("\nNOTE:  Not all terminals will support all characters\n" . '[% COLOR 52 %]╭───────╮[% RESET %]' . "\n");
    if (defined($search)) {
        $ansi->ansi_output('[% COLOR 52 %]│[% BRIGHT CYAN %]Unicode[% COLOR 52 %]│[% RESET %]' . "\n");
        $ansi->ansi_output('[% COLOR 52 %]├───────┼─────[% RESET %]' . "\n");
        $ansi->ansi_output('[% COLOR 52 %]│[% BRIGHT WHITE %]' . sprintf('%6s',$search) . ' [% COLOR 52 %]│[% RESET %] ' . charnames::string_vianame(charnames::viacode(hex($search))));
        print "\n";
        $ansi->ansi_output('[% COLOR 52 %]╰───────┴─────[% RESET %]' . "\n\n");
    } else {
        $ansi->ansi_output('[% COLOR 52 %]│[% BRIGHT CYAN %]Unicode[% COLOR 52 %]│[% RESET %][% BRIGHT WHITE %] 0 1 2 3 4 5 6 7 8 9 A B C D E F[% RESET %]' . "\n");
        $ansi->ansi_output('[% COLOR 52 %]├───────┼───────────────────────────────────[% RESET %]' . "\n");
        my $count = 0;
        my $start = $ansi->{'start'};
        my $finish = $ansi->{'finish'};
        foreach my $code ($start .. $finish) {
            next if (($code >= 0x2BFF && $code <= 0x1F2FF) || ($code >= 0x1F8C0 && $code <= 0x1F8FF));
            my $name = charnames::viacode($code);
            my $char = charnames::string_vianame($name);
            my $hcode = substr(sprintf('0x%X',$code),2);
            if ($hcode ne '') {
                if ($hcode eq '1F300') {
                    print "\n";
                    $count = 0;
                }
                if ($code >= 0x20E0 && $code <= 0x20EF) {
                    unless ($count) {
                        $ansi->ansi_output('[% COLOR 52 %]│[% BRIGHT WHITE %]  ' . $hcode . ' [% COLOR 52 %]│[% RESET %]   ' . $char);
                    } else {
                        $ansi->ansi_output('  ' . $char);
                    }
                } elsif ($code < 0x2BFF) {
                    unless ($count) {
                        $ansi->ansi_output('[% COLOR 52 %]│[% BRIGHT WHITE %]  ' . $hcode . ' [% COLOR 52 %]│[% RESET %]  ' . $char);
                    } else {
                        $ansi->ansi_output(' ' . $char);
                    }
                } else {
                    unless ($count) {
                        $ansi->ansi_output('[% COLOR 52 %]│[% BRIGHT WHITE %] ' . $hcode . ' [% COLOR 52 %]│[% RESET %] ' . $char);
                    } else {
                        $ansi->ansi_output(' ' . $char);
                    }
                } ## end else [ if ($name =~ /^U0(20D.|20E.|20F0)/)]
                $count++;
                if ($count > 15) {
                    $count = 0;
                    print "\n";
                }
            } ## end if ($name ne '')
        }
        $ansi->ansi_output('[% COLOR 52 %]╰───────┴───────────────────────────────────[% RESET %]' . "\n\n");
    }
#    $ansi->ansi_output($temp);
} elsif ($symbols) {
    my $start  = $ansi->{'start'};
    my $finish = $ansi->{'finish'};
    my @names;
    my $search = (scalar(@ARGV)) ? pop(@ARGV) : undef;
    my $size = 0;
    if (defined($search) && $search ne '') {
        push(@names, $search);
    } else {
        foreach my $code ($start .. $finish) {
            next if (($code >= 0x2BFF && $code <= 0x1F2FF) || ($code >= 0x1F8C0 && $code <= 0x1F8FF));
            my $name = charnames::viacode($code);
            push(@names, $name);
            $size = max($size, length($name));
        }
    }
    $ansi->ansi_output("\nNOTE:  Not all terminals will support all characters\n" . '[% COLOR 52 %]╭───────┬─' . '─' x $size . '─╮[% RESET %]' . "\n");
    $ansi->ansi_output('[% COLOR 52 %]│[% B_BLACK %][% CYAN %]Unicode[% RESET %][% COLOR 52 %]│[% B_BLACK %]' . ' ' x ($size - 20) . '[% BRIGHT YELLOW %]Character Token Names [% RESET %]' . "[% COLOR 52 %]│[% RESET %]\n");
    $ansi->ansi_output('[% COLOR 52 %]├───────┼─' . '─' x $size . "─┤[% RESET %]\n");
    while (scalar(@names)) {
        my $name = shift(@names);
        if ($name ne '') {
            if ($name =~ /^COMBINING/) {
                $ansi->ansi_output(sprintf('%s│ %s%05X %s│%s %' . $size . 's %s│%s   %s', '[% COLOR 52 %]', '[% RESET %]', charnames::vianame($name), '[% COLOR 52 %]', '[% RESET %]', $name, '[% COLOR 52 %]', '[% RESET %]', charnames::string_vianame($name)) . "\n");
            } else {
                $ansi->ansi_output(sprintf('%s│ %s%05X %s│%s %' . $size . 's %s│%s %s', '[% COLOR 52 %]', '[% RESET %]', charnames::vianame($name), '[% COLOR 52 %]', '[% RESET %]', $name, '[% COLOR 52 %]', '[% RESET %]', charnames::string_vianame($name)) . "\n");
            }
        } ## end if ($name ne '')
    } ## end while (scalar(@names))
    $ansi->ansi_output('[% COLOR 52 %]╰───────┴─' . '─' x $size . '─╯[% RESET %]' . "\n\n");
} elsif ($colors) {
    my $grey   = '[% GREY 8 %]';
    my $off    = '[% RESET %]';
    my $string = '';
    $string .= "\n" . '[% BRIGHT WHITE %] ANSI Colors and GREY colors (requires a terminal with 256 color support for all colors)' . $off . "\n";
    $string .= $grey . '╭─────┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──╮' . $off . "\n";
    $string .= $grey . '│' . $off . 'COLOR';
    foreach my $i (0 .. 35) {
        $string .= $grey . '│' . $off . sprintf('%02d', $i);
    }
    $string .= $grey . "│\n├─────┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┤$off\n";
    $string .= sprintf('%s│%s %4d%s│%s', $grey, $off, 0, $grey, $off);
    foreach my $i (0 .. 35) {
        if ($i <= 15) {
            $string .= chr(27) . '[48;5;' . $i . 'm  ' . $off . $grey . '│' . $off;
        } else {
            $string .= '  ' . $grey . '│' . $off;
        }
    } ## end foreach my $i (0 .. 35)
    foreach my $i (0 .. 6) {
        my $_i = ($i * 36) + 16;
        $string .= "\n" . $grey . '├─────┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┤' . $off . "\n";
        if ($i == 6) {
            $string .= $grey . '│' . $off . 'GREY ' . $grey . '│' . $off;
        } else {
            $string .= sprintf("%s│%s %4d%s│%s", $grey, $off, $_i, $grey, $off);
        }
        foreach my $j (0 .. 35) {
            $string .= chr(27) . '[48;5;' . ($_i + $j) . 'm  ' . chr(27) . '[m' . $grey . '│' . $off;
        }
    } ## end foreach my $i (0 .. 6)
    $string .= "\n" . $grey . '╰─────┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──╯' . $off . "\n\n";
    $string .= 'RGB and B_RGB take three values (0 - 255) for [% RED %]RED[% RESET %],[% GREEN %]GREEN[% RESET %],[% BLUE %]BLUE[% RESET %] for full 24 bit color' . "\n";
    $ansi->ansi_output($string);
    print 'For example:  [% RGB 255,255,255 %] WHITE [% RESET %] will show as ';
    $ansi->ansi_output('[% RGB 255,255,255 %] WHITE [% RESET %]' . "\n");
    print '              [% RGB 255,128,192 %] COLOR [% RESET %] will show as ';
    $ansi->ansi_output('[% RGB 255,128,192 %] COLOR [% RESET %]' . "\n");
} else {    # Output file to STDOUT
    my $file = $ARGV[0];
    if (defined($file) && -e $file) {
        my $size = -s $file;
        open(my $FILE, '<', $file);
        binmode($FILE, ":encoding(UTF-8)");
        read($FILE, my $text, $size);
        close($FILE);
        $ansi->ansi_output($text);
    } else {
        $ansi->ansi_output($small);
        $| = 1;
    }
} ## end else [ if ($version) ]

exit(0);

__END__

=head1 NAME

ANSI Encode

=head1 SYNOPSIS

A markup language to generate basic ANSI text

=head1 USAGE

 ansi_encode.pl file

=head1 OPTIONS

=over 4

=item --B<version> or -B<v>

Shows name, version information and brief licensing information.

=item --B<help> or -B<h>

Simple usage and options documentation

=item --B<tokens> or -B<y>

Shows the most used tokens available.  A token is encapsulated within [% and %] (with at lease one space on each side)

=item --B<rawtokens> or B<r>

Raw dump of useable tokens.

=item --B<symbols> or -B<s> [search]

Similar to "tokens", but instead shows special symbol character tokens names.

You may also add a search string to shorten the list.

IT IS HIGHLY SUGGESTED YOU USE A SEARCH STRING.

=item --B<unicode> or -B<u> [search]

Similar to "tokens", but instead shows special symbol characters by unicode.

You may also add a search string to shorten the list.

IT IS HIGHLY SUGGESTED YOU USE A SEARCH STRING.

=item --B<dump> or -B<d> [search]

Does a raw dump of the symbols.

=back

=over 8

[% RED %]This is written in red[% RESET %]

B<RESET> changes output text to normal.

=back

=head1 TOKENS

=head2 GENERAL

 RETURN     = ASCII RETURN (13)
 LINEFEED   = ASCII LINEFEED (10)
 NEWLINE    = RETURN + LINEFEED (13 + 10)
 CLS        = Places cursor at top left, screen cleared
 CLEAR      = Clear screen only, cursor remains where it was
 CLEAR LINE = Clear to the end of line
 CLEAR DOWN = Clear down from current cursor position
 CLEAR UP   = Clear up from current cursor position
 RESET      = Reset all colors and attributes

=head2 CURSOR

 HOME        = Moves the cursor to the location 1,1.
 UP          = Moves cursor up one step
 DOWN        = Moves cursor down one step
 RIGHT       = Moves cursor right one step
 LEFT        = Moves cursor left one step
 SAVE        = Save cursor position
 RESTORE     = Place cursor at saved position
 BOLD        = Bold text (not all terminals support this)
 FAINT       = Faded text (not all terminals support this)
 ITALIC      = Italicized text (not all terminals support this)
 UNDERLINE   = Underlined text
 SLOW BLINK  = Slow cursor blink
 RAPID BLINK = Rapid cursor blink

=head2 ATTRIBUTES

 INVERT       = Invert text (flip background and foreground attributes)
 REVERSE      = Reverse
 CROSSED OUT  = Crossed out
 DEFAULT FONT = Default font

=head2 FRAMES

 BOX & ENDBOX = Draw a frame

=head2 COLORS

 NORMAL = Sets colors to default

=head2 FOREGROUND

 BLACK          = Black
 RED            = Red
 PINK           = Hot pink
 ORANGE         = Orange
 NAVY           = Deep blue
 GREEN          = Green
 YELLOW         = Yellow
 BLUE           = Blue
 MAGENTA        = Magenta
 CYAN           = Cyan
 WHITE          = White
 DEFAULT        = Default foreground color
 BRIGHT BLACK   = Bright black (dim grey)
 BRIGHT RED     = Bright red
 BRIGHT GREEN   = Lime
 BRIGHT YELLOW  = Bright Yellow
 BRIGHT BLUE    = Bright blue
 BRIGHT MAGENTA = Bright magenta
 BRIGHT CYAN    = Bright cyan
 BRIGHT WHITE   = Bright white

=head2 BACKGROUND

 B_BLACK          = Black
 B_RED            = Red
 B_GREEN          = Green
 B_YELLOW         = Yellow
 B_BLUE           = Blue
 B_MAGENTA        = Magenta
 B_CYAN           = Cyan
 B_WHITE          = White
 B_DEFAULT        = Default background color
 B_PINK           = Hot pink
 B_ORANGE         = Orange
 B_NAVY           = Deep blue
 BRIGHT B_BLACK   = Bright black (grey)
 BRIGHT B_RED     = Bright red
 BRIGHT B_GREEN   = Lime
 BRIGHT B_YELLOW  = Bright yellow
 BRIGHT B_BLUE    = Bright blue
 BRIGHT B_MAGENTA = Bright magenta
 BRIGHT B_CYAN    = Bright cyan
 BRIGHT B_WHITE   = Bright white

=head2 HORIZONAL RULES

Makes a solid blank line, the full width of the screen with the selected background color

 HORIZONTAL RULE RED             = A solid line of red background
 HORIZONTAL RULE GREEN           = A solid line of green background
 HORIZONTAL RULE YELLOW          = A solid line of yellow background
 HORIZONTAL RULE BLUE            = A solid line of blue background
 HORIZONTAL RULE MAGENTA         = A solid line of magenta background
 HORIZONTAL RULE CYAN            = A solid line of cyan background
 HORIZONTAL RULE PINK            = A solid line of hot pink background
 HORIZONTAL RULE ORANGE          = A solid line of orange background
 HORIZONTAL RULE WHITE           = A solid line of white background
 HORIZONTAL RULE BRIGHT RED      = A solid line of bright red background
 HORIZONTAL RULE BRIGHT GREEN    = A solid line of bright green background
 HORIZONTAL RULE BRIGHT YELLOW   = A solid line of bright yellow background
 HORIZONTAL RULE BRIGHT BLUE     = A solid line of bright blue background
 HORIZONTAL RULE BRIGHT MAGENTA  = A solid line of bright magenta background
 HORIZONTAL RULE BRIGHT CYAN     = A solid line of bright cyan background
 HORIZONTAL RULE BRIGHT WHITE    = A solid line of bright white background

=head1 AUTHOR & COPYRIGHT

Richard Kelsch

 Copyright (C) 2025 Richard Kelsch
 All Rights Reserved
 Perl Artistic License

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

L<http://www.perlfoundation.org/artistic_license_2_0>

=cut
