aboutsummaryrefslogtreecommitdiff
path: root/listamsb.rst
diff options
context:
space:
mode:
Diffstat (limited to 'listamsb.rst')
-rw-r--r--listamsb.rst313
1 files changed, 313 insertions, 0 deletions
diff --git a/listamsb.rst b/listamsb.rst
new file mode 100644
index 0000000..5bb5640
--- /dev/null
+++ b/listamsb.rst
@@ -0,0 +1,313 @@
+========
+listamsb
+========
+
+------------------------------------------------------------
+List the source of a tokenized Atari Microsoft BASIC program
+------------------------------------------------------------
+
+.. include:: manhdr.rst
+
+SYNOPSIS
+========
+
+listamsb [**-U**] | [**-C** [**-k**]] | [**-D**] | [[**-L**] [**-a**] [**-c**] [**-v**] [**-h**] [**-i**] [**-u**] [**-t**] [**-m**] [**-M**] [**-n**] [**-s**] [**-r** *line-range*] ...] [**input-file**] [**output-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.
+
+**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**.
+
+Programs created with *SAVE "filename" LOCK* are autodetected,
+and will be listed normally. It's also possible to convert a LOCKed
+program to an unencrypted one, with the **-U** option.
+
+Programs can be "crunched" and "decrunched" with the **-C** and **-D**
+options.
+
+If no **output-file** is given, output is to **stdout**. When output
+is to a file, the file will be overwritten without prompting if it
+already exists.
+
+By default, output is modern UTF-8 equivalents of the ATASCII
+character set, with ANSI control sequences for inverse video and
+color. See the **-M**, **-a**, **-i**, **-u**, **-t**, **-m**, **-s**
+options to change the output style.
+
+When listing in color (when the **-M** option is not used),
+**listamsb**\'s output is piped through **colorize-amsb**, which must
+be available in your **PATH**\.
+
+**listamsb** will not write binary data (ATASCII or tokenized BASIC)
+directly to a terminal, under any circumstances.
+
+OPTIONS
+=======
+
+Operation Modes
+---------------
+
+**-L**
+ LIST program. This is the default, so there's no need to give this option
+ normally. See next section for options that control the listing.
+
+**-C**
+ "Crunch" program: remove comments and spaces that occur outside of a
+ string. The resulting program is tokenized, and is usually 5 to 10
+ percent smaller. It should RUN correctly, but will be difficult to
+ edit in AMSB because its parser requires the spaces.
+
+ The crunched program will always be unLOCKed.
+
+ If any comment-only lines are the target of GOTO or GOSUB, the
+ program won't RUN correctly because all comment-only lines are
+ removed. If this happens, you can use the **-k** option (see below).
+
+ This option must be used with an **output-file**, since seeking is done.
+ None of the other options have any effect with **-C**.
+
+**-D**
+ "Decrunch" a crunched program. Puts spaces where they're required for
+ AMSB's parser. The resulting program is tokenized, and will be
+ editable in AMSB. Of course, any comments that were removed during
+ crunching will not magically be restored (they're gone).
+
+ The decrunched program will always be unLOCKed.
+
+ This option must be used with an **output-file**, since seeking is done.
+ None of the other options have any effect with **-D**.
+
+**-U**
+ UnLOCK or LOCK the the program. Locked programs are created with
+ *SAVE "filename" LOCK*. The "encryption" is a reciprocal cipher: locking and
+ unlocking are the same operation (similar to ROT13). The output will
+ be the locked or unlocked tokenized program (rather than a listing).
+
+ This option must be used with an **output-file**, a pipe, or
+ redirection: **listamsb** will not write tokenized BASIC to a
+ terminal. None of the other options have any effect with **-U**.
+
+Options for **-L** (list) Mode
+------------------------------
+
+None of these options have any effect when used with **-C**, **-D**,
+or **-U**.
+
+**-a**
+ Output raw ATASCII. This option must be used with an
+ **output-file**, a pipe, or redirection: **listamsb** will not write
+ ATASCII to a terminal. **colorize-amsb** 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. It's an error to give an **output-file** with
+ this option.
+
+**-i**
+ Input uses Atari XL/XE International Character Set encoding, rather than
+ ATASCII graphics.
+
+**-u**
+ Use underlining for inverse video (see **a8cat**\(1) for more detail).
+
+**-t**
+ Text mode (see **a8cat**\(1) for more detail).
+
+**-m**
+ Magazine listing mode (see **a8cat**\(1) for more detail).
+
+**-s**
+ Strip bit 7 (inverse video bit; see **a8cat**\(1) for more detail).
+
+**-M**
+ Monochrome listing: disable color syntax highlighting, meaning **colorize-amsb**
+ is not used.
+
+**-r** *line-range*
+ Show only part of the listing. *line-range* can be a single line, or
+ a comma- or hyphen-separated pair of starting and ending line numbers (e.g. **100,200**, or
+ **1000-2000**).
+
+ 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,** or **-r-** is equivalent to not using the **-r** option at all.
+
+**-n**
+ No empty line. By default, **listamsb** prints an empty line at the
+ start of the output, to match AMSB's LIST command.
+
+Options for **-C** (crunch) Mode
+--------------------------------
+
+**-k**
+ Keep comment-only lines. Normally these are removed. If the program
+ gives UNDEF'D LINE ERROR, it means the target line was a comment-only
+ line that got removed. With **-k**, these lines will be kept, although
+ the actual comments won't (*10 REM HELLO* will become *10 REM*).
+
+Utility Options
+---------------
+
+**-v**
+ Verbose output, on **stderr**. May be given twice for extra verbosity,
+ which shows each line number, its offset, length, and end-of-line pointer.
+ Can be used with any of the mode options (**-C**, **-D**, **-L**, **-U**).
+
+**-h**\, **--help**
+ Print built-in help and exit.
+
+**--version**
+ Print version number and exit.
+
+DIAGNOSTICS
+===========
+
+All error and warning messages are written to the standard error output.
+
+Fatal errors
+------------
+
+These are errors in the program header at the start of the file. They
+generally mean the input isn't actually an tokenized Atari Microsoft
+BASIC file.
+
+- not an AMSB file: first byte not $00 or $01
+
+ Pretty self-explanatory: if the file doesn't begin with a *$00* or
+ *$01* byte, it's not a tokenized AMSB file.
+
+- not an AMSB file: too big (*N* bytes), won't fit in Atari memory
+
+ The file can't be a tokenized AMSB file because there was no way
+ for it to be created. It must be some other kind of file that begins
+ with a *$00* byte.
+
+- not an AMSB file: program size too small (*N*). Atari BASIC file?
+
+ The program header claims the file is 0, 1, 3, or 4 bytes long. This
+ is impossible, so this isn't an AMSB file. A lot of Atari BASIC
+ programs begin with three *$00* bytes, so that might be what this is.
+
+- program length is 2, no code in file (SAVE after NEW)
+
+ Probably, someone did a SAVE when there was no program in memory. It
+ could also mean this isn't an AMSB file at all.
+
+Warnings
+--------
+
+These are non-fatal: **listamsb** logs the warning to stderr, then
+continues processing.
+
+- unexpected EOF, file truncated?
+
+ A tokenized AMSB file always ends with three null bytes (*$00*\).
+ This file doesn't. Probably the rest of the file is missing.
+
+- line *L*: EOL address *A* too (low|high)
+
+ Each line begins with the address of the next line. If the address
+ is below *$0700*, it's below the minimum value of *MEMLO*, which
+ is impossible. If it's above *$bc1f*, it would be in the display
+ list, screen memory, or OS ROM (also impossible). File is
+ corrupt, or not an AMSB file.
+
+- line *L*: EOL address *A* <= previous *B*
+
+ Corrupt file, or not an AMSB file.
+
+- line *L* is suspiciously long
+
+ The line is >128 bytes long, but less than 256. AMSB can execute
+ lines of this length, but it's impossible to actually enter them
+ in the editor, because a logical line can't be longer than 3
+ screen lines. Possibly corrupted file.
+
+- line *L* is impossibly long
+
+ The line is >= 256 bytes long. AMSB will crash, if you try to
+ LOAD the file. Corrupted file.
+
+- line *L* EOL address doesn't match actual line length *N*
+
+ Corrupt file, or not an AMSB file.
+
+- line number out of order
+
+ Corrupt file, or not an AMSB file.
+
+- line number out range
+
+ The program contains a line number that's greater than *63999*. How
+ did that happen?
+
+- line *L* has character *C* outside of a string. maybe Atari BASIC?
+
+ This happens when ATASCII codes 0 to 31 (*$1f*\) appear in the program.
+ AMSB can create files like this, but at runtime, it's a syntax error.
+ More likely, it means this is an Atari BASIC file.
+
+- program size doesn't match size in header
+
+ Might mean this isn't an AMSB file. If you're sure it is, it might
+ be truncated, or part of the file might have been overwritten with
+ *$00* bytes. It could also mean the length in the header has somehow
+ gotten corrupted.
+
+- trailing garbage at end of file
+
+ Might mean this isn't an AMSB file. If you're sure it is, garbage
+ data has somehow gotten appended to the file, after the three *$00*
+ bytes that end the program. Maybe it was downloaded with a crappy
+ version of XMODEM that pads the last block. The good news is,
+ AMSB will just ignore the garbage when you LOAD the file, so it
+ won't hurt anything.
+
+- file has *N* unknown tokens
+
+ Either the file is corrupt, or this is a file from some *other* variant
+ of Microsoft BASIC (e.g. Commodore, AppleSoft, GW-BASIC, TRS-80). If
+ you see this warning, you'll also see *N* <unknown token *XX*>
+ messages in the actual listing.
+
+ENVIRONMENT
+===========
+
+**COLORIZE_AMSB**
+ Path to the **colorize-amsb** executable. Can be the absolute path
+ or just the executable (searched for in **PATH**). If not set,
+ defaults to *colorize-amsb*.
+
+
+LIMITATIONS
+===========
+
+**listamsb** may behave strangely when fed something other than a
+tokenized AMSB program, at least if the first byte in the file
+is **$00** or **$01**. Unfortunately, tokenized Atari BASIC (and
+variants like Turbo and BASIC XL) begin with **$00**. Usually
+you'll get this error::
+
+ not an AMSB file: program size too small (0). Atari BASIC file?
+
+\.\.\.but occasionally you may get a bunch of warnings and gibberish
+output instead.
+
+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 had errors or warnings (see
+**DIAGNOSTICS**).
+
+.. include:: manftr.rst