path: root/listbas.rst

=======
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.

**listbas** supports several BASIC dialects used on the Atari. By
default, the BASIC dialect is autodetected by running **whichbas**\(1)
as an external process.

OPTIONS
=======

BASIC options
-------------

**-b**
  Set the BASIC dialect the program was written in. 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.

  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.

**-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.

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 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

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
=====
So far, **listbas** doesn't support the indentation that BASIC A+/XL/XE
do by default. It acts like **SET 12,0** has been executed... though
BASIC A+ doesn't actually *have* this option, and the indentation can't
be turned off in A+ at all.

--

**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** supports OSS BASIC/A+ in addition to Turbo and BXL/BXE.

- **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).

--

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