AMSB.txt: add sections on redundant and unused tokens.

1 files changed, 79 insertions, 2 deletions

diff --git a/AMSB.txt b/AMSB.txt
index 158bc0c..f277e26 100644
--- a/AMSB.txt
+++ b/AMSB.txt
@@ -5,12 +5,20 @@ AMSB is actually a pretty cool BASIC for the Atari 8-bit. I never
 got the chance to use it 'back in the day' because it was expensive,
 required a floppy drive and at least 32K of RAM (my poor 400 had a
 tape drive for the first few years), and then later on, there was
-Turbo BASIC XL, which was just as cool as AMSB, but freeware.
+Turbo BASIC XL, which was cooler than AMSB, and also freeware.
 
 This file is a collection of notes I made to myself while developing
 listamsb. The information here might be useful (e.g. if you're trying
 to repair a damaged AMSB file) and hopefully is interesting. Enjoy!
 
+This file is part of the bw-atari8-utils source. You can get the
+latest version of the source from:
+
+https://slackware.uk/~urchlay/repos/bw-atari8-tools
+
+...which you can either view with a web browser or use with the 'git
+clone' command.
+
                                 -- B. Watson <urchlay@slackware.uk>
 
 
@@ -75,6 +83,73 @@ depending on what version of AMSB you have, what DOS you boot, whether
 or not you have the R: device driver loaded, etc etc).
 
 
+Redundant Tokens
+----------------
+
+There are two separate tokens each for PRINT and AT:
+
+token | text
+------+-----------------------
+ $ab  | "PRINT "
+ $ac  | "PRINT"
+ $df  | "AT("
+ $e0  | "AT "
+
+When tokenizing a line, AMSB will actually use the $ab token if
+there's a space after PRINT (or ?), otherwise it will use the
+$ac token. These lines actually get tokenized differently:
+
+10 PRINT "HELLO"
+10 PRINT"HELLO"
+
+Same applies to the $df and $e0 AT tokens: if the user entered
+"AT(X,Y)", $df is used. Otherwise, with "AT (X,Y)", $e0 is used
+(followed by an ASCII left parenthesis).
+
+3 tokens include the opening parenthesis:
+
+token | text
+------+-----------------------
+ $d2  | "TAB("
+ $d6  | "SPC("
+ $df  | "AT("
+
+Normally in AMSB, it's OK to leave a space between a function name
+and the left-paren. PEEK (123) and SIN (1) are both valid. However,
+for SPC and TAB, no space is allowed, because the ( is part of the
+token. AT would be the same way, except there's a separate token $e0
+that *includes* the space. Weird, huh? A side effect of this is
+that "SPC (10)" or "TAB (10)" won't be treated as a function call.
+Instead, the SPC or TAB is treated as a variable name. If you write:
+
+PRINT TAB (10);"HELLO"
+
+...it'll print " 0 HELLO" at the start of the line[*], instead of "HELLO"
+in the 10th column as you might have expected. It also means that AT,
+TAB, and SPC are valid variable names in AMSB, which is an exception
+to the rule that keywords can't be used as variable names (e.g. SIN=1
+or STRING$="HELLO" are invalid).
+
+[*] Unless you've assigned another value to TAB, of couse.
+
+
+Unused Tokens
+-------------
+
+If you look at the token list in amsbtok.h (or in a hex dump
+of the AMSB executable or cartridge image), you'll see a lot of
+double-quotes mixed in with the list. AMSB doesn't actually tokenize
+the " character (it's stored as $22, its ASCII value), so these seem
+to be placeholders, either because some tokens were deleted from the
+language during its development, or else they're intended for some
+future version of AMSB that never happened.
+
+The weird quote tokens are $99, $c8 to $d0, $d5, and $e7 to $ed. If
+you hexedit a program to replace a regular double-quote with one of
+these tokens, it will list as either "" or just one ", but it will
+cause a syntax error at runtime.
+
+
 LOADing Untokenized Files
 -------------------------
 
@@ -90,7 +165,9 @@ happen if a LISTed file somehow got truncated.
 While on the subject... the manual doesn't mention it, but if you LOAD
 a text file without line numbers, the code gets executed in direct
 mode during the load (like Atari BASIC's ENTER command does). This
-means you could write scripts (batch files) for AMSB.
+means you could write scripts (batch files) for AMSB... though you'd
+be better off using MERGE, rather than LOAD (MERGE is basically the
+same thing as Atari BASIC's ENTER).
 
 
 Program Length Header Mismatch