========
listamsb
========

------------------------------------------------------------
List the source of a tokenized Atari Microsoft BASIC program
------------------------------------------------------------

.. include:: manhdr.rst

SYNOPSIS
========

listamsb [**-a**\] [**-v**\] [**-h**\] [**-i**\] [**-u**\] [**-t**\] [**-m**\] [**-s**\] [**input-file**\]

DESCRIPTION
===========

**listamsb** acts like the *LIST* command in Atari Microsoft BASIC. It reads a
tokenized (SAVEd) AMSB program and prints the code in human-readable
format.

By default, output is piped to **a8cat**\(1), which converts the
ATASCII output to something that's human-readable on modern terminals.
This means **a8cat** must be available somewhere in **$PATH**\.

**listamsb** supports both versions of Atari Microsoft BASIC: the
disk-based version 1 and the cartridge-based version 2. The language
is the same for both versions, so there's no need to specify it.

**input-file** must be a tokenized AMSB program. If no **input-file** is given,
input is read from stdin.

Output is to stdout. Use shell redirection to save the output to a file.

OPTIONS
=======

**-a**
  Output raw ATASCII. This option must be used with a pipe or redirection, as
  **listamsb** will not write ATASCII to a terminal. **a8cat** is not used,
  with this option.

**-c**
  Check only. No output on stdout. Diagnostics are still printed on stderr,
  and the exit status is unchanged.

**-v**
  Verbose output, on stderr.

**-h**
  Print built-in help and exit.

**-i**\, **-u**\, **-t**\, **-m**\, **-s**
  These options are passed to **a8cat**. See its man page for details. If
  the **-a** or **-c** option is used, these options have no effect.

DIAGNOSTICS
===========

LIMITATIONS
===========

Unlike **listbas**, there's no color syntax highlighting. Probably there
never will be.

It's hard to reliably detect AMSB files. If you feed **listamsb** an
Atari BASIC file, you'll get gibberish output.

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