diff options
Diffstat (limited to 'listbas.rst')
| -rw-r--r-- | listbas.rst | 405 |
1 files changed, 405 insertions, 0 deletions
diff --git a/listbas.rst b/listbas.rst new file mode 100644 index 0000000..1aba12a --- /dev/null +++ b/listbas.rst @@ -0,0 +1,405 @@ +======= +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*] [**-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. + +.. include:: genopts.rst + +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). + +.. include:: manftr.rst |