#!/usr/bin/env perl

#######################################################################
#            _   _  _____ _____   ______                     _        #
#      ╱╲   | ╲ | |╱ ____|_   _| |  ____|                   | |       #
#     ╱  ╲  |  ╲| | (___   | |   | |__   _ __   ___ ___   __| | ___   #
#    ╱ ╱╲ ╲ | . ` |╲___ ╲  | |   |  __| | '_ ╲ ╱ __╱ _ \ / _` |╱ _ ╲  #
#   ╱ ____ ╲| |╲  |____) |_| |_  | |____| | | | (_| (_) | (_| |  __╱  #
#  ╱_╱    ╲_╲_| ╲_|_____╱|_____| |______|_| |_|╲___╲___╱ ╲__,_|╲___|  #
#######################################################################
#                     Written By Richard Kelsch                       #
#                  © Copyright 2025 Richard Kelsch                    #
#                        All Rights Reserved                          #
#######################################################################
# 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 3 of the  #
# License, or (at your option) any later version.                     #
#                                                                     #
# This program is distributed in the hope that it will be useful, but #
# WITHOUT ANY WARRANTY; without even the implied warranty of          #
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU   #
# General Public License for more details.                            #
#                                                                     #
# You should have received a copy of the GNU General Public License   #
# along with this program.  If not, see:                              #
#                                     <http://www.gnu.org/licenses/>. #
#######################################################################

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 $full      = FALSE;
my $Dump      = FALSE;

GetOptions(
    'version'   => \$version,
    'help'      => \$help,
    'tokens'    => \$tokens,
    'rawtokens' => \$rawtokens,
    'colors'    => \$colors,
    'symbols'   => \$symbols,
    'full'      => \$full,
    'dump'      => \$Dump,
    'unicode'   => \$unicode,
);
###
my $text = <<'VERSION';
[% CLEAR %][% 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_ANSI17 %]                         Written By [% BRIGHT YELLOW %]Richard Kelsch[% RESET %][% B_ANSI17 %]                           [% RESET %][% ORANGE %]║[% RESET %]
[% ORANGE %]║[% RESET %][% B_ANSI17 %]                       Copyright ©[% GREEN %]2025 [% BRIGHT YELLOW %]Richard Kelsch[% RESET %][% B_ANSI17 %]                        [% RESET %][% ORANGE %]║[% RESET %]
[% ORANGE %]║[% RESET %][% B_ANSI17 %]                            All Rights Reserved                              [% RESET %][% ORANGE %]║[% RESET %]
[% ORANGE %]║[% RESET %][% B_ANSI17 %]                   GNU General Public License version 3                      [% RESET %][% ORANGE %]║[% RESET %]
[% ORANGE %]║[% RESET %][% B_ANSI17 %]                               Version [% GREEN %]XXXX[% RESET %][% B_ANSI17 %]                                  [% RESET %][% ORANGE %]║[% RESET %]
[% ORANGE %]╚═════════════════════════════════════════════════════════════════════════════╝[% RESET %]

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

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

