Initial importHEADmain

1 files changed, 186 insertions, 0 deletions

diff --git a/bas2tap.doc b/bas2tap.doc
new file mode 100644
index 0000000..942c748
--- /dev/null
+++ b/bas2tap.doc
@@ -0,0 +1,186 @@
+BAS2TAP v2.2                                                (Release 13-06-2003)
+Written by M. van der Heide of ThunderWare Research Center
+
+This program converts 'BASIC in an ASCII file' to a TAP tape image file, to be
+used in a ZX Spectrum emulator. Both 48K and 128K listings are supported.
+
+
+STANDARD DISCLAIMER
+-------------------
+This program is provided "as is", without any warranties, nor an indication
+that it will fit the purpose.
+BAS2TAP has been tested on several systems and OSes, causing no problems.
+If you want to use this program, though, you do so at your own risk.
+This means that it is extremely unlikely to damage your system, but if the
+unthoughtful event DOES happen, you will be on your own.
+ThunderWare Research Center can and will accept no claims whatsoever.
+
+This program is neither public domain nor shareware: it's Open Source Software.
+This means that anyone is allowed to distribute and use the program, as well as
+change the source code. The source code (modified or not) must be included in
+any distribution at all time.
+You can not request any money from anyone for copying this program, apart from
+the expenses made for the media onto which it has been copied.
+The package contents may not be changed when distributing it. At least the
+following files must be present:
+
+   BAS2TAP.C    source text file
+   BAS2TAP.DOC  this documentation file
+
+Remember you can always freely obtain the latest version from
+the utilities section of The World of Spectrum, at:
+    http://www.worldofspectrum.org/
+
+Or you can try:
+    ftp://ftp.worldofspectrum.org/pub/sinclair/tools/pc
+
+
+REVISION HISTORY
+----------------
+1.0  26-03-98: First public release
+1.1  01-04-98: Changes:
+               - Added banner.
+               - Switch -q does not suppress warnings, but progress indication.
+               - Added switch -w to suppress warnings.
+               - Added switch -e on popular demand.
+               - Empty lines are skipped and only generate a warning.
+               - Lines with only a line number generate an error.
+               - Numbers can also start with a decimal point (eg. '.5').
+               - Lines no longer require an end-of-line terminator.
+               - In-line sequence expansions also remove any trailing
+                 spaces unless it was between quotes.
+               - The created TAP is made valid (although incomplete) if an error
+                 occurs, unless it was a write error.
+1.2  11-12-98: Changes:
+               - Block graphics were encoded rotated by 1.
+               - Added full syntax checking, and
+               - Added switch -n to disable the syntax checking again.
+               - Added expansion sequences '{CAT}' and '{CODE}' with the sole
+                 purpose of being used as channel name in the OPEN # command.
+               - Changed the distribution policy from freeware to Open Source
+                 Software.
+1.3  04-01-99: Changes:
+               - Spaces after strings are now skipped (they are not needed).
+               - The 'CLS #' command does exist on the Interface 1 after all.
+               - Exponential numbers were raised the wrong way around
+                 (eg. 25e3 became 0.025 and 25e-3 became 25000). Oooops....
+1.4  17-05-99: Changes:
+               - UDGs used as 'USR "x"' would result in a crash due to 2
+                 bad pointers.
+               - Complex expressions between brackets as parameter to other
+                 expression types (eg. ATTR or string slicing) would screw
+                 up the evaluation.
+               - The 'CLS #' command was flagged as being Interface 1
+                 specific in the previous version rather than either
+                 Interface 1 or Opus Discovery (aaargh!)
+1.5  19-05-99: Changes:
+               - The 'DIM' command's syntax description was incorrect, so the
+                 checker didn't like the variable name before the opening
+                 bracket.
+1.6  23-06-99: Changes:
+               - Several problems with array indices!
+               - The 'USR' token only accepted a numerical operand. An
+                 exception was made for UDG expressions '"x"' but constructions
+                 like 'USR CHR$ a' didn't work.
+1.7  02-11-99: Changes:
+               - The DEF FN function requires insertion of evaluation room.
+1.8  09-11-00: Changes:
+               - The DEF FN function only requires insertion of evaluation room
+                 in the parameter area before the '=' token.
+                 Any bracketed argument would upset the parser.
+1.9  08-12-01: Changes:
+               - Forgot to skip the ';' colour token separator in class 9.
+               - REM statements should be parsed as-is (except for expansion
+                 sequences), without taking out multiple spaces or counting
+                 quotes.
+2.0  11-12-02: Changes:
+               - SAVE/LOAD/VERIFY/MERGE DATA didn't work, as the DATA token was
+                 set to be allowed as keyword only.
+               - ERASE ! didn't work, as ERASE was only allowed from the "m"
+                 chennel.
+2.1  22-12-02: Changes:
+               - Any alphanumerical expression can be sliced, not only
+                 variables and direct strings.
+               - If the output filename provided on the command line had the
+                 extension '.TAP', it shouldn't be forced to '.tap'.
+2.2  13-06-03: Changes:
+               - Expand sequences PAPER and INK had their codes reversed.
+               - Expand sequences BRIGHT and FLASH had their codes reversed.
+               - Expand sequences INVERSE and OVER had their codes reversed.
+               - Expand sequences {XX} didn't work (missing pointer advance).
+               - Expand sequences AT and TAB didn't work and threw a
+                 warning instead (missing pointer advance).
+
+SYNTAX
+------
+  BAS2TAP [-q] [-w] [-e] [-c] [-aX] [-sX] FileIn [FileOut]
+
+-q  goes into quiet mode, suppressing banner and progress indication.
+-w  suppress generation of warnings.
+-e  write errors to the stdout in stead of the stderr stream.
+-c  makes token matching case independant. The drawback is that variables that
+    have the same name as a token (eg. 'print') cannot be used, as they will be
+    treated as (unexpected) tokens.
+-n  disables syntax checking.
+-aX sets the auto-start line to line X.
+-sX sets the TAP block name to X (max 10 characters).
+
+If no output filename is provided, the same name as the input file will be
+used, but with extension `.TAP'.
+
+
+THE CONVERTOR
+-------------
+The following rules apply:
+
+1. One BASIC line must be provided in one ASCII line.
+2. Keywords must appear in upper case (unless switch -c is used).
+3. Keywords that consist of multiple words (eg. `GO TO') must have the space
+   in between the words.
+4. Spaces between words are not needed, unless this leads to concatenation
+   problems - eg. `PRINTVAL"10"' must appear as `PRINT VAL"10"', while
+   `PRINT10' is perfectly acceptable.
+5. Syntax is fully checked according to
+   - the normal Spectrum ROM,
+   - Interface 1/Microdrive extension,
+   - Opus Discovery extension.
+
+The following sequences are expanded in-line:
+
+   Chars   Expand to
+
+   tab     character 06     ("print '")
+   {XX}    XX is 2-digit hex, converts to the Spectrum ASCII value
+   {(C)}   character 7F     (copyright sign)
+   {-X}    X is 1-8, characters 80-87 (block graphics without shift)
+   {+X}    X is 1-8, characters 88-8F (block graphics with shift)
+   {X}     X is `A'-`U', converts to the UDG Spectrum ASCII value
+   {CODE}  character AF     ('CODE')
+   {CAT}   character CF     ('CAT')
+
+Special sequences are (case independant) PAPER, INK, BRIGHT, FLASH, OVER,
+INVERSE, AT and TAB control sequences. They may appear as "{PAPER 3}" to convert
+to the sequence 0x10,0x03. Note that both AT and TAB take 2 operands, which
+should be seperated by a comma (eg. "{AT 1,10}").
+Notice that these expansions are identical to what SGD and TAPER create when
+saving out BASIC blocks.
+
+
+RECOMPILING THE SOURCE
+----------------------
+The source is provided in (almost) fully portable ANSI C, the source text is
+written in 132 columns.
+
+If you wish to experiment with different syntax (eg. for a DISCiPLE), you may
+find it useful to set the `__DEBUG__' define.
+
+If you make any fundamental change to the source, you are requested - but not
+obligated - to send the changed source back to me, so that everyone can benefit
+from it. My e-mail address is `mheide@worldofspectrum.org'
+
+
+Enjoy!
+
+Martijn van der Heide, MSc
+Senior Software Developer
+ThunderWare Research Center