==================
ZX-RENUM (ZX-SOFT)
==================

ZX-RENUM is a small utility to renumber programs in Basic.


========
FEATURES
========

* It's optimized for both size and speed. This utility size is
only 900 bytes, it allocates only 4 bytes per line reference, and
it occupies only 6 program lines (9994 to 9999). Even so, it runs
fairly fast for an utility implemented 100% in Basic (see further
technical details below).


* It correctly updates line references such as:

GO TO nnnn
GO SUB nnnn
RUN nnnn
RESTORE nnnn
LIST nnnn
LLIST nnnn
SAVE name LINE nnnn


* It correctly differentiates (and ignores) statements such as:

REM ...
RUN
RESTORE
LIST
LLIST
INPUT LINE a$


=====
RULES
=====

* Every line reference must have exactly 4 digits, such as
GO TO 1000 and GO TO 0010, but not GO TO 10 (since it's not
possible for a renumber in Basic to insert or remove digits as
needed). If you always write programs above line 1000, you
should be following this rule automatically.

* Strings are not fully interpreted (it would be too inefficient
to do so), thus a statement such as LET A$=" GO SUB " may be
reported as error. Fortunately, this kind of problem is very
unlikely to happen in practice, and ZX-RENUM will let you know
if it does.

If there's a statement you cannot fix according to these rules,
you can comment it out (adding a REM statement just before it)
and fix it manually later, after renumbering everything else.


=====
USAGE
=====

1. Load your program from tape. Make sure it does not contain any
line numbers from 9994 to 9999 (these are reserved for ZX-RENUM).

2. Execute MERGE "ZX-RENUM" to load this utility, then RUN 9994
to run it.

3. Input the initial line in your program that must be renumbered
(you can simply type zero to renumber everything), the new number
you want for this initial line (such as 1000) and the increment
between lines (such as 10).

4. If this utility identifies a program line that doesn't follow
the required rules (see above), it will report this error before
making any changes to your program. In this case, you should fix
the reported line and then restart ZX-RENUM with RUN 9994

5. You may run ZX-RENUM several times, for instance to renumber
one part of your program starting at line 1000, the following
part starting at line 2000, and so on. After the entire program
is renumbered, you should manually delete lines 9994 to 9999 and
finally save your program.


============
TECH DETAILS
============

The ZX-RENUM utility is structured as follows:

* INPUT (line 9994): initializes variables and parameters.

* ANALYZER (lines 9995-9997): locates all line references and
reports program lines that don't follow the rules.

* MODIFIER (lines 9998-9999): updates line numbers and their
corresponding line references.


The functions and variables in ZX-RENUM are defined as follows:

* DEFINITIONS:

b - constant value 256
w(x) - function to PEEK word, either lower or higher byte first:
       w(a)        returns PEEK a + 256*PEEK (a+1)
       w(-a-SGN a) returns 256*PEEK a + PEEK (a+1)
v(x) - function to validate a digit:
       returns 0 for a character code between '0' and '9'
       returns 1 otherwise

* ANALYZER VARIABLES:

l - initial line to be renumbered
e - address of initial line to be renumbered
p - address of the beginning of the current line
k - current line number
q - address inside current line
d - content from address q
z$ - store 4 bytes for each line reference located in the program

* MODIFIER VARIABLES:

e - address of the beginning of the current line
k - counter for z$ index
q - address of a line reference
n - current line number
i - line increment
d - counter for updating line reference digits


In order to understand the code, it's also important to keep in
mind the following memory optimizations:

* Value zero is replaced by expression BIN, which saves 6 bytes
  each time, providing almost the same performance.

* Value one is replaced by expression SGN PI, which saves 5 bytes
  each time, providing almost the same performance.

* Other optimizations that would impact performance significantly
  (such as using expression VAL "256" instead of value 256) are
  only applied to code sections that are executed just once.


=======
CREDITS
=======

Freeware utility "ZX-RENUM" for ZX-Spectrum & compatibles.
Produced by *ZX-SOFT* Brasil Ltda.
Programmed by Einar Saukas.
