========
renumbas
========

-----------------------------------
Renumber Atari 8-bit BASIC programs
-----------------------------------

.. include:: manhdr.rst

SYNOPSIS
========
renumbas [**-v**] [**-s** *start-lineno*] [**-i** *increment*] [**-f** *first-lineno*] [**-b**] *input-file* *output-file*

DESCRIPTION
===========
**renumbas** reads a tokenized Atari 8-bit BASIC program and writes a
renumbered copy of the program. 

**input-file** must be a tokenized (SAVEd) Atari BASIC program. Use
*-* to read from standard input, but **renumbas** will refuse to
read from standard input if it's a terminal.

**output-file** will be the renumbered BASIC program. If it already
exists, it will be overwritten. Use *-* to write to standard output,
but **renumbas** will refuse to write to standard output if it's a
terminal (since tokenized BASIC is binary data and may confuse the
terminal).

Line number references are changed in every line where they occur, so
e.g. if line 100 gets changed to 200, any other line that does a *GOTO*
*100* (or *GOSUB*, *RESTORE*, *TRAP*, etc) will be updated with the new line
number.

Computed line numbers can't be updated (e.g. *GOTO A or GOSUB
1000+A*100*). These will cause warnings on stderr, so you can fix them
manually.

Valid line numbers (0 to 32767) that don't exist will not be changed,
but will cause a warning. Invalid line numbers (e.g. *TRAP 40000*)
will be ignored (no change, no warning).

Remember that the maximum line number for Atari BASIC is 32767.
Renumbering will fail, if the chosen start and increment values
would result in lines with numbers higher than this.

Atari BASIC allows fractional line numbers, such as *GOTO 123.4*.
These are rounded to the nearest integer when the program is
executed. **renumbas** handles these correctly, although you're
not likely to run into them in real-world programs.

OPTIONS
=======

Options may appear in any order. The first non-option argument is used
for **input-file**; the second is **output-file**. A third non-option
argument is an error.

Renumber Options
----------------
**-s** *start-lineno*
  First line number in the renumbered program. Default: 10.

**-i** *increment*
  Line number increment between successive lines. Default: 10.

**-f** *first-lineno*
  Line number in original program where renumbering will start. Lines
  numbered lower that this will not be renumbered. Default: 0.

**-b**
  Renumber program backwards (line numbers in descending
  order). This option is completely useless, but exists for testing
  purposes. Programs renumbered this way won't *RUN* correctly,
  although they will *LOAD* and *LIST*. When using this option, set
  **-s** to a higher number than the default.

.. include:: genopts.rst

DIAGNOSTICS
===========

Fatal: Program is code-protected; unprotect it first.
  Use **unprotbas** to remove the protection, if you get this error.

Fatal: New line number *num* would be >32767.
  32767 is the highest line number BASIC allows.
  Use a lower starting line (**-s**) and/or increment (**-i**).

Warning: Computed *cmd* at line *num*.
  The line number for a *GOTO*, *GOSUB*, etc is normally adjusted to
  whatever the line got renumbered to. This warning means that **renumbas**
  couldn't adjust the line number, because it's a computed value such as
  *GOTO A+100*. You'll have to fix this manually. *num* is the original
  line number, not the renumbered one.

Warning: Line *num1* references nonexistent line *num2*.
  Usually indicates a bug in the BASIC program. Example: *GOTO 100*,
  but there is no line 100. *num1* is the original line number, not the
  renumbered one.

Renumbering line *num1* as *num2* (*num3* refs).
  Only seen when the **-v** (verbose) option is used. Just an informational
  message.

Warning line numbers
--------------------
Any warning that includes a line number (such as "Computed line number") will
have the original line number, *not* the renumbered one. This is because
the warnings are generated while scanning the program to find line number
references, which happens before the actual renumbering (so the new number
isn't known yet).

LIMITATIONS
===========

A pathological case::

  100 GOTO 200+0

200+0 is considered a computed line number, even though the results of
the computation are constant. This is because neither Atari BASIC nor
**renumbas** does constant folding.

This shouldn't be a real-world problem; did *you* ever write code like
that in Atari BASIC?

EXIT STATUS
===========

0 for success, 1 for failure.

.. include:: manftr.rst