This is the LWBasic project. Its goal is to create a replacement Basic for
the TRS80 Color Computer. This Basic will not be binary compatible with the
stock ROM. In particular, any various peeks, pokes, executes, and the like
intended to mess with the interpreter internals are unlikely to work, and,
in fact, may be completely detrimental.

Additional detailed documentation can be found under docs/.

There are two versions of LWBasic. One is for the Coco 1 and 2. The other
is for the Coco 3. The primary differences between the two are in the
startup code and features that rely on the existence of Coco 3 hardware. The
main differences for the Coco 3 version are:

* 32/40/64/80 column text modes with attributes
* 256/320/512/640 column bitmap graphics with up to 16 colours (256/320)
  or 4 colours (512/640)
* palette register setting
* graphics and text screen located outside main program memory
* disk I/O buffers located outside main program memory
* separate heaps for strings, scalars, arrays, and program text not limited
  to the 64K address space of the CPU
* ROM/RAM copy at startup and initialization of Coco 3 specific hardware;
  defaulting to the 80 column text screen

Both versions can either be installed in ROM or loaded from disk or tape.
In the case of loading from disk or tape, the machine must have at least
64K of RAM. The loadable versions do not include certain initalization
routines that are only relevant to cold starting the hardware.

For the Coco 3 version, the ROM is a single 32K chunk intended to replace
the 32K internal ROM. For the Coco 1/2 version, there are three chunks: an
"Extended Color Basic" chunk (8K for the ECB socket), a "Color Basic" chunk
(8K for the CB socket), and "Disk Extended Color Basic", a 16K chunk
intended to be installed in a cartridge ROM, probably a disk controller. On
machines with a single 16K internal ROM, the "Extended Color Basic" and
"Color Basic" chunks should arranged with "Extended Color Basic" at the
lowest address and "Color Basic" immediately above.

An important note about the hardware interrupt vectors in the ROMs: the Coco
1/2 get the FFFx vectors from the top 16 bytes of the "Color Basic" chunk.
The Coco 3 gets the FFFx vectors from the top 16 bytes of the 32K internal
ROM.

Note that LWBasic does not look for the DK signature of a Disk Basic ROM
and, thus, will not autostart whatever Disk Basic you happen to have
installed. This is most relevant on a Coco 3 where the upper 16K of the
LWBasic ROM is internal instead of in a cartrige.


Numbers
=======

LWBasic has two numeric types: a 32 bit signed integer, stored as two's
complement and a decimal floating point type stored in packed BCD with
10 digits of precision and a base 10 exponent range of -63 to +63

The BCD format using 48 bits is stored as follows:

Offset	Bits	Content
0	1	Sign bit - 1 for negative
1	7	Decimal exponent with a bias of 64; 0 indicates a value of 0
8	40	10 packed BCD digits of the significand

It is worth noting the reason for using the BCD format instead of binary
floating point. Because interactions with the computer are typically in base
10, it makes sense to avoid the horrendous complications of attempting to
maximize the accuracy of converting binary floating point to decimal and
back again. While this is trivial for integers, it is non-trivial for
floating point where the variations in accuracy and the need for rounding is
unavoidable.

At the expense of some extra CPU cycles for doing the calculations, base 10
accuracy is preserved, at least to the precision limit of the data type.
This also allows pre-parsing numbers and being able to display them again
accurately when generating a program listing, even if extra nonsignificant
digits like trailing decimal zeroes are not reproduced.

It is, however, critical to note that despite the BCD representation, these
values are still floating point and have the inherent inaccuracies of all
limited precision data types. The simple difference is that it makes the
numbers in the computer behave exactly like scientific notiation with no
unexpected surprises.