Apple ][ Kit (a2kit)

Command line interface and library for manipulating Apple ][ language files and disk images.

Here is an example using the CLI to create a disk image that is then loaded into microM8 and booted. This example assumes the working directory contains ProDOS file images and source code for the startup program. In practice one might choose to script such operations.

Documentation

Command Line Interface

Library Crate

lib.rs:

a2kit main library

This library manipulates disk images that can be used with Apple II emulators. Manipulations can be done at a level as low as track bits, or as high as language files.

Architecture

Disk image operations are built around two trait objects found in the disk_base module:

• DiskImage encodes/decodes disk tracks, does not try to interpret a file system
• DiskFS imposes a file system on the already decoded track data
• FileImage provides a representation of a file that can be restored to a disk image

Internally, the DiskFS object contains its own track data, but always in the DSK image format, with the sector order chosen to match the file system. Because the DSK format is at the heart of all file operations, the beginning and end of many workflows involves transforming between DSK and some other image format (including ordering variants of DSK)

Language services are built on tree-sitter parsers. Generalized syntax checking is in walker. Specific language services are in modules named after the language, at present:

• applesoft handles (de)tokenization of Applesoft BASIC
• integer handles (de)tokenization of Integer BASIC
• merlin handles encodings for Merlin assembly source files
• Pascal source files are handled through the file system module

File Systems

In order to manipulate files, a2kit must understand the file system it finds on the disk image. As of this writing a2kit supports

• DOS 3.3
• ProDOS
• Pascal File System

Disk Encodings

The disk hardware used with the Apple II line of computers (and perhaps others) could not handle an arbitrary sequence of bits, i.e., the bit sequence had to follow certain rules. Encoding schemes were developed to represent arbitrary bits using the hardware's allowed bit sequences. There are disks that will not work on an emulator unless the detailed bit stream of the original is carefully reproduced. As a result, disk image formats were invented that emulate a disk down to this level of detail. As of this writing, the bit-level formats supported by a2kit are WOZ versions 1 and 2. High level operations with WOZ images are supported to the extent that the track format and file system are supported.