path: root/bas2aplus.1

.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BAS2APLUS" 1 "2024-07-24" "0.2.1" "Urchlay's Atari 8-bit Tools"
.SH NAME
bas2aplus \- Convert Atari BASIC (and some BASIC XL/XE) programs to BASIC/A+
.SH SYNOPSIS
.sp
bas2aplus \fIinput\-file\fP \fIoutput\-file\fP
.SH DESCRIPTION
.sp
\fBbas2aplus\fP 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.
.sp
\fIinput\-file\fP 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 \fBRUN\fP\&.
.sp
All Atari BASIC programs can be successfully converted. Some BASIC
XL/XE tokens have no equivalent in BASIC/A+, so programs using these
can\(aqt be converted (you will see messages on standard error, in that
case).
.SH OPTIONS
.SS General Options
.INDENT 0.0
.TP
.B \fB\-\-help\fP
Print usage message and exit.
.TP
.B \fB\-\-version\fP
Print version number and exit.
.TP
.B \fB\-v\fP
Verbose operation. When displaying a number in verbose mode, it will
be prefixed with \fI$\fP if it\(aqs in hex, or no prefix for decimal.
.UNINDENT
.SH BASIC
.sp
BASIC/A+ is basically a later version of Atari BASIC, by the same team
that developed Atari BASIC. As such, it\(aqs source\-compatible with Atari
BASIC, but \fInot\fP token\-compatible.
.sp
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.
.sp
The two missing tokens are the \fBCOM\fP and \fBGO TO\fP commands, which
are converted to \fBDIM\fP and \fBGOTO\fP, respectively.
.sp
The resulting program should \fBLOAD\fP and \fBRUN\fP in BASIC/A+ and
function identically to the BASIC version, unless it uses memory
that\(aqs reserved in A+. \fBUSR()\fP 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.
.SH BASIC XL
.sp
BASIC XL is basically the next version of BASIC/A+, by the
same developers. The token lists were rearranged so that it\(aqs
token\-compatible with Atari BASIC, and includes all the extra
commands/functions/etc from BASIC/A+... with different token numbers.
.sp
BASIC XL has keywords and operators that don\(aqt exist in BASIC/A+,
which can\(aqt be translated by \fBbas2aplus\fP\&. These are:
.INDENT 0.0
.TP
.B \fBNUM\fP
Rarely found in a program (usually only used in direct mode).
.TP
.B \fBFAST\fP
Just doesn\(aqt exist in BASIC/A+.
.TP
.B \fBLOCAL\fP, \fBEXIT\fP, \fBPROCEDURE\fP, \fBCALL\fP, \fBSORTUP\fP, \fBSORTDOWN\fP
These BASIC XL commands are provided by the disk\-based Toolkit
extension, which doesn\(aqt exist for BASIC/A+.
.TP
.B \fBString Arrays\fP
BASIC/A+ doesn\(aqt support these; if your BASIC XL program uses them,
it won\(aqt convert correctly.
.TP
.B \fBBUMP\fP and \fBFIND\fP
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\(aqre not supported.
.TP
.B \fB%\fP
The exclusive OR operator in BASIC XL. No such animal, in A+.
.TP
.B \fBHEX$\fP, \fBRANDOM\fP, \fBLEFT$\fP, \fBRIGHT$\fP, \fBMID$\fP
These functions don\(aqt exist in BASIC/A+.
.UNINDENT
.sp
Also, BASIC XL supports hex constants, with a leading \fB$\fP\&. A+
doesn\(aqt support these, so they get converted to the equivalent decimal
constant. This is basically a cosmetic change; \fBA=$0600\fP assigns the
same value as \fBA=1536\fP\&.
.sp
BASIC XL also allows some syntax that\(aqs not valid in BASIC
A+. For instance, \fBDIR\fP is allowed with no argument in XL.
\fBbas2aplus\fP doesn\(aqt detect these constructs.
.SH BASIC XE
.sp
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 \fInot\fP supported by
\fBbas2aplus\fP\&. Only non\-EXTENDed BASIC XE programs can be converted.
.sp
BASIC XE adds a few keywords to BASIC XL, which also don\(aqt exist in
A+. These are:
.INDENT 0.0
.TP
.B \fBEXTEND\fP
This command is direct\-mode only, so it will never appear in a SAVEd
program anyway.
.TP
.B \fBHITCLR\fP, \fBINVERSE\fP, \fBNORMAL\fP, \fBBLOAD\fP, \fBBSAVE\fP
Not supported in either A+ or XL.
.UNINDENT
.sp
BASIC XE also allows some syntax that\(aqs not valid in either BASIC XL
or A+. For instance, \fBIF <condition>\fP, without \fBTHEN\fP, can appear
as the last statement on a line, and \fBLVAR\fP no longer requires an
argument. \fBbas2aplus\fP doesn\(aqt detect these constructs.
.sp
Actually, BASIC/A+ will \fBLIST\fP and \fBRUN\fP programs with the \fBIF\fP
issue, but such lines can\(aqt be edited in A+. Easy enough to add a
\fB:REM\fP to the end of the line, though.
.SH TURBO BASIC
.sp
Not supported. It\(aqs also an extended version of Atari BASIC (by
a different developer), but extends the syntax in ways that just
wouldn\(aqt convert directly to BASIC/A+.
.SH EXIT STATUS
.sp
0 for success, non\-zero for failure.
.SH COPYRIGHT
.sp
WTFPL. See \fI\%http://www.wtfpl.net/txt/copying/\fP for details.
.SH AUTHOR
.INDENT 0.0
.IP B. 3
Watson <\fI\%urchlay@slackware.uk\fP>; Urchlay on irc.libera.chat \fI##atari\fP\&.
.UNINDENT
.SH SEE ALSO
.sp
\fBa8cat\fP(1),
\fBa8eol\fP(1),
\fBa8xd\fP(1),
\fBatr2xfd\fP(1),
\fBatrsize\fP(1),
\fBaxe\fP(1),
\fBbas2aplus\fP(1),
\fBblob2c\fP(1),
\fBblob2xex\fP(1),
\fBcart2xex\fP(1),
\fBcxrefbas\fP(1),
\fBdasm2atasm\fP(1),
\fBdiffbas\fP(1),
\fBdumpbas\fP(1),
\fBf2toxex\fP(1),
\fBfenders\fP(1),
\fBlistbas\fP(1),
\fBprotbas\fP(1),
\fBrenumbas\fP(1),
\fBrom2cart\fP(1),
\fBunmac65\fP(1),
\fBunprotbas\fP(1),
\fBvxrefbas\fP(1),
\fBwhichbas\fP(1),
\fBxex1to2\fP(1),
\fBxexamine\fP(1),
\fBxexcat\fP(1),
\fBxexsplit\fP(1),
\fBxfd2atr\fP(1),
\fBxex\fP(5),
\fBatascii\fP(7),
\fBfauxtari\fP(7).
.sp
Any good Atari 8\-bit book: \fIDe Re Atari\fP, \fIThe Atari BASIC  Reference
Manual\fP,  the  \fIOS Users\(aq Guide\fP, \fIMapping the Atari\fP, etc.
.\" Generated by docutils manpage writer.
.