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

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

.. include:: manhdr.rst

SYNOPSIS
========
renumbas [**-v**] [**-s** *start-lineno*] [**-i** *increment*] [**-f** *first-lineno*] *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.

.. include:: genopts.rst

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?

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).

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

0 for success, 1 for failure.

.. include:: manftr.rst