======= 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"). **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, comments (**REM** text) and **DATA** elements. **uncolorized** Variable names. Quotes around strings and commas between **DATA** elements are never colorized, so they'll appear in the default foreground color (usually white if the terminal has a black background, or black if the background is white). Note that nothing is blue in the default color scheme. This is because it's difficult to read on many terminals. Also, black and white are not used 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 6 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, 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** Variable names. So, the default color scheme is equivalent to: **-c** *32516n* 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