LISTBAS(1)

NAME
listbas - List the source of a tokenized Atari 8-bit BASIC program

SYNOPSIS

listbas [-a | -d | -m | -x | -U] [-B] [-u] [-i] [-l] [-n | -C] [-v] [-c colors] [-r line-range] input-file

DESCRIPTION

listbas acts like the LIST command in BASIC. It reads a tokenized (SAVEd) BASIC program and prints the code in human-readable format.

By default, output is Unicode in UTF-8 encoding, with ANSI/VT220 escape sequences for inverse video and color syntax highlighting.

listbas supports several BASIC dialects used on the Atari. By default, the BASIC dialect is autodetected by running whichbas(1) as an external process. To override this, see the -b option, below.

OPTIONS

  BASIC options

-b  Set the BASIC dialect the program will be treated as. This disables autodetection. Supported dialects are:

-ba Atari BASIC.

-ba+
    OSS BASIC/A+.

-bt Turbo BASIC XL.

-bxl
    OSS BASIC XL.

-bxe
    OSS BASIC XE.

    See BASIC DIALECTS below for details.

-r line-range
    Show only part of the listing. line-range can be a single line, or a comma-separated pair of starting and ending line numbers (e.g. 100,200). If the start line number is omitted (e.g. ,100), it will be treated as 0 (meaning, list from the beginning of the program). If the ending line number is omitted (e.g. 100,), it means "list until the end of the program". -r, is equivalent to not using the -r option at all.

-i  Include the immediate mode command (line 32768) in the output. This option has no effect if the -r option is used to stop listing before the end of the program.

-l  Do not print line numbers at the start of each line. GOTO, GOSUB, TRAP, and THEN target line numbers are still printed.

-t  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 -bt or -bxe.

-k  Do not print keywords in mixed case (e.g. Print, Graphics), for BASIC XL or BASIC XE. Equivalent of SET 5,0.

  Output modes

The default output mode is Unicode/UTF-8 representations of ATASCII characters.

-U  Output Unicode/UTF-8 representations of ATASCII characters. This is the default output mode; the -U option is provided so you can override -a, -d, -m, -x in LISTBAS_OPTS (see ENVIRONMENT, below).

-x  Output Unicode/UTF-8 representations of the XL International Character Set, rather than ATASCII.

