path: root/listbas.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 "LISTBAS" 1 "2024-07-24" "0.2.1" "Urchlay's Atari 8-bit Tools"
.SH NAME
listbas \- List the source of a tokenized Atari 8-bit BASIC program
.SH SYNOPSIS
.sp
listbas [\fB\-a\fP | \fB\-d\fP | \fB\-m\fP | \fB\-x\fP | \fB\-U\fP] [\fB\-B\fP] [\fB\-u\fP] [\fB\-i\fP] [\fB\-l\fP] [\fB\-n\fP | \fB\-C\fP] [\fB\-v\fP] [\fB\-c\fP \fIcolors\fP] [\fB\-r\fP \fIline\-range\fP] \fBinput\-file\fP
.SH DESCRIPTION
.sp
\fBlistbas\fP acts like the \fILIST\fP command in BASIC. It reads a
tokenized (SAVEd) BASIC program and prints the code in human\-readable
format.
.sp
By default, output is Unicode in UTF\-8 encoding, with ANSI/VT220
escape sequences for inverse video and color syntax highlighting.
.sp
\fBlistbas\fP supports several BASIC dialects used on the Atari. By
default, the BASIC dialect is autodetected by running \fBwhichbas\fP(1)
as an external process. To override this, see the \fB\-b\fP option, below.
.SH OPTIONS
.SS BASIC options
.INDENT 0.0
.TP
.B \fB\-b\fP
Set the BASIC dialect the program will be treated as. This disables
autodetection. Supported dialects are:
.INDENT 7.0
.TP
.B \fB\-ba\fP
Atari BASIC.
.TP
.B \fB\-ba+\fP
OSS BASIC/A+.
.TP
.B \fB\-bt\fP
Turbo BASIC XL.
.TP
.B \fB\-bxl\fP
OSS BASIC XL.
.TP
.B \fB\-bxe\fP
OSS BASIC XE.
.UNINDENT
.sp
See \fBBASIC DIALECTS\fP below for details.
.TP
.B \fB\-r\fP \fIline\-range\fP
Show only part of the listing. \fIline\-range\fP can be a single line, or
a comma\-separated pair of starting and ending line numbers (e.g. \fB100,200\fP).
If the start line number is omitted (e.g. \fB,100\fP), it will be treated as
\fB0\fP (meaning, list from the beginning of the program). If the ending line
number is omitted (e.g. \fB100,\fP), it means "list until the end of the program".
\fB\-r,\fP is equivalent to not using the \fB\-r\fP option at all.
.TP
.B \fB\-i\fP
Include the immediate mode command (line 32768) in the output. This option has no
effect if the \fB\-r\fP option is used to stop listing before the end of the program.
.TP
.B \fB\-l\fP
Do not print line numbers at the start of each line. \fBGOTO\fP, \fBGOSUB\fP,
\fBTRAP\fP, and \fBTHEN\fP target line numbers are still printed.
.TP
.B \fB\-t\fP
Do not indent, if the program is Turbo BASIC, BASIC/A+, BASIC XL, or BASIC XE.
By default, indentation is enabled for everything but Atari BASIC.
If you want to indent an Atari BASIC program, use \fB\-bt\fP or \fB\-bxe\fP\&.
.TP
.B \fB\-k\fP
Do not print keywords in mixed case (e.g. \fBPrint\fP, \fBGraphics\fP),
for BASIC XL or BASIC XE. Equivalent of \fBSET 5,0\fP\&.
.UNINDENT
.SS Output modes
.sp
The default output mode is Unicode/UTF\-8 representations of ATASCII
characters.
.INDENT 0.0
.TP
.B \fB\-U\fP
Output Unicode/UTF\-8 representations of ATASCII characters. This is
the default output mode; the \fB\-U\fP option is provided so you can
override \fB\-a\fP, \fB\-d\fP, \fB\-m\fP, \fB\-x\fP in \fBLISTBAS_OPTS\fP (see
\fBENVIRONMENT\fP, below).
.TP
.B \fB\-x\fP
Output Unicode/UTF\-8 representations of the XL International Character
Set, rather than ATASCII.
.TP
.B \fB\-a\fP
Output raw ATASCII; no translation to the host character set. Must be
used with redirection or a pipe; \fBlistbas\fP will not write ATASCII to the terminal.
ATASCII output does not support color (because ATASCII doesn\(aqt).
.TP
.B \fB\-m\fP
Output "magazine listing". See the \fB\-m\fP option for \fBa8cat\fP(1) for details.
Color is supported in this mode. No Unicode/UTF\-8 characters are printed in
this mode.
.TP
.B \fB\-d\fP
Print dots rather than Unicode/UTF\-8 characters. Color and inverse
video are still supported in this mode, but no Unicode/UTF8 characters
are printed. Use this only if your terminal \fIreally\fP doesn\(aqt support
Unicode (e.g. \fBrxvt\fP(1))... but even then, \fB\-m\fP is preferred,
because you can\(aqt tell what the dots are supposed to represent.
.UNINDENT
.SS Other display options
.INDENT 0.0
.TP
.B \fB\-C\fP
Enable color syntax highlighting. This option is enabled by default;
the \fB\-C\fP option is provided so you can override \fB\-n\fP in
\fBLISTBAS_OPTS\fP (see \fBENVIRONMENT\fP, below).
.TP
.B \fB\-n\fP
No color. Has no effect if \fB\-a\fP is in effect, since this
mode doesn\(aqt support color anyway. Disabling color does not
disable reverse video.
.TP
.B \fB\-B\fP
Use bold for color output. This may make it easier to read on
some terminals. Or, it may hurt your eyes...
.TP
.B \fB\-u\fP
Use underlining for inverse video, rather than reverse video output.
.TP
.B \fB\-c\fP \fIcolors\fP
Customize the color scheme. See \fBCOLORS\fP, below, for the format of the
\fIcolors\fP argument. Once you\(aqve found a set of colors you like,
you can place this option in the \fBLISTBAS_OPTS\fP environment variable
to use your colors by default. See \fBENVIRONMENT\fP, below.
.UNINDENT
.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 DIALECTS
.sp
Note that Turbo, BASIC XL, and BASIC XE are all proper supersets of
Atari BASIC, so you can view an Atari BASIC program with any of
\fB\-bt\fP, \fB\-bxl\fP, or \fB\-bxe\fP\&. Also, BASIC XE is a superset of BASIC XL
(provided BASIC XL\(aqs disk\-based toolkit extended commands are not used),
so you can usually use \fB\-bxe\fP on a BASIC XL program.
.sp
BASIC/A+ uses incompatible tokens, so its programs can\(aqt be viewed as
any of the others. Trying to do this results in a very funny\-looking
listing, with commands like \fBPOSITION\fP with no arguments (or with a
string argument, or \fBPOSITION #6;"string"\fP; it so happens A+ uses the
same token number for \fBPOSITION\fP that the other BASICs use for
\fB?\fP). The same thing would happen if you booted BASIC/A+ on an Atari
and tried to \fBLOAD\fP an Atari BASIC program. I can\(aqt help but think
this is a major reason BASIC/A+ didn\(aqt sell that well (fortunately,
OSS realized their mistake and fixed it in BASIC XL).
.sp
If you see lots of "bad token XX" messages, or if the code
just doesn\(aqt make any sense, you\(aqre using the wrong BASIC
option. \fBwhichbas\fP(1) can usually detect the BASIC a program was
written in, but if the results are ambiguous, \fBlistbas\fP will assume
Turbo BASIC XL. If this is wrong, use \fB\-bxl\fP or \fB\-bxe\fP to force
the issue.
.SH COLORS
.sp
Color output only works on terminal emulators (or real terminals)
that support ANSI/VT220 style escape codes. This includes all modern
terminal emulators, and most not\-so\-modern ones in the UNIX world. See
\fBNOTES\fP for a list of tested terminal emulators.
.sp
You can customize the colors by using the \fB\-c\fP \fIcolors\fP option, either
on the command line, or in the \fBLISTBAS_OPTS\fP environment variable.
\fIcolors\fP is a string of exactly 8 characters, each of which must be the
digits \fI0\fP through \fI7\fP to specify a color, or the letter \fIn\fP to specify
no color.
.sp
The colors are the standard ANSI ones, plus \fIn\fP:
.INDENT 0.0
.TP
.B \fI0\fP
Black.
.TP
.B \fI1\fP
Red.
.TP
.B \fI2\fP
Green.
.TP
.B \fI3\fP
Yellow (or brown/orange, on some terminals).
.TP
.B \fI4\fP
Blue.
.TP
.B \fI5\fP
Purple (aka violet).
.TP
.B \fI6\fP
Cyan.
.TP
.B \fI7\fP
White.
.TP
.B \fIn\fP
No custom color. Output will be in the terminal\(aqs default foreground color.
.UNINDENT
.sp
The order they\(aqre used in the \fIcolors\fP argument is:
.INDENT 0.0
.TP
.B \fB1\fP
BASIC keywords. Default: \fI3\fP (yellow).
.TP
.B \fB2\fP
Operators, including quotes around strings and commas between \fBDATA\fP items. Default: \fI2\fP (green).
.TP
.B \fB3\fP
Functions. Default: \fI5\fP (purple).
.TP
.B \fB4\fP
Constants (numeric or string). Default: \fI1\fP (red).
.TP
.B \fB5\fP
Line numbers (at the start of a line only; \fBGOTO\fP and \fBGOSUB\fP line numbers
are constants). Default: \fI6\fP (cyan).
.TP
.B \fB6\fP
\fBREM\fP text. Default: \fI4\fP (blue).
.TP
.B \fB7\fP
\fBDATA\fP items (but not the commas between them). Default: \fI6\fP (cyan).
.TP
.B \fB8\fP
Variable names. Default: \fIn\fP (uncolorized).
.UNINDENT
.sp
So, the default color scheme is equivalent to:
.INDENT 0.0
.INDENT 3.5
\fB\-c\fP \fI3251646n\fP
.UNINDENT
.UNINDENT
.sp
Black and white are not used by default because presumably, one or the
other is the background color of the terminal.
.SH NOTES
.SS Indentation
.sp
The indentation isn\(aqt all that well\-tested yet, but so far it seems work
correctly. The \fB\-t\fP option is the equivalent of \fB*L\-\fP for Turbo,
or \fBSET 12,0\fP for BXL/BXE. The different BASICs have different
indentation rules; try viewing the same Atari BASIC program with
\fB\-bt\fP, \fB\-bxl\fP, and \fB\-bxe\fP to compare them.
.sp
\fBlistbas \-t\fP is also (as far as I know) the only way to \fBLIST\fP
a BASIC/A+ program without indentation, since BASIC/A+ itself doesn\(aqt
have a way to disable it.
.sp
Turbo BASIC, at least, will "max out" the indentation level at some
point. Once there are 60 or so levels of indent, it stops adding
more. \fBlistbas\fP doesn\(aqt emulate this behaviour (shouldn\(aqt be a
problem, it\(aqs a pathological case).
.sp
BASIC XL actually does indentation within a line. If you write:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
10 IF A:IF B:IF C:REM
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\&...BXL lists it as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
10   If A:  If B:  If C:Rem
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBlistbas\fP only indents at the start of a line, so this behaviour is
not emulated.
.sp
One thing \fBlistbas\fP gets right: the \fBLIST\fP command in Turbo, A+,
BXL, and BXE always starts out with 0 indent spaces, if you\(aqre only
listing part of a program. BXE example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
10 While 1
20   If Peek(764)<>255
30     ? "SOMEONE PRESSED A KEY":Poke 764,255
40   Endif
50 Endwhile
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\&...but if you give a \fBLIST 30\fP in BXE, you\(aqll get line 30 without any
indentation. \fBlistbas\fP does this, too, if you use the \fB\-r\fP option.
.SS Protected Programs
.sp
\fBlistbas\fP will refuse to operate on a LIST\-protected program with
scrambled variable names. For code\-protected programs, it will stop at
the line with the invalid offset. Use \fBunprotbas\fP(1) to remove the
protection.
.SS Comparison to chkbas
.sp
\fBlistbas\fP is similar to Jindroush\(aqs \fBchkbas\fP(1). The main differences are:
.INDENT 0.0
.IP \(bu 2
\fBlistbas\fP prints ATASCII graphics as Unicode equivalents, so the listing
looks very similar to how it would appear on the Atari.
.IP \(bu 2
\fBlistbas\fP does color syntax highlighting.
.IP \(bu 2
\fBlistbas\fP supports OSS BASIC/A+ in addition to Turbo and BXL/BXE.
.IP \(bu 2
\fBlistbas\fP indents BASIC/A+, Turbo, BXL, and BXE code, just like the
actual BASICs do.
.IP \(bu 2
\fBlistbas\fP doesn\(aqt show information about the variables. Use \fBvxrefbas\fP(1)
for that.
.IP \(bu 2
\fBlistbas\fP will not write ATASCII data to your terminal. By default, it
converts ATASCII characters into Unicode/UTF\-8 characters
that won\(aqt confuse the terminal. When outputting raw ATASCII (\fB\-a\fP option),
it refuses to run if standard output is a terminal.
.IP \(bu 2
\fBlistbas\fP only lists line 32768 (the immediate mode command) if
specifically asked to do so.
.IP \(bu 2
\fBlistbas\fP doesn\(aqt print a banner on startup.
.IP \(bu 2
\fBlistbas\fP tells you if the program is protected, and refuses to operate
on variable\-protected programs. For code\-protected programs, it lists
the program up to the "poisoned" line (normally the last line).
.UNINDENT
.SS Terminal Support
.sp
The color and inverse/bold/underline support assumes your terminal supports
ANSI/VT220 escape codes... but it does \fInot\fP use \fBcurses\fP(3X) or
\fBterminfo\fP(5), or even look at \fBTERM\fP in the environment. It just
blindly emits the escape codes. Likewise, Unicode characters are printed
in UTF\-8 encoding, without actually checking whether the terminal or the
current locale supports UTF\-8.
.sp
\fBlistbas\fP has been tested and is known to work in at least these
terminals:
.INDENT 0.0
.INDENT 3.5
\fBrxvt\-unicode\fP, aka \fBurxvt\fP\&. This is the terminal the author uses.
.sp
\fBxterm\fP \- tested frequently. Requires the XTerm.locale resource
to be set to \fBUTF\-8\fP (e.g. in \fB~/.Xdefaults\fP), or the \fB\-lc\fP
and/or \fB\-en UTF\-8\fP command line options.
.sp
\fBLinux console\fP \- works fine, but good luck finding a font with
all the Unicode graphics characters. Better use \fB\-m\fP\&.
.sp
\fBkitty\fP \- very fancy terminal emulator that supports both X11 and
Wayland. \fBlistbas\fP was only tested on X11.
.sp
\fBxfce4\-terminal\fP \- version 0.8.10, with XFCE4 4.16.0.
.sp
\fBkonsole\fP \- the KDE terminal, from KDE 5.90.
.sp
\fBgnome\-terminal\fP \- version 3.43.90.
.sp
\fBst\fP \- minimal terminal from suckless.org, version 0.9.2.
.sp
\fBmlterm\fP \- version 3.9.3.
.sp
\fBkmscon\fP \- version 9.0.0. \fI\%https://github.com/Aetf/kmscon\fP
.sp
\fBfbterm\fP \- version 1.8. \fI\%https://github.com/sfzhi/fbterm\fP
.UNINDENT
.UNINDENT
.sp
Also, \fBrxvt\fP and \fBaterm\fP don\(aqt support Unicode, but they will
otherwise work (display color and inverse) with the \fB\-m\fP or \fB\-d\fP
options to \fBlistbas\fP\&.
.SS HTML Output
.sp
I thought about adding an HTML output option, but there\(aqs no need: if you want
a colorful listing of an Atari BASIC program, install \fBaha\fP(1) from
\fI\%https://github.com/theZiz/aha\fP (or your distro\(aqs package repo) and run
something like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
listbas PROGRAM.BAS | aha > program.html
.ft P
.fi
.UNINDENT
.UNINDENT
.SH ENVIRONMENT
.INDENT 0.0
.TP
.B \fBLISTBAS_OPTS\fP
If this environment variable is set, \fBlistbas\fP parses its value as though
the contents were placed on the command line as options, preceding any actual
option. Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
export LISTBAS_OPTS="\-c123456 \-d"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you place the above line in your shell\(aqs startup script, \fBlistbas\fP will
use your custom color scheme, and will default to the "dots" output mode. If
you then run \fBlistbas\fP the \fB\-c\fP and/or \fB\-x\fP, \fB\-m\fP options, the options
on the command line will override the environment.
.UNINDENT
.SH EXIT STATUS
.sp
0 for success, 1 if there was an error reading the input (e.g. file
not found), or 2 if the input file has invalid tokens (if this
happens, you will also see a warning about it on stderr).
.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.
.