LIST_bas
                                ========

        Recreates S*BASIC listing from tokenised (sav) file


Compatibility
=============

Needs TK2 V2.32+ (earlier versions may be ok). To run the compiled version
you also need the Qlib runtimes V3.36+

Compatible with all systems (but see below). May not work with older
versions of SAV files.


Usage
=====

Invoke with:

    EX <path>LIST_obj;"<path>filename_sav"
 or
    EX <path>LIST_obj   (Manual input of filename)
 or
    LRUN <path>LIST_bas (Manual input of filename)

The output file name is hardwired to be ram1_test_bas. Change in the code
if you prefer.

In SMSQ/E you can also EXecute the SBASIC file directly. To RUN the
S*BASIC file under Qdos you need to change the dots to underscores in all
the variable names!

Error returns:
--------------

        -19 -> Incorrect or unsupported Qsave file
        -10 -> Unexpected end of file
         -7 -> file not found

The program always returns with the last error found - or 0 if none.

        1 -> unrecognised language command
        2 -> unrecognised separator
        3 -> unrecognised operator
        4 -> unrecognised monadic operator
        5 -> unrecognised formatting separator
        6 -> unrecognised string delimiter
        9 -> line number error

These errors are highly unlikely ever to occur and could imply some kind
of corruption of the source file.


Why this program?
=================

This program is a concept tool for treating S*BASIC files in various ways.
As it stands, it performs a simple task, one that the interpreter does
effortlessly by itself! But that is not the point. Running this program is
just a simple demonstration that the tool works at a basic level.

LIST is designed to be modified for various different uses where it is
necessary to process some source code. The built-in parser has already done
a splendid job of parsing the messy source file into unambiguous tokens,
leaving the tokenised file as a pure representation of the code.

I have already used this program as a skeleton for

1. Converting S*BASIC programs into syntax coloured, navigable HTML (see
   Knoware's sb2htm).

2. To convert SBASIC's hex and binary constants, which SuperBASIC doesnt
   support, into standard floating point (see Knoware's dehex).

3. Code obfuscater, a silly program, desired by some, to make S*BASIC
   code unreadable in a (vain) attempt to hide bad programming or
   proprietary IP. (See Knoware's Obfuscater).

I have produced various other, unpublished, hacks to analyse code, to
index functions and procedures, or to extract them from programs for
re-use.


History
=======

When I first got hold of the Qdos Technical guide, was the first time I
saw the list of all the SuperBASIC tokens, neatly typed out. I had a hand-
held scanner with OCR for the Atari and I used that to scan the tokens into
a file. OCR wasnt what it is today. There were many errors and missed
characters. It might almost have been quicker to type the whole thing by
hand!

Anyway, taking that list I converted it almost verbatim into a program:
LIST. In fact, that was the easiest part of the process! Since then Ive
made various attempts to speed up and streamline parts of the program, but
the central core, the engine, is more or less the same as it always was. I
havent tried to speed up or rationalise it, as it perfectly describes the
token vocabulary and structure.

In dehex, Ive whittled the token structure down to the bare basics, and
then rationalised it:

 1 DEFine PROCedure DeHex
 2 LOCal scan, pos, tb%, l%
 3 REMark Program to convert SBAS $hex
 4 REMark and  %bin literals to decimal
 5 REMark © pjwitte 2oo1 @
 6 :
 7 pos = PEEK_L(\\$10) + 2: REMark Get start of program
 8 REPeat scan
 9  IF pos > PEEK_L(\\$14): EXIT scan
10 :
11  tb% = PEEK(\\pos)
12  SELect ON tb%
13   = $8B,  $8C : REMark strings
14                 pos = pos + 2
15                 l% = PEEK_W(\\pos): REMark Length of text
16                 pos = pos + ((l% + 3 ) && -2): REMark skip text
17   = $8D,  $88 : REMark skip line numbers and names
18                 pos = pos + 4
19   = $D0 TO $FF: REMark numbers % to $, and beyond
20                 POKE\\pos, tb% || $F0 : REMark Convert type to decimal
21                 pos = pos + 6
22   = REMAINDER :
23                 pos = pos + 2
24  END SELect
25 END REPeat scan
26 END DEFine
27 :

This is supposed to work on a loaded program. Renumber it so it is out of
range of your program and MERGE it. Then type dehex. When done DLINE the
dehex procedure again. All your $hex and %bin variables will have been
converted to decimals and you could now load and run your program in
Qdos'es SuperBASIC interpreter. Of course, this variant of the program must
be run under SBASIC. It was designed for a time when Qliberator also
couldnt deal with non-decimal constants. That problem has been eliminated
since Qlib V3.42 (or there about).


Program status
==============

Note: This program is not a polished program and may not be fully error
trapped!

V0.01, ©PWitte 1991
V0.06, pjw, 2025 Sep 20, Removed last external toolkit reference!
V0.07, pjw, 2025 Sep 21, New Minerva tokens, $89 and $86 catered for.
            They code for literal integers -128 to 127 (two bytes) and
            >128 (4 bytes). Not documented anywhere I know of. Only
            applies to files QSAVEd under Minerva V1.??+
V0.08, pjw, 2025 Sep 26, Bug fix: Wrong byte returned by MinB%

               Conditions of use and DISCLAIMER as per Knoware.no

Generated by QuickHTM, 2025 Sep 26