-a  Output raw ATASCII; no translation to the host character set. Must be used with redirection or a pipe; listbas will not write ATASCII to the terminal. ATASCII output does not support color (because ATASCII doesn't).

-m  Output "magazine listing". See the -m option for a8cat(1) for details. Color is supported in this mode. No Unicode/UTF-8 characters are printed in this mode.

-d  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 really doesn't support Unicode (e.g. rxvt(1))... but even then, -m is preferred, because you can't tell what the dots are supposed to represent.

  Other display options

-C  Enable color syntax highlighting. This option is enabled by default; the -C option is provided so you can override -n in LISTBAS_OPTS (see ENVIRONMENT, below).

-n  No color. Has no effect if -a is in effect, since this mode doesn't support color anyway. Disabling color does not disable reverse video.

-B  Use bold for color output. This may make it easier to read on some terminals. Or, it may hurt your eyes...

-u  Use underlining for inverse video, rather than reverse video output.

-c colors
    Customize the color scheme. See COLORS, below, for the format of the colors argument. Once you've found a set of colors you like, you can place this option in the LISTBAS_OPTS environment variable to use your colors by default. See ENVIRONMENT, below.

  General Options

--help
    Print usage message and exit.

--version
    Print version number and exit.

-v  Verbose operation. When displaying a number in verbose mode, it will be prefixed with $ if it's in hex, or no prefix for decimal.

BASIC DIALECTS

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 -bt, -bxl, or -bxe. Also, BASIC XE is a superset of BASIC XL (provided BASIC XL's disk-based toolkit extended commands are not used), so you can usually use -bxe on a BASIC XL program.

BASIC/A+ uses incompatible tokens, so its programs can't be viewed as any of the others. Trying to do this results in a very funny-looking listing, with commands like POSITION with no arguments (or with a string argument, or POSITION #6;"string"; it so happens A+ uses the same token number for POSITION that the other BASICs use for ?). The same thing would happen if you booted BASIC/A+ on an Atari and tried to LOAD an Atari BASIC program. I can't help but think this is a major reason BASIC/A+ didn't sell that well (fortunately, OSS realized their mistake and fixed it in BASIC XL).

If you see lots of "bad token XX" messages, or if the code just doesn't make any sense, you're using the wrong BASIC option. whichbas(1) can usually detect the BASIC a program was written in, but if the results are ambiguous, listbas will assume Turbo BASIC XL. If this is wrong, use -bxl or -bxe to force the issue.

COLORS

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 NOTES for a list of tested terminal emulators.

You can customize the colors by using the -c colors option, either on the command line, or in the LISTBAS_OPTS environment variable. colors is a string of exactly 8 characters, each of which must be the digits 0 through 7 to specify a color, or the letter n to specify no color.

The colors are the standard ANSI ones, plus n:

0   Black.

1   Red.

2   Green.

3   Yellow (or brown/orange, on some terminals).

4   Blue.

5   Purple (aka violet).

6   Cyan.

7   White.

n   No custom color. Output will be in the terminal's default foreground color.

    The order they're used in the colors argument is:

1   BASIC keywords. Default: 3 (yellow).

2   Operators, including quotes around strings and commas between DATA items. Default: 2 (green).

3   Functions. Default: 5 (purple).

4   Constants (numeric or string). Default: 1 (red).

5   Line numbers (at the start of a line only; GOTO and GOSUB line numbers are constants). Default: 6 (cyan).

6   REM text. Default: 4 (blue).

7   DATA items (but not the commas between them). Default: 6 (cyan).

8   Variable names. Default: n (uncolorized).

    So, the default color scheme is equivalent to: -c 3251646n

    Black and white are not used by default because presumably, one or the other is the background color of the terminal.

NOTES

  Indentation

The indentation isn't all that well-tested yet, but so far it seems work correctly. The -t option is the equivalent of *L- for Turbo, or SET 12,0 for BXL/BXE. The different BASICs have different indentation rules; try viewing the same Atari BASIC program with -bt, -bxl, and -bxe to compare them.

listbas -t is also (as far as I know) the only way to LIST a BASIC/A+ program without indentation, since BASIC/A+ itself doesn't have a way to disable it.

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. listbas doesn't emulate this behaviour (shouldn't be a problem, it's a pathological case).

BASIC XL actually does indentation within a line. If you write:

10 IF A:IF B:IF C:REM

...BXL lists it as:

10   If A:  If B:  If C:Rem

listbas only indents at the start of a line, so this behaviour is not emulated.

One thing listbas gets right: the LIST command in Turbo, A+, BXL, and BXE always starts out with 0 indent spaces, if you're only listing part of a program. BXE example:

10 While 1
20   If Peek(764)<>255
30     ? "SOMEONE PRESSED A KEY":Poke 764,255
40   Endif
50 Endwhile

...but if you give a LIST 30 in BXE, you'll get line 30 without any indentation. listbas does this, too, if you use the -r option.

  Protected Programs

listbas 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 unprotbas(1) to remove the protection.

  Comparison to chkbas

listbas is similar to Jindroush's chkbas(1). The main differences are:

•   listbas prints ATASCII graphics as Unicode equivalents, so the listing looks very similar to how it would appear on the Atari.

•   listbas does color syntax highlighting.

•   listbas supports OSS BASIC/A+ in addition to Turbo and BXL/BXE.

•   listbas indents BASIC/A+, Turbo, BXL, and BXE code, just like the actual BASICs do.

•   listbas doesn't show information about the variables. Use vxrefbas(1) for that.

•   listbas will not write ATASCII data to your terminal. By default, it converts ATASCII characters into Unicode/UTF-8 characters that won't confuse the terminal. When outputting raw ATASCII (-a option), it refuses to run if standard output is a terminal.

•   listbas only lists line 32768 (the immediate mode command) if specifically asked to do so.

•   listbas doesn't print a banner on startup.

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

  Terminal Support

The color and inverse/bold/underline support assumes your terminal supports ANSI/VT220 escape codes... but it does not use curses(3X) or terminfo(5), or even look at TERM 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.

listbas has been tested and is known to work in at least these terminals: rxvt-unicode, aka urxvt. This is the terminal the author uses.

xterm - tested frequently. Requires the XTerm.locale resource to be set to UTF-8 (e.g. in ~/.Xdefaults), or the -lc and/or -en UTF-8 command line options.

Linux console - works fine, but good luck finding a font with all the Unicode graphics characters. Better use -m.

kitty - very fancy terminal emulator that supports both X11 and Wayland. listbas was only tested on X11.

xfce4-terminal - version 0.8.10, with XFCE4 4.16.0.

konsole - the KDE terminal, from KDE 5.90.

gnome-terminal - version 3.43.90.

st - minimal terminal from suckless.org, version 0.9.2.

mlterm - version 3.9.3.

kmscon - version 9.0.0. https://github.com/Aetf/kmscon

fbterm - version 1.8. https://github.com/sfzhi/fbterm

Also, rxvt and aterm don't support Unicode, but they will otherwise work (display color and inverse) with the -m or -d options to listbas.

  HTML Output

I thought about adding an HTML output option, but there's no need: if you want a colorful listing of an Atari BASIC program, install aha(1) from https://github.com/theZiz/aha (or your distro's package repo) and run something like:

listbas PROGRAM.BAS | aha > program.html

ENVIRONMENT

LISTBAS_OPTS
    If this environment variable is set, listbas parses its value as though the contents were placed on the command line as options, preceding any actual option. Example:

    export LISTBAS_OPTS="-c123456 -d"

    If you place the above line in your shell's startup script, listbas will use your custom color scheme, and will default to the "dots" output mode. If you then run listbas the -c and/or -x, -m options, the options on the command line will override the environment.

EXIT STATUS

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

COPYRIGHT

WTFPL. See http://www.wtfpl.net/txt/copying/ for details.

AUTHOR

B.  Watson <urchlay@slackware.uk>; Urchlay on irc.libera.chat ##atari.

SEE ALSO

a8cat(1), a8eol(1), a8xd(1), atr2xfd(1), atrsize(1), axe(1), bas2aplus(1), blob2c(1), blob2xex(1), cart2xex(1), cxrefbas(1), dasm2atasm(1), diffbas(1), dumpbas(1), f2toxex(1), fenders(1), listbas(1), listamsb(1), protbas(1), renumbas(1), rom2cart(1), unmac65(1), unprotbas(1), vxrefbas(1), whichbas(1), xex1to2(1), xexamine(1), xexcat(1), xexsplit(1), xfd2atr(1), xex(5), atascii(7), fauxtari(7).

Any good Atari 8-bit book: De Re Atari, The Atari BASIC Reference Manual, the OS Users' Guide, Mapping the Atari, etc.