=========
bas2aplus
=========

---------------------------------------------------------------
Convert Atari BASIC (and some BASIC XL/XE) programs to BASIC/A+
---------------------------------------------------------------

.. include:: manhdr.rst

SYNOPSIS
========

bas2aplus *input-file* *output-file*

DESCRIPTION
===========

**bas2aplus** reads an Atari BASIC or BASIC XL/XE tokenized (SAVEd)
program and converts it to BASIC/A+. The conversion is a simple token
replacement; no syntax or semantic analysis is done.

*input-file* must be an Atari BASIC, BASIC XL, or BASIC XE program.
Turbo BASIC is not supported. Trying to convert a program that is
already BASIC/A+ will appear to succeed, but the resulting program
will be gibberish and will likely crash BASIC/A+ when **RUN**.

All Atari BASIC programs can be successfully converted. Some BASIC
XL/XE tokens have no equivalent in BASIC/A+, so programs using these
can't be converted (you will see messages on standard error, in that
case).

OPTIONS
=======

.. include:: genopts.rst

BASIC
=====

BASIC/A+ is basically a later version of Atari BASIC, by the same team
that developed Atari BASIC. As such, it's source-compatible with Atari
BASIC, but *not* token-compatible.

BASIC/A+ uses a different set of token numbers, but has all but two
of the same tokens used by Atari BASIC. Conversion should always
succeed, for an Atari BASIC program.

The two missing tokens are the **COM** and **GO TO** commands, which
are converted to **DIM** and **GOTO**, respectively.

The resulting program should **LOAD** and **RUN** in BASIC/A+ and
function identically to the BASIC version, unless it uses memory
that's reserved in A+. **USR()** routines that are stored in the lower
half of Page 6 will have to be relocated, since A+ uses this area
itself. See the BASIC/A+ manual for full details.

BASIC XL
========

BASIC XL is basically the next version of BASIC/A+, by the
same developers. The token lists were rearranged so that it's
token-compatible with Atari BASIC, and includes all the extra
commands/functions/etc from BASIC/A+... with different token numbers.

BASIC XL has keywords and operators that don't exist in BASIC/A+,
which can't be translated by **bas2aplus**. These are:

**NUM**
  Rarely found in a program (usually only used in direct mode).

**FAST**
  Just doesn't exist in BASIC/A+.

**LOCAL**, **EXIT**, **PROCEDURE**, **CALL**, **SORTUP**, **SORTDOWN**
  These BASIC XL commands are provided by the disk-based Toolkit
  extension, which doesn't exist for BASIC/A+.

**String Arrays**
  BASIC/A+ doesn't support these; if your BASIC XL program uses them,
  it won't convert correctly.

**BUMP** and **FIND**
  While BASIC/A+ does support these functions, the token-level syntax
  is different; it would be possible to translate them, but it would
  require recalculating the line offset and statement offsets for
  every line that uses them. For now, they're not supported.

**%**
  The exclusive OR operator in BASIC XL. No such animal, in A+.

**HEX$**, **RANDOM**, **LEFT$**, **RIGHT$**, **MID$**
  These functions don't exist in BASIC/A+.

Also, BASIC XL supports hex constants, with a leading **$**. A+
doesn't support these, so they get converted to the equivalent decimal
constant. This is basically a cosmetic change; **A=$0600** assigns the
same value as **A=1536**.

BASIC XL also allows some syntax that's not valid in BASIC
A+. For instance, **DIR** is allowed with no argument in XL.
**bas2aplus** doesn't detect these constructs.

BASIC XE
========

BASIC XE is the last in the series of OSS BASIC interpreters. It
supports "EXTENDed" mode, which allows BASIC XE to use all the
memory in a 130XE, but such programs are *not* supported by
**bas2aplus**. Only non-EXTENDed BASIC XE programs can be converted.

BASIC XE adds a few keywords to BASIC XL, which also don't exist in
A+. These are:

**EXTEND**
  This command is direct-mode only, so it will never appear in a SAVEd
  program anyway.

**HITCLR**, **INVERSE**, **NORMAL**, **BLOAD**, **BSAVE**
  Not supported in either A+ or XL.

BASIC XE also allows some syntax that's not valid in either BASIC XL
or A+. For instance, **IF <condition>**, without **THEN**, can appear
as the last statement on a line, and **LVAR** no longer requires an
argument. **bas2aplus** doesn't detect these constructs.

Actually, BASIC/A+ will **LIST** and **RUN** programs with the **IF**
issue, but such lines can't be edited in A+. Easy enough to add a
**:REM** to the end of the line, though.

TURBO BASIC
===========

Not supported. It's also an extended version of Atari BASIC (by
a different developer), but extends the syntax in ways that just
wouldn't convert directly to BASIC/A+.

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

0 for success, non-zero for failure.

.. include:: manftr.rst