.\" 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 "LISTAMSB" 1 "2025-03-17" "0.2.2" "Urchlay's Atari 8-bit Tools"
.SH NAME
listamsb \- List the source of a tokenized Atari Microsoft BASIC program
.SH SYNOPSIS
.sp
listamsb [\fB\-U\fP] | [\fB\-C\fP [\fB\-k\fP]] | [\fB\-D\fP] | [[\fB\-L\fP] [\fB\-a\fP] [\fB\-c\fP] [\fB\-v\fP] [\fB\-h\fP] [\fB\-i\fP] [\fB\-u\fP] [\fB\-t\fP] [\fB\-m\fP] [\fB\-M\fP] [\fB\-n\fP] [\fB\-s\fP] [\fB\-r\fP \fIline\-range\fP] ...] [\fBinput\-file\fP] [\fBoutput\-file\fP]
.SH DESCRIPTION
.sp
\fBlistamsb\fP acts like the \fILIST\fP command in Atari Microsoft BASIC. It reads a
tokenized (SAVEd) AMSB program and prints the code in human\-readable
format.
.sp
\fBlistamsb\fP supports both versions of Atari Microsoft BASIC: the
disk\-based version 1 and the cartridge\-based version 2. The language
is the same for both versions, so there\(aqs no need to specify it.
.sp
\fBinput\-file\fP must be a tokenized AMSB program. If no \fBinput\-file\fP is given,
input is read from \fBstdin\fP\&.
.sp
Programs created with \fISAVE "filename" LOCK\fP are autodetected,
and will be listed normally. It\(aqs also possible to convert a LOCKed
program to an unencrypted one, with the \fB\-U\fP option.
.sp
Programs can be "crunched" and "decrunched" with the \fB\-C\fP and \fB\-D\fP
options.
.sp
If no \fBoutput\-file\fP is given, output is to \fBstdout\fP\&. When output
is to a file, the file will be overwritten without prompting if it
already exists.
.sp
When listing a program to \fBstdout\fP, output is piped through
\fBa8cat\fP(1), which converts the ATASCII output to UTF\-8 that\(aqs
human\-readable on modern terminals. This means \fBa8cat\fP must be
available in your \fBPATH\fP\&. If this is not convenient, you can set
the location of \fBa8cat\fP via the \fBA8CAT\fP environment variable.
When listing in color (when the \fB\-M\fP option is not used), \fBa8cat\fP\(aqs
output is piped through \fBcolorize\-amsb\fP, which also must be available
in your \fBPATH\fP\&.
.sp
\fBlistamsb\fP will not write binary data (ATASCII or tokenized BASIC)
directly to a terminal, under any circumstances.
.SH OPTIONS
.SS Operation Modes
.INDENT 0.0
.TP
.B \fB\-L\fP
LIST program. This is the default, so there\(aqs no need to give this option
normally. See next section for options that control the listing.
.TP
.B \fB\-C\fP
"Crunch" program: remove comments and spaces that occur outside of a
string. The resulting program is tokenized, and is usually 5 to 10
percent smaller. It should RUN correctly, but will be difficult to
edit in AMSB because its parser requires the spaces.
.sp
The crunched program will always be unLOCKed.
.sp
If any comment\-only lines are the target of GOTO or GOSUB, the
program won\(aqt RUN correctly because all comment\-only lines are
removed. If this happens, you can use the \fB\-k\fP option (see below).
.sp
This option must be used with an \fBoutput\-file\fP, since seeking is done.
None of the other options have any effect with \fB\-C\fP\&.
.TP
.B \fB\-D\fP
"Decrunch" a crunched program. Puts spaces where they\(aqre required for
AMSB\(aqs parser. The resulting program is tokenized, and will be
editable in AMSB. Of course, any comments that were removed during
crunching will not magically be restored (they\(aqre gone).
.sp
The decrunched program will always be unLOCKed.
.sp
This option must be used with an \fBoutput\-file\fP, since seeking is done.
None of the other options have any effect with \fB\-D\fP\&.
.TP
.B \fB\-U\fP
UnLOCK or LOCK the the program. Locked programs are created with
\fISAVE "filename" LOCK\fP\&. The "encryption" is a reciprocal cipher: locking and
unlocking are the same operation (similar to ROT13). The output will
be the locked or unlocked tokenized program (rather than a listing).
.sp
This option must be used with an \fBoutput\-file\fP, a pipe, or
redirection: \fBlistamsb\fP will not write tokenized BASIC to a
terminal. None of the other options have any effect with \fB\-U\fP\&.
.UNINDENT
.SS Options for \fB\-L\fP (list) Mode
.sp
None of these options have any effect when used with \fB\-C\fP, \fB\-D\fP,
or \fB\-U\fP\&.
.INDENT 0.0
.TP
.B \fB\-a\fP
Output raw ATASCII. This option must be used with an
\fBoutput\-file\fP, a pipe, or redirection: \fBlistamsb\fP will not write
ATASCII to a terminal. \fBa8cat\fP and \fBcolorize\-amsb\fP are not used, with this option.
.TP
.B \fB\-c\fP
Check only. No output on \fBstdout\fP\&. Diagnostics are still printed on stderr,
and the exit status is unchanged. It\(aqs an error to give an \fBoutput\-file\fP with
this option.
.TP
.B \fB\-i\fP, \fB\-u\fP, \fB\-t\fP, \fB\-m\fP, \fB\-s\fP
These options are passed to \fBa8cat\fP\&. See its man page for details.
.TP
.B \fB\-M\fP
Monochrome listing: disable color syntax highlighting, meaning \fBcolorize\-amsb\fP
is not used.
.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\- or hyphen\-separated pair of starting and ending line numbers (e.g. \fB100,200\fP, or
\fB1000\-2000\fP).
.sp
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 or \fB\-r\-\fP is equivalent to not using the \fB\-r\fP option at all.
.TP
.B \fB\-n\fP
No empty line. By default, \fBlistamsb\fP prints an empty line at the
start of the output, to match AMSB\(aqs LIST command.
.UNINDENT
.SS Options for \fB\-C\fP (crunch) Mode
.INDENT 0.0
.TP
.B \fB\-k\fP
Keep comment\-only lines. Normally these are removed. If the program
gives UNDEF\(aqD LINE ERROR, it means the target line was a comment\-only
line that got removed. With \fB\-k\fP, these lines will be kept, although
the actual comments won\(aqt (\fI10 REM HELLO\fP will become \fI10 REM\fP).
.UNINDENT
.SS Utility Options
.INDENT 0.0
.TP
.B \fB\-v\fP
Verbose output, on \fBstderr\fP\&. May be given twice for extra verbosity,
which shows each line number, its offset, length, and end\-of\-line pointer.
Can be used with any of the mode options (\fB\-C\fP, \fB\-D\fP, \fB\-L\fP, \fB\-U\fP).
.TP
.B \fB\-h\fP, \fB\-\-help\fP
Print built\-in help and exit.
.TP
.B \fB\-\-version\fP
Print version number and exit.
.UNINDENT
.SH DIAGNOSTICS
.sp
All error and warning messages are written to the standard error output.
.SS Fatal errors
.sp
These are errors in the program header at the start of the file. They
generally mean the input isn\(aqt actually an tokenized Atari Microsoft
BASIC file.
.INDENT 0.0
.IP \(bu 2
not an AMSB file: first byte not $00 or $01
.sp
Pretty self\-explanatory: if the file doesn\(aqt begin with a \fI$00\fP or
\fI$01\fP byte, it\(aqs not a tokenized AMSB file.
.IP \(bu 2
not an AMSB file: too big (\fIN\fP bytes), won\(aqt fit in Atari memory
.sp
The file can\(aqt be a tokenized AMSB file because there was no way
for it to be created. It must be some other kind of file that begins
with a \fI$00\fP byte.
.IP \(bu 2
not an AMSB file: program size too small (\fIN\fP). Atari BASIC file?
.sp
The program header claims the file is 0, 1, 3, or 4 bytes long. This
is impossible, so this isn\(aqt an AMSB file. A lot of Atari BASIC
programs begin with three \fI$00\fP bytes, so that might be what this is.
.IP \(bu 2
program length is 2, no code in file (SAVE after NEW)
.sp
Probably, someone did a SAVE when there was no program in memory. It
could also mean this isn\(aqt an AMSB file at all.
.UNINDENT
.SS Warnings
.sp
These are non\-fatal: \fBlistamsb\fP logs the warning to stderr, then
continues processing.
.INDENT 0.0
.IP \(bu 2
unexpected EOF, file truncated?
.sp
A tokenized AMSB file always ends with three null bytes (\fI$00\fP).
This file doesn\(aqt. Probably the rest of the file is missing.
.IP \(bu 2
line \fIL\fP: EOL address \fIA\fP too (low|high)
.sp
Each line begins with the address of the next line. If the address
is below \fI$0700\fP, it\(aqs below the minimum value of \fIMEMLO\fP, which
is impossible. If it\(aqs above \fI$bc1f\fP, it would be in the display
list, screen memory, or OS ROM (also impossible). File is
corrupt, or not an AMSB file.
.IP \(bu 2
line \fIL\fP: EOL address \fIA\fP <= previous \fIB\fP
.sp
Corrupt file, or not an AMSB file.
.IP \(bu 2
line \fIL\fP is suspiciously long
.sp
The line is >128 bytes long, but less than 256. AMSB can execute
lines of this length, but it\(aqs impossible to actually enter them
in the editor, because a logical line can\(aqt be longer than 3
screen lines. Possibly corrupted file.
.IP \(bu 2
line \fIL\fP is impossibly long
.sp
The line is >= 256 bytes long. AMSB will crash, if you try to
LOAD the file. Corrupted file.
.IP \(bu 2
line \fIL\fP EOL address doesn\(aqt match actual line length \fIN\fP
.sp
Corrupt file, or not an AMSB file.
.IP \(bu 2
line number out of order
.sp
Corrupt file, or not an AMSB file.
.IP \(bu 2
line number out range
.sp
The program contains a line number that\(aqs greater than \fI63999\fP\&. How
did that happen?
.IP \(bu 2
line \fIL\fP has character \fIC\fP outside of a string. maybe Atari BASIC?
.sp
This happens when ATASCII codes 0 to 31 (\fI$1f\fP) appear in the program.
AMSB can create files like this, but at runtime, it\(aqs a syntax error.
More likely, it means this is an Atari BASIC file.
.IP \(bu 2
program size doesn\(aqt match size in header
.sp
Might mean this isn\(aqt an AMSB file. If you\(aqre sure it is, it might
be truncated, or part of the file might have been overwritten with
\fI$00\fP bytes. It could also mean the length in the header has somehow
gotten corrupted.
.IP \(bu 2
trailing garbage at end of file
.sp
Might mean this isn\(aqt an AMSB file. If you\(aqre sure it is, garbage
data has somehow gotten appended to the file, after the three \fI$00\fP
bytes that end the program. Maybe it was downloaded with a crappy
version of XMODEM that pads the last block. The good news is,
AMSB will just ignore the garbage when you LOAD the file, so it
won\(aqt hurt anything.
.IP \(bu 2
file has \fIN\fP unknown tokens
.sp
Either the file is corrupt, or this is a file from some \fIother\fP variant
of Microsoft BASIC (e.g. Commodore, AppleSoft, GW\-BASIC, TRS\-80). If
you see this warning, you\(aqll also see \fIN\fP <unknown token \fIXX\fP>
messages in the actual listing.
.UNINDENT
.SH ENVIRONMENT
.sp
\fBA8CAT\fP
.INDENT 0.0
.INDENT 3.5
The path to the \fBa8cat\fP(1) binary. Can be a full path or just
the executable name, in which case it will be searched for with the
normal \fBPATH\fP mechanism. If not set, \fIa8cat\fP is used. If there are
spaces or other metacharacters, they must be escaped.
.UNINDENT
.UNINDENT
.SH LIMITATIONS
.sp
\fBlistamsb\fP may behave strangely when fed something other than a
tokenized AMSB program, at least if the first byte in the file
is \fB$00\fP or \fB$01\fP\&. Unfortunately, tokenized Atari BASIC (and
variants like Turbo and BASIC XL) begin with \fB$00\fP\&. Usually
you\(aqll get this error:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
not an AMSB file: program size too small (0). Atari BASIC file?
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\&...but occasionally you may get a bunch of warnings and gibberish
output instead.
.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 had errors or warnings (see
\fBDIAGNOSTICS\fP).
.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),
\fBlistamsb\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.
.