=================
ZX-LINE (ZX-SOFT)
=================

ZX-LINE is a "one-liner" utility to renumber programs in Basic,
based on the original utility ZX-RENUM by the same author.


=======
HISTORY
=======

According to the Jargon File, creating "one-liners" is a popular
tradition in computer science that started from APL programmers
in the 1960's.

In particular, implementing a "one-liner" in BASIC Sinclair is
very challenging, since the entire program must fit in a single
screen (22x32) otherwise it can't be properly edited anymore.


=======
CHANGES
=======

ZX-LINE works just like ZX-RENUM, except it doesn't validate if
all line references have exactly 4 digits (it will likely crash
if the program does not follow this rule), and it doesn't allow
to specify the initial line number to be renumbered (it will
always renumber the entire program).

Internally, ZX-LINE allocates only 2 bytes per line reference
located in the program while renumbering (instead of 4 bytes for
each line reference allocated by ZX-RENUM).


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

* 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 cause
ZX-LINE to crash. Fortunately, this kind of problem is very
unlikely to happen in practice.

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.


========
WARNING!
========

Keep in mind that ZX-LINE does NOT check for line references that
disobey the rules described above. In particular, if your program
contains a line reference that doesn't have exactly 4 digits,
ZX-LINE may crash while attempting to renumber it. In this case,
it would be safer to reload your program from tape, fix the
incorrect lines and then run ZX-LINE again.

There's not enough space to implement both line validation and
renumbering logic within the same "one-liner". In the future, we
may implement a separate "one-liner" for line validation only,
that could be used prior to ZX-LINE execution. In the meantime,
if you cannot identify invalid line references in your program
yourself, your best option is to use ZX-RENUM instead of ZX-LINE,
since ZX-RENUM will validate and report invalid line references.


=====
USAGE
=====

1. Load your program from tape. Make sure it does not contain the
line number 9999 (this line is reserved for ZX-LINE).

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

3. Input the new number you want for the initial line of your
program (such as 1000) and the increment between lines (such as
10).

4. After the entire program is renumbered, simply delete line
9999 (to remove ZX-LINE) before saving your program.


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

This is the entire source code for ZX-LINE:

  9999 INPUT n'i:
  LET g=23620:
  LET b=256:
  DEF FN w(x)=PEEK ABS x+b*PEEK ABS (x+1):
  LET e=FN w(g+15):
  LET p=e:
  LET z$="":
  LET k=FN w(-p-1):
  LET q=p+4:
  LET p=q+FN w(p+2):
  LET d=238-PEEK q:
  LET q=q+1+5*(d=224):
  POKE g,16-2*((d=1)+(ABS d=2)+(ABS d=9)+(d=13)+(d=36))*(PEEK q>47)*(PEEK q<58)+5*(k>9998):
  LET z$=z$+CHR$ (q-b*INT (q/b))+CHR$ (q/b-.5):
  LET q=q+9:
  POKE g,8+3*(q<p)*(d<>4):
  POKE e,n/b-.5:
  POKE e+1,n-b*PEEK e:
  LET n=n+i:
  LET e=e+FN w(e+2)+4:
  LET k=FN w(-e-1):
  FOR p=1 TO LEN z$ STEP 2:
  LET q=CODE z$(p)+b*CODE z$(p+1):
  POKE (FN w(q+7)<>k)*g,31:
  FOR d=0 TO 3:
  POKE q+d,CODE ("000"+STR$ n)(LEN STR$ n+d):
  NEXT d:
  POKE q+8,n/b-.5:
  POKE q+7,n-b*PEEK (q+8):
  LET z$(p TO p+1)="":
  NEXT p:
  POKE (k<9999)*g,17


The source listing fits exactly in a single screen, which
is the maximum editable size for a program line in the
ZX-Spectrum:

  9999 INPUT n'i: LET g=23620: LET
   b=256: DEF FN w(x)=PEEK ABS x+b
  *PEEK ABS (x+1): LET e=FN w(g+15
  ): LET p=e: LET z$="": LET k=FN
  w(-p-1): LET q=p+4: LET p=q+FN w
  (p+2): LET d=238-PEEK q: LET q=q
  +1+5*(d=224): POKE g,16-2*((d=1)
  +(ABS d=2)+(ABS d=9)+(d=13)+(d=3
  6))*(PEEK q>47)*(PEEK q<58)+5*(k
  >9998): LET z$=z$+CHR$ (q-b*INT
  (q/b))+CHR$ (q/b-.5): LET q=q+9:
   POKE g,8+3*(q<p)*(d<>4): POKE e
  ,n/b-.5: POKE e+1,n-b*PEEK e: LE
  T n=n+i: LET e=e+FN w(e+2)+4: LE
  T k=FN w(-e-1): FOR p=1 TO LEN z
  $ STEP 2: LET q=CODE z$(p)+b*COD
  E z$(p+1): POKE (FN w(q+7)<>k)*g
  ,31: FOR d=0 TO 3: POKE q+d,CODE
   ("000"+STR$ n)(LEN STR$ n+d): N
  EXT d: POKE q+8,n/b-.5: POKE q+7
  ,n-b*PEEK (q+8): LET z$(p TO p+1
  )="": NEXT p: POKE (k<9999)*g,17


The ZX-LINE utility is structured as follows:

* INPUT (statements 1-7): initializes variables and parameters.

* ANALYZER (statements 8-16): locates all line references.

* MODIFIER (statements 17-32): updates line numbers and their
corresponding line references.


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

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