###
my $small = <<'SMALL';
[% CLEAR %]╔═════════════════════════════════════════════════════════════════════════╗
║[% 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_ANSI52 %][% BRIGHT YELLOW %] DESCRIPTION                                                             [% RESET %]║
║     Markup text to ANSI encoder.                                        ║
║                                                                         ║
║[% B_ANSI52 %][% BRIGHT YELLOW %] USAGE                                                                   [% RESET %]║
║     [% CYAN %]ansi-encode[% RESET %] [options] [text file]                                   ║
║                                                                         ║
║[% B_ANSI52 %][% 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                                         ║
║                                                                         ║
║     -[% PINK %]f[% RESET %] or --[% PINK %]full[% RESET %]                                                        ║
║         Loads the full symbol table.  It will slow down initialization. ║
╚═════════════════════════════════════════════════════════════════════════╝
SMALL
###
my $greydient = '';    # Yes, the spelling is intentional
foreach my $c (0 .. 23) {
    $greydient .= "[% B_GREY$c %] ";
}
$greydient .= '[% RESET %]';
###
my $to = <<'TOKENS';
[% CLEAR %]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 %] 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 %] [% GREY7 %]------------------------------[% 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_GREY8        %][% 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 %] ANSI0 - ANSI231                [% BRIGHT WHITE %]│[% RESET %] X-Term256 colors    (use -c to see these) [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] GREY0 - GREY23                 [% BRIGHT WHITE %]│[% RESET %] Levels of grey  [% GREYDIENT %]  [% 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_ANSI0 - B_ANSI231            [% BRIGHT WHITE %]│[% RESET %] X-Term256 background colors               [% BRIGHT WHITE %]│[% RESET %]
[% BRIGHT WHITE %]│[% RESET %] B_GREY0 - B_GREY23             [% BRIGHT WHITE %]│[% RESET %] Levels of grey  [% GREYDIENT %]  [% 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║', 'ANSI0 - ANSI231', 'B_ANSI0 - B_ANSI231', 'GREY0 - GREY28', 'B_GREY0 - B_GREY28');
    print "\n║";
    my $width = 4;
    my $count = 1;
    foreach my $token (sort(keys %{ $ansi->{'ansi_sequences'} })) {
        next if ($token =~ /ANSI|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 = pop(@ARGV);
    if (defined($search) && $search ne '') {
        @names = grep(/$search/i, (sort(keys %{ $ansi->{'characters'}->{'NAME'} })));
    } else {
        @names = (sort(keys %{ $ansi->{'characters'}->{'NAME'} }));
    }
    while (scalar(@names)) {
        my $name = shift(@names);
        $temp .= $ansi->{'characters'}->{'NAME'}->{$name} . ' ';
    }
    $temp .= "\n\n";
    $ansi->ansi_output($temp);
} elsif ($unicode) {
    my @names;
    my $search = pop(@ARGV);
    if (defined($search) && $search ne '') {
        @names = grep(/$search/i, (sort(keys %{ $ansi->{'characters'}->{'UNICODE'} })));
    } else {
        @names = (sort(keys %{ $ansi->{'characters'}->{'UNICODE'} }));
    }
    my $size = 0;
    foreach my $name (@names) {
        $size = max($size, length($name));
    }
    my $temp = "\nNOTE:  Not all terminals will support all characters\n" . '[% ANSI52 %]╭───────╮[% RESET %]' . "\n";
    $temp .= '[% ANSI52 %]│[% BRIGHT CYAN %]Unicode[% ANSI52 %]│[% RESET %][% BRIGHT WHITE %] 0 1 2 3 4 5 6 7 8 9 A B C D E F[% RESET %]' . "\n";
    $temp .= '[% ANSI52 %]├───────┼───────────────────────────────────[% RESET %]' . "\n";
    my $count = 0;
    while (scalar(@names)) {
        my $name = shift(@names);
        if ($name ne '') {
            if (($name eq 'U1F341' && !$full) || ($name eq 'U1F300' && $full)) {
                $temp .= "\n";
                $count = 0;
            }
            if ($name =~ /^U0(20D.|20E.|20F0)/) {
                unless ($count) {
                    $temp .= '[% ANSI52 %]│[% BRIGHT WHITE %]' . $name . ' [% ANSI52 %]│[% RESET %]  ' . $ansi->{'characters'}->{'UNICODE'}->{$name};
                } else {
                    $temp .= '  ' . $ansi->{'characters'}->{'UNICODE'}->{$name};
                }
            } else {
                unless ($count) {
                    $temp .= '[% ANSI52 %]│[% BRIGHT WHITE %]' . $name . ' [% ANSI52 %]│[% RESET %] ' . $ansi->{'characters'}->{'UNICODE'}->{$name};
                } else {
                    $temp .= ' ' . $ansi->{'characters'}->{'UNICODE'}->{$name};
                }
            } ## end else [ if ($name =~ /^U0(20D.|20E.|20F0)/)]
            $count++;
            if ($count > 15) {
                $count = 0;
                $temp .= "\n";
            }
        } ## end if ($name ne '')
    } ## end while (scalar(@names))
    $temp .= "\n" unless ($full);
    $temp .= '[% ANSI52 %]╰───────┴───────────────────────────────────[% RESET %]' . "\n\n";
    $ansi->ansi_output($temp);
} elsif ($symbols) {
    my @names;
    my $search = pop(@ARGV);
    if (defined($search) && $search ne '') {
        @names = grep(/$search/i, (sort(keys %{ $ansi->{'characters'}->{'NAME'} })));
    } else {
        @names = (sort(keys %{ $ansi->{'characters'}->{'NAME'} }));
    }
    my $size = 0;
    foreach my $name (@names) {
        $size = max($size, length($name));
    }
    my $temp = "\nNOTE:  Not all terminals will support all characters\n" . '[% ANSI52 %]╭───────┬─' . '─' x $size . '─╮[% RESET %]' . "\n";
    $temp .= '[% ANSI52 %]│[% B_BLACK %][% CYAN %]Unicode[% RESET %][% ANSI52 %]│[% B_BLACK %]' . ' ' x ($size - 20) . '[% BRIGHT YELLOW %]Character Token Names [% RESET %]' . "[% ANSI52 %]│[% RESET %]\n";
    $temp .= '[% ANSI52 %]├───────┼─' . '─' x $size . "─┤[% RESET %]\n";
    while (scalar(@names)) {
        my $name = shift(@names);
        if ($name ne '') {
            if ($name =~ /^COMBINING/) {
                $temp .= sprintf('%s│%sU%05X %s│%s %' . $size . 's %s│%s   %s', '[% ANSI52 %]', '[% RESET %]', charnames::vianame($name), '[% ANSI52 %]', '[% RESET %]', $name, '[% ANSI52 %]', '[% RESET %]', $ansi->{'characters'}->{'NAME'}->{$name}) . "\n";
            } else {
                $temp .= sprintf('%s│%sU%05X %s│%s %' . $size . 's %s│%s %s', '[% ANSI52 %]', '[% RESET %]', charnames::vianame($name), '[% ANSI52 %]', '[% RESET %]', $name, '[% ANSI52 %]', '[% RESET %]', $ansi->{'characters'}->{'NAME'}->{$name}) . "\n";
            }
        } ## end if ($name ne '')
    } ## end while (scalar(@names))
    $temp .= '[% ANSI52 %]╰───────┴─' . '─' x $size . '─╯[% RESET %]' . "\n\n";
    $ansi->ansi_output($temp);
} elsif ($colors) {
    my $grey   = '[% GREY8 %]';
    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 . 'ANSI';
    foreach my $i (0 .. 35) {
        $string .= $grey . '│' . $off . sprintf('%02d', $i);
    }
    $string .= $grey . "│\n├────┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┤$off\n";
    $string .= sprintf('%s│%s %3d%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 %3d%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";
    $ansi->ansi_output($string);
} 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 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>

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

=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.

=item --B<full> or -B<f>

Enables the full symbol tree.  Initialization is slower.  It his highly recommended that you use a search string.

=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)
 CLEAR      = Places cursor at top left, screen cleared
 CLS        = Same as CLEAR
 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

 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

=cut
