CCEDIT: A Simple Full-Screen Text Editor for the BASIC environment
Copyright 2015, Brett M. Gordon


**************************
  About
**************************


Requirements:
* A CoCo3 (128K or 512K)
* DECB 1.1 compatible system (YA-DOS,SDC-DOS,HDBDOS,RGBDOS, others?)
* Composite or RGB monitor (high contrast 80 column screen)

Features:
* Supports large edit buffers:
     512KB RAM: ~440KB buffer size
     128KB RAM: ~78KB buffer size
* Real Key Repeating with Delay
* Specify file name to edit via BASIC's "command line"
* Emacs-ish commands
* Made in the spirit of Luis Antoniosi's "minTED", but for BASIC
* Uncrunches binary BASIC files for editing



**************************
  Installing CCEDIT
**************************

Load up the DSK file, copy the "CCEDIT.BIN" file onto a disk of
your choice.



**************************
  Starting CCEDIT
**************************

LOADM"CCEDIT":EXEC  (DECB,SDC-DOS)

-or-

RUNM"CCEDIT"

You may also start CCEDIT with a "command line" parameter specifying
the initial file to load by using a ' comment:

RUNM"CCEDIT"'NOTES.TXT



**************************
  Usage
**************************

Key              Command
-------------------------------------------------
left              backspace
right             delete (forward)
cntl-left         move cursor left
cntl-right        move cursor right
cntl-up           move cursor up
cntl-down         move cursor down
cntl-shift-right  move cursor one word right
cntl-shift-left   move cursor one word left
cntl-shift-up     move cursor up one page
cntl-shift-down   move cursor down one page
cntl-a            move cursor to beginning of line
cntl-e            move cursor to end of line
cntl-s            save buffer to disk
cntl-q            quit CCEDIT
cntl-k            delete rest of line / delete line
cntl-o            insert line
cntl-t            move cursor to top of buffer
cntl-g            move cursor to bottom of buffer
cntl-r            rename buffer
cntl-l            load buffer from disk
cntl-n            clear buffer
cntl-y            yank undelete buffer
shft-0            toggles shift-lock


SAVING, LOADING FILES:

CCEDIT only supports one edit buffer.  Loading and Saving buffers to
and from disk has been simplified down to it's basic core components:
Saving, Loading, and Renaming.  Renaming a buffer does not load or
save the buffer contents.  The user must issue separate commands to do
this.

example:

To revert to a disk-saved copy of the current buffer:
cntl-l

To save current buffer:
cntl-s

To save the file under a different name:
cntl-r, cntl-s

To load a different file:
cntl-r, cntl-l

To create a fresh, blank buffer:
cntl-n, cntl-r


FILENAME SPECIFICATION:

This work the same as the standard BASIC file name parser. In fact, it
IS BASIC's parser.  Use of colon, ":", to specify drive number is
fine, and the "/" separator is allowable too.


****************************
  What's Lacking?
****************************

* Any sort of warning about unsaved buffers
* Large cursor movements are slow (e.g. moving the cursor from top to
  bottom of the file)
* Running out of RAM on a 128KB CoCo makes CCEDIT unhappy.
* shft-0 shift-locking is wonky, but eventually works.
* TAB and other other non-printable characters are printed.



***************************
  How Ja Do it?
***************************

CCEDIT uses a modified "GAP" buffer to allow easy insertion and
deletion.  There are main edit stacks.  One stack represents
characters in the buffer that are "behind" the cursor, and the other
stack represents characters "forward" the cursor.  Basic edit
operations become:

insert character:  push new character unto the "behind" stack.
delete char-actor:  pull character off the "forward" stack.
backspace: pull character off the "behind" stack.
move cursor:  pull of character off one stack, push it onto the other.

In addition to the two main stacks, there are to "overflow" stacks
designed to page whole 8192 byte memory blocks as the two edit stacks
fill up or are depleted.

Advantages:  Easy and simple insertion, deletion, and cursor movement.
Disadvantages: Slow for large cursor repositions, moderate complexity
to display, save, or load the buffer.

I also leveraged BASIC "POLCAT" routine.  "POLCAT" is a bit
restrictive, so I enhanced it's design with a wrapper function to:

1. Strategically reset the BASIC's stored keyboard state before each
call to POLCAT.  This means that if a key is held down, POLCAT will
return it each call, rather than wait for it's state to go from
unpressed to pressed.  Each 60HZ VSYNC, an interrupt based
Finite-State-Machine reads the keyboard and responds to held keys
appropriately and fills an intermediate buffer with keys.  

2. The "META" keys (SHIFT,CNTL,ENTER,BREAK, etc.) are polled
separately and their state if scanned and maintained separately from
POLCAT.  This allows better, simpler "Control" shifting.