
*** Escape sequences for ALL platforms including a stock AMIGA A1200(HD). ***
-----------------------------------------------------------------------------

  Preface:-
  ---------

(Apologies for any typos, spelling, and inaccuracies...)

These escape sequences are non[-]standard in this code format but result in
the standard format required to work.
They are the most useful and from the URLs:-

		https://www.xfree86.org/current/ctlseqs.html
AND......
		https://en.wikipedia.org/wiki/ANSI_escape_code

  !!! IMPORTANT !!!
  -----------------

If you have uploaded an earlier version of this archive then DELETE ANY
'ESC.pyc' and/or 'ESC.pyo' files that exist so that new current versions can
be created, either inside the'__pycache__ folder or the folder where 'ESC.py'
is. Also there WILL be a random terminal that will be unable to use some of
the more advanced escape sequences so be well aware.

  !!! REMEMBER !!!
  ----------------

The Classic AMIGA does not have the luxuries of the current, (as of the
above date), Python Version 3.15.0rc3 and its massive (C)2026_Pytho[-]System,
so these recipes might help towards using what we have and inspiring others
to add to them. They can be anything, not just mathematics, (like my others).
The difficulty is learning and memorising _ALL_ of the differences between
Python Versions, (1.3.0), 1.4.0 to 3.15.0rc3; there are a great many, believe
me!
(Creating workarounds has become second nature to me nowadays.)

A personal touch; many thanks to my wife who puts up with my coding antics
and all of the time it takes to create something new for we AMIGA fanatics.

=============================================================================

****************** General information about this project. ******************

  Hardware and OSes required:-
  ----------------------------

  Amiga environment:-
  -------------------
    Classic STOCK AMIGA A1200(HD), default OS3.0x install.
    FS-UAE on Intel APPLE OSX 10.15.x and GNU/Linux Mint Cinnamon 22.3.
    Standard default AMIGA OS_3.0.x install, or better still a highly
    expanded AMIGA with extra RAM will speed things up considerably.
    Python Version 1.4.0 on Classic AMIGA A1200(HD) OS3.0x:-

               https://aminet.net/package/dev/lang/Python_14

    This version that requires no extra hardware at all:-
                           'python_020_ieee'

    Python Version 1.5.2 to 2.0.1 on '030+ highly expanded AMIGAs OS3.0x.
    AmigaMicropython340 on Classic AMIGA A1200(HD) OS3.0x.

            https://aminet.net/package/dev/misc/AmigaMicropython

    Also as a matter of interest these Python scripts also work inside the
    excellent ADE, the *NIX emulation, but the STOCK AMIGA A1200(HD) needs
    at least an extra 4MB of FastRAM to do so:-

                   https://aminet.net/package/dev/gcc/ADE

  Other environments:-
  --------------------
    Any Python version from 2.x.x to 3.15.0rc3 on Intel APPLE OSX 10.15.7.
    Any Python Version from 1.3.0 to 3.12.x on GNU/LINUX MINT CINNAMON 22.3.

-----------------------------------------------------------------------------

  Platforms tested, or known to work on are:-
  -------------------------------------------

A) (1) A classic stock AMIGA A1200(HD) OS3.0x using Python 1.4.0 to 2.0.1,
       and, MicroPython 3.4.0 for the GENERIC section only, also up to
       Version 2.5.2 for NON[-]Classic AMIGAs.

B) (1) GNU/Linux Mint Cinnamon 22.3 using Python 1.3.0, and, 3.12.3 ALL
       sections as shown.
   (2) All of GENERIC, some of the INTERMEDIATE. and some of the ADVANCED
       also work inside a Console mode also.
   (3) FS-UAE emulating MY real AMIGA A1200(HD) with or without any
       expansions needed.

C) (1) APPLE OS_X 10.15.7 using Python 2.7.x, and, 3.15.0rc3 ALL sections as
       shown.
   (2) FS-UAE emulating MY real AMIGA A1200(HD) with or without any
       expansions needed.

D) (1) CygWin uses 'mintty' and does all GENERIC, some of the INTERMEDIATE,
       and some of ADVANCED sections. Not tested per[-]se but I have used
       them hard coded in another major project I did several years ago.
       See image 'Graphics_Cur_Col_TB_CygWin.jpg',

  Platforms NOT tested on are:-
  -----------------------------

A) (1) Windows PowerShell. To be honest, I DON'T REALLY CARE!
   (2) WSL or WSL-2, but they follow all normal *NIX rules so may work as
       normal.
   (3) WinUAE, using a Classic AMIGA OS3.0x emulation; however, as it is much
       more advanced than FS-UAE then there is NOT one reason why this WILL
       NOT work.

B) (1) APPLE 'M' series, there is no reason why not, but it cannot be added
       until thoroughly checked using the 'ESC.<function>_test()' files.
   (2) ASSUMING FS-UAE exists then there should be no problem in AMIGA mode.

C) (1) Android, using 'Termux'; manually hard coding some of the escape
       features work fine, so the GENERIC section could well be OK.

D) (1) Other non[-]prolific platforms.

-----------------------------------------------------------------------------

  !!!REMEMBER!!!
  --------------

There is an '[ESC.]generic()' function where you can use on ANY platform
having a terminal that accepts terminal escape codes. It defaults to an
AMIGA format, which is obscure enough to prove a point!

  !!!NOTICE!!!
  ------------

There will be some that will say '[ESC.]generic()' is a potential security
risk and to be aware.
They are probably correct except that this archive will never reach corporate
nor commercial level. If you are capable of manipulating any two platforms
from ANY AMIGA variant, UNIX, APPLE, GNU/Linux, Android, dare I say Windows,
and many others not mentioned then I am SURE you will be well aware and not
bothered!

It would be nice to have an email to let me know about any of the untested 
platforms above.

=============================================================================

***************************** The manual proper. ****************************

  What are the terminal escape codes?
  -----------------------------------

In a nutshell, (no pun), escape codes are used inside a terminal emulator or
console to modify text with different prefixes, (attributes). These prefixes
can change the colours of the text, make them bold/bright, underline, and
much more.

  Inside this module/source_file are three levels:-
  -------------------------------------------------

1) GENERIC; probably every *NIX environment has this level and includes the
   ancient AMIGA A1200(HD) OS3.0x, which is not *NIX like but has a subset
   of the 'xterm' escape commands in its own format.
   These also work OK inside any of the six GNU/LINUX Consoles available.

2) INTERMEDIATE; the VAST majority of *NIX style terminals are able to use
   this level, (and perhaps non[-]classic AMIGA systems too, but that can't
   be guaranteed. SO AMIGA USERS, YOU USE THESE AT YOUR OWN RISK).
   Some of these also work OK inside any of the six GNU/LINUX Consoles.

3) ADVANCED; the majority of *NIX style terminals can do these but be aware
   that some might not. The AMIGA family are NOT able to use these so don't
   try, (SO AMIGA USERS, DO NOT USE AT ALL!).

-----------------------------------------------------------------------------

  Usage, imported and sourced:-
  -----------------------------

  Installation:-
  --------------

1) Download the archive from AMINET:-

               https://aminet.net/package/dev/src/ESC_Sequences

2) Place the the 'ESC.py' file inside the same drawer/folder/directory as the
   'lib' folder, OR, where the Python executable is, OR, the current working 
   drawer/folder/directory you are working in, OR, finally all three if you
   wish.

3) Optional for Python Versions LESS THAN Python 3.0.0; copy '__init__.py'
   into the drawer/folder/directory you are working in. NOTE: This is NOT
   important so CAN be ignored.

-----------------------------------------------------------------------------

  As an 'import':-
  ----------------

1) Start whatever Python Version you have from, (1.3.0), 1.4.0 to 3.15.0rc3. 
   Because there is NO 'exit()' command in early Python Versions then from
   the Python prompt '>>> ' type:-

   >>> import sys
   >>> import ESC
   >>> dir(ESC)

2) As the file is import[ed] then 'ESC.' will be needed for all the proper
   functions inside the 'print()' statement/function; that is, NOT the
   '<function>_test()' functions. Then do what is inside 'Tutorial1.png'...

-----------------------------------------------------------------------------

  As an import[ed] * method:-
  ---------------------------

1) Start whatever Python Version you have from, (1.3.0), 1.4.0 to 3.15.0rc3. 
   Because there is NO 'exit()' command in early Python Versions then from
   the Python prompt '>>> ' type:-

   >>> import sys
   >>> from ESC import *
   >>> dir()

2) As you have asked for all the functions inside 'ESC' then the 'ESC.' part
   will NOT be needed. Then do what is inside 'Tutorial2.png'...

-----------------------------------------------------------------------------

  As a sourced file:-
  ------------------

1) Start whatever Python Version you have from, (1.3.0), 1.4.0 to 3.15.0rc3. 
   Because there is NO 'exit()' command in early Python Versions then from
   the Python prompt '>>> ' type:-

   >>> import sys
   >>> exec(open("ESC.py").read())
   >>> dir()

2) The end result is EXACTLY the same as for the 'import *' method above.

=============================================================================

**************************** The test functions. ****************************

All of the '<function>_test()' functions DO NOT require the 'print()'
statement/function at all to run, it is built in to the function.

   If 'ESC.py' is imported only, then to run each '<function_test()' is
   called from the Python prompt as:-

   >>> ESC.<function>_test()

   For example:-

   >>> ESC.po_test()

   If, however, you have used 'from ESC import *' OR sourced 'ESC.py' then
   'ESC' can be omitted completely and called from the Python prompt as:-

   >>> <function>_test()

   For example:-

   >>> po_test()

What was 'colours_test()' has now been changed to 'pfb_test()' to _marry_
with the 'pfb()' working function.

=============================================================================

*************************** Functions available. ****************************

---- Read the file 'Functions_Available_ATM.txt' file for FULL details! -----

  GENERIC:-
  ---------

default()			Displays ALL the Python builtin escape codes.

tr()				Terminal Reset.

ctr()				Complete Terminal Reset. 

cls()				Clear the screen/window, ONLY.

ra()				Reset all attributes only to the default.

pfb(prefix=0, fg=31, bg=40)	A Prefix, Foreground and Background colour
				function.

po(prefix=0)			Prefix Only; can be used multiple times to
				obtain your desired text effect[s].

ca(rows=1, cols=1)		Force the Cursor Anywhere. 

hm()				Cursor, HOME position ONLY.

cup(y), cdn(y), clt(x), crt(x)	Cursor, up, down, left, right.

generic(your_string='Text...')	Generic function to put raw escape codes in a
				complete string setup to use 'os.system()' to
				run it.

-----------------------------------------------------------------------------

  INTERMEDIATE:-
  --------------

con()				Cursor enabled, ON.

coff()				Cursor disabled, OFF.

ext_col(fg=90, bg=107)		Extended Colours; foreground colour range
				90 to 97, and background colour range 100 to
				107.

-----------------------------------------------------------------------------

  ADVANCED:-
  ----------

graph(graphics="OFF")		Enable 'ON', disable 'OFF' graphics mode.

tb(title="Text.", ver="", tb="ON")
				Writes to the Title Bar whatever you want!

fg24(r=0, g=0, b=0)		Foreground 24 bit colour access.

bg24(r=255, g=255, b=255)	Background 24 bit colour access.

fg8(pal=226)			Foreground paletted colour access.

bg8(pal=21)			Background paletted colour access.

=============================================================================

************************* Test functions available. *************************

--------------------- Read the code for FULL details. -----------------------

   Generic, all platforms:-
   ------------------------

currel_test()			Cursor Relative, 'cls()', crt()', 'cdn()',
				'clt()', 'cup()' functions are tested.

curabs_test()			Cursor Anywhere. 'tr()', 'ca()', 'hm()'
				functions, and the builtin newline escape#
				code are tested.

pfb_test()			Prefix, Foreground, and Background colours,
				'ctr()', 'ra()', and 'pfb()' functions are
				tested.

po_test()			Prefix, (attribute[s]) only.
				This uses the function 'po()' multiple times.

generic_test()			This tests YOUR defined escapes and strings
				for ANY platform of your choice.
				It defaults to a classic AMIGA A1200(HD)
				terminal escape sequence method...

-----------------------------------------------------------------------------

  Most current platforms and PERHAPS non[-]classic AMIGA variants:-
  -----------------------------------------------------------------

ext_col_test()			Extended Colours, 90 to 97, and 100 to 107,
				test.

coff_con_test()			Cursor OFF, cursor ON test.

-----------------------------------------------------------------------------

  For current *NIX terminals, AND, NOT for the AMIGA platform[s] at all:-
  -----------------------------------------------------------------------

graph_test()			THERE IS NO DIRECT TEST WITH THIS FUNCTION.
				THIS INFORMATION WILL BE PRINTED ON SCREEN.
				-------------------------------------------
				"""
				There is no test for this as 'graphics.py'
				is added to run on a GNU/Linux Mint
				Cinnamon 22.3 from Python 1.3.0 to its
				current Python 3.12.3, WITHOUT any
				modification at all.
				It uses this 'ESC' module to work.
				See attached photos.
				From the 'ESC' folder/drawer/directory
				just type:-
					python3 graphics.py<RETURN/ENTER>
				Ensure the 'ESC.py' file is inside the same
				folder/drawer/directory!
				"""

title_test()			Title Bar, 'tb()' function is tested.

truecol_test()			True colour[s], foreground, and background,
				'fg24()' and 'bg24()' functions tested.

palette_test()			Paletted colour[s], foreground, and
				background, 'fg8()' and 'bg8()' functions
				tested.

=============================================================================

