aboutsummaryrefslogtreecommitdiff
path: root/listbas.rst
diff options
context:
space:
mode:
Diffstat (limited to 'listbas.rst')
-rw-r--r--listbas.rst405
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