======= listbas ======= -------------------------------------------------------- List the source of a tokenized Atari 8-bit BASIC program -------------------------------------------------------- .. include:: manhdr.rst SYNOPSIS ======== listbas [**-a** | **-d** | **-m** | **-x** | **-U**] [**-b**] [**-u**] [**-i**] [**-l**] [**-n** | **-C**] [**-v**] [**-c** *colors*] **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. OPTIONS ======= 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; **listbas** will not write ATASCII to the terminal. **-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 options ------------- **-i** Include the immediate mode command (line 32768) in the output. **-l** Do not print line numbers at the start of each line. **GOTO**, **GOSUB**, **TRAP**, and **THEN** target line numbers are still printed. **-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. .. include:: genopts.rst 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 ===== **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. -- **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** only supports Atari BASIC, not Turbo BASIC or BASIC XL/XE. This is a bug, not a feature... - **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. -- 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**. -- 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). .. include:: manftr.rst