diff options
Diffstat (limited to 'listamsb.rst')
-rw-r--r-- | listamsb.rst | 313 |
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 |