README

        : It is the apocalypse, and what your bunker got for computers :
        : is a bunch of C64s.  Unfortunately,  the requisition for any :
        : software never went through...                               :


     BASASM is a simple 6502 assembler made entirely in and for use with
     Commodore BASIC V2 as implemented in the C64 home computer.

     Included is a set of utilities that make it viable to work on machine
     language programs of moderate size. No additional software, cartridges,
     or other accessories are required. A floppy disk drive is recommended
     to save programs.

     The assembler consists of the base program, BASASM, and the table
     of machine OPCODES in a separate file. It must be combined with the
     user program in the form of DATA statements before RUNning. This can
     be accomplished with the supplied LINEUTILs. An executable MANUAL
     provides more instructions.

     Beside its immediate purpose, LINEUTIL serves as a moderate-size
     example program, comprising a set of base subroutines and multiple
     top-level entry points for individual utilities.

     One word of caution to temper expectations: The assembler is quite
     slow, running entirely on the "unhurried" Commodore BASIC interpreter.
     Processing the roughly 1000 lines of LINEUTIL takes several minutes,
     so be prepared to take some breaks. :)

     Speed woes aside, for a program of less than 300 lines of code, BASASM
     is perhaps surprisingly feature rich:

        -  Mnemonic instructions, aware of operand sizes.
        -  Decimal and hexadecimal notation.
        -  Symbolic labels, absolute and relative addressing.
        -  Locally-scoped labels.
        -  Listing label definitions for "export" to separate programs.
        -  User-defined symbolic constants.
        -  Single-pass operation with forward references.
        -  Range checks for operands.
        -  High-byte and successor (+1) operators.
        -  Directives to output arbitrary bytes, words, strings.
        -  Directives to alter and limit the output position.
        -  String representation for bit pattern output (...XX...).
        -  Adjusting the BASIC heap size for output below 40K.

     About 70 more lines implement subprograms to save PRG files, issue
     drive commands, dump memory, and a few others.

     This repository contains listings of the relevant PRG files in
     UTF-8.  The transfer is facilitated by two C programs that can
     unpack a D64 disk image (und64) and output BASIC PRG files in plain
     text (listprg).  Note: Commit time stamps are not representative
     beyond obviously providing upper bounds.

     Files are naturally formatted to fit the limited 40x25 character
     screen of the C64 and its line-wise editing workflow, so some
     adjustment from modern "sensibilities" might be necessary when
     reading.

     Included here are a few programs that were produced "along the way"
     during development:

           HEXDUMP      dump memory (stand-alone version)
           HDFILE       hexdump raw contents of a file
           SAVEMEM      save memory to PRG file (stand-alone version)
           TEST.B       nonsense program, test input for BASASM
           PRINTNAT.B   first assembly program: print a number
           LINECNT.B    first line utility: count BASIC program lines
           TV           text viewer, used in MANUAL
           MKALLTOK     write a PRG file that contains every possible BASIC
                        token (used for listprg)
           DISKCOPY     duplicate a disk block by block (incredibly slow)
           MKOPCODES    generate OPCODES file
           OPCODES.B    source file to be combined with MKOPCODES
           CRUNCH.B     remove REMs and spaces from current BASIC program

     Notes on encoding: Several (printable) characters in the Commodore
     character set differ from ASCII - arrows, for instance, in place of
     caret and underscore.  Such characters have been converted to Unicode
     to appear visually correct.  Lower case characters are not normally
     available at all, their codes being reused for graphical symbols.
     The code of MANUAL and TV contains strings with embedded control
     characters.  These appear as "{XX}" in the listings, which is
     unambiguous because curly braces are not part of the character set.