Expand description
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 systemA2Disk
imposes a file system on the already decoded track data
Internally, the A2Disk
object contains its own track data,
but always in the DSK
image format, with the sector order chosen to match the file system.
The DSK
image format uses already-decoded track data from the get-go, so it is ideal for
running a 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 BASICinteger
handles (de)tokenization of Integer BASICmerlin
handles encodings for Merlin assembly source files
File Systems
In order to manipulate files, a2kit
must understand the file system it finds on the disk image.
As of this writing standard DOS 3.3 and ProDOS are supported.
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.
Modules
Functions
create_disk_from_bytestream
getting the bytes from a file.
The pathname must already be in the right format for the file system.create_disk_from_bytestream
getting the bytes from stdincreate_img_and_disk_from_bytestream
getting the bytes from a file.
The pathname must already be in the right format for the file system.create_img_from_bytestream
getting the bytes from a file.
The pathname must already be in the right format for the file system.A2Disk
to update the sectors on a DiskImage
and save the image file
This will almost always be used if we are making permanent changes to a file system.