Mercurial > hg > index.cgi

annotate README.txt @ 126:ac183a519439

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update parsing scheme with a keyword lookup by token value and other framework Add ability to turn a token code into a keyword string. Also correct some details related to token table generation with some additiona adjustments for token symbols. Also rework token symbol definitions and creation of some parsing tables as well as the main statement parsing loop.
author William Astle <lost@l-w.ca>
date Mon, 08 Jan 2024 22:58:08 -0700
parents 1c1a0150fdda
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
1 This is the LWBasic project. Its goal is to create a replacement Basic for
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
2 the TRS80 Color Computer. This Basic will not be binary compatible with the
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
3 stock ROM. In particular, any various peeks, pokes, executes, and the like
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
4 intended to mess with the interpreter internals are unlikely to work, and,
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
5 in fact, may be completely detrimental.
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
6
120
1c1a0150fdda Add documentation of bytecode and parsing scheme
William Astle <lost@l-w.ca>
parents: 85
diff changeset
7 Additional detailed documentation can be found under docs/.
1c1a0150fdda Add documentation of bytecode and parsing scheme
William Astle <lost@l-w.ca>
parents: 85
diff changeset
8
0
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
9 There are two versions of LWBasic. One is for the Coco 1 and 2. The other
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
10 is for the Coco 3. The primary differences between the two are in the
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
11 startup code and features that rely on the existence of Coco 3 hardware. The
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
12 main differences for the Coco 3 version are:
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
13
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
14 * 32/40/64/80 column text modes with attributes
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
15 * 256/320/512/640 column bitmap graphics with up to 16 colours (256/320)
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
16 or 4 colours (512/640)
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
17 * palette register setting
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
18 * graphics and text screen located outside main program memory
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
19 * disk I/O buffers located outside main program memory
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
20 * separate heaps for strings, scalars, arrays, and program text not limited
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
21 to the 64K address space of the CPU
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
22 * ROM/RAM copy at startup and initialization of Coco 3 specific hardware;
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
23 defaulting to the 80 column text screen
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
24
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
25 Both versions can either be installed in ROM or loaded from disk or tape.
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
26 In the case of loading from disk or tape, the machine must have at least
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
27 64K of RAM. The loadable versions do not include certain initalization
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
28 routines that are only relevant to cold starting the hardware.
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
29
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
30 For the Coco 3 version, the ROM is a single 32K chunk intended to replace
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
31 the 32K internal ROM. For the Coco 1/2 version, there are three chunks: an
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
32 "Extended Color Basic" chunk (8K for the ECB socket), a "Color Basic" chunk
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
33 (8K for the CB socket), and "Disk Extended Color Basic", a 16K chunk
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
34 intended to be installed in a cartridge ROM, probably a disk controller. On
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
35 machines with a single 16K internal ROM, the "Extended Color Basic" and
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
36 "Color Basic" chunks should arranged with "Extended Color Basic" at the
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
37 lowest address and "Color Basic" immediately above.
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
38
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
39 An important note about the hardware interrupt vectors in the ROMs: the Coco
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
40 1/2 get the FFFx vectors from the top 16 bytes of the "Color Basic" chunk.
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
41 The Coco 3 gets the FFFx vectors from the top 16 bytes of the 32K internal
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
42 ROM.
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
43
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
44 Note that LWBasic does not look for the DK signature of a Disk Basic ROM
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
45 and, thus, will not autostart whatever Disk Basic you happen to have
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
46 installed. This is most relevant on a Coco 3 where the upper 16K of the
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
47 LWBasic ROM is internal instead of in a cartrige.
85
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
48
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
49
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
50 Numbers
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
51 =======
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
52
120
1c1a0150fdda Add documentation of bytecode and parsing scheme
William Astle <lost@l-w.ca>
parents: 85
diff changeset
53 LWBasic has two numeric types: a 32 bit signed integer, stored as two's
1c1a0150fdda Add documentation of bytecode and parsing scheme
William Astle <lost@l-w.ca>
parents: 85
diff changeset
54 complement and a decimal floating point type stored in packed BCD with
1c1a0150fdda Add documentation of bytecode and parsing scheme
William Astle <lost@l-w.ca>
parents: 85
diff changeset
55 10 digits of precision and a base 10 exponent range of -63 to +63
85
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
56
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
57 The BCD format using 48 bits is stored as follows:
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
58
120
1c1a0150fdda Add documentation of bytecode and parsing scheme
William Astle <lost@l-w.ca>
parents: 85
diff changeset
59 Offset Bits Content
85
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
60 0 1 Sign bit - 1 for negative
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
61 1 7 Decimal exponent with a bias of 64; 0 indicates a value of 0
120
1c1a0150fdda Add documentation of bytecode and parsing scheme
William Astle <lost@l-w.ca>
parents: 85
diff changeset
62 8 40 10 packed BCD digits of the significand
85
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
63
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
64 It is worth noting the reason for using the BCD format instead of binary
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
65 floating point. Because interactions with the computer are typically in base
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
66 10, it makes sense to avoid the horrendous complications of attempting to
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
67 maximize the accuracy of converting binary floating point to decimal and
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
68 back again. While this is trivial for integers, it is non-trivial for
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
69 floating point where the variations in accuracy and the need for rounding is
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
70 unavoidable.
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
71
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
72 At the expense of some extra CPU cycles for doing the calculations, base 10
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
73 accuracy is preserved, at least to the precision limit of the data type.
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
74 This also allows pre-parsing numbers and being able to display them again
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
75 accurately when generating a program listing, even if extra nonsignificant
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
76 digits like trailing decimal zeroes are not reproduced.
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
77
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
78 It is, however, critical to note that despite the BCD representation, these
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
79 values are still floating point and have the inherent inaccuracies of all
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
80 limited precision data types. The simple difference is that it makes the
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
81 numbers in the computer behave exactly like scientific notiation with no
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
82 unexpected surprises.