======= listbas ======= -------------------------------------------------------- List the source of a tokenized Atari 8-bit BASIC program -------------------------------------------------------- .. include:: manhdr.rst SYNOPSIS ======== listbas [**-v**] [**-i**] [**-b**] [**-d** ] [**-a** | **-m** ] **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. **-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. The color scheme is adjustable via the **-c** option; see **Customization**, below. To avoid having to give your custom colors on the command line every time, see **ENVIRONMENT**, below. The default color scheme is: **yellow** Commands. Also "command operators" such as the **GOTO** in **ON/GOTO** and the **STEP** in a **FOR** command. These are really operators as far as BASIC is concerned, but it makes more sense to colorize them as commands. **green** Operators (except functions and "command operators"), quotes around strings, and commas between **DATA** elements. **purple** Functions. **red** Numbers (except line numbers at the start of a line) and string constants (but not the quotes around the string). **cyan** Line numbers at the start of a line and **DATA** items. **blue** Comments (**REM** text). **uncolorized** Variable names. Black and white are not used by default because presumably, one or the other is the background color of the terminal. Customization ------------- 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** Commands. **2** Operators. **3** Functions. **4** Constants. **5** Line numbers (at the start of a line only; **GOTO** and **GOSUB** line numbers are constants). **6** **DATA** items (but not the commas between them). **7** **REM** text. **8** Variable names. So, the default color scheme is equivalent to: **-c** *3251646n* 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. - **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. 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