Crate a2kit

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
• A2Disk 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)

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

applesoft

Applesoft parsing library

disk525

Low level treatment of 5.25 inch floppy disks

disk_base

Base Layer for Disk Image and File Operations

dos33

DOS 3.3 disk image library

img_do

Support for DOS ordered disk images (DO,DSK)

img_po

Support for ProDOS ordered disk images (PO,DSK)

img_woz

Common components for WOZ1 or WOZ2 disk images

img_woz1

Support for WOZ v1 disk images

img_woz2

Support for WOZ v2 disk images

integer

Integer BASIC parsing library

prodos

ProDOS disk image library

walker

Functions

create_disk_from_bytestreamDeprecated

Given a bytestream try to identify the type of disk image and create a disk object. N.b. this discards metadata and track layout details, only the high level data remains. This will also panic if the data cannot be interpreted.

create_disk_from_fileDeprecated

Calls 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_stdinDeprecated

Calls create_disk_from_bytestream getting the bytes from stdin

create_img_and_disk_from_bytestream

Given a bytestream return a tuple with (DiskImage, A2Disk), or None if the bytestream cannot be interpreted. DiskImage is the disk structure and data, A2Disk is a higher level representation including a file system (e.g. DOS or ProDOS). Manipulation of files that may be on the image is done via the A2Disk object. The changes are only permanent if they are written back to the DiskImage, and explicitly saved to local storage.

create_img_and_disk_from_file

Calls create_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

Given a bytestream return a disk image without any file system. N.b. the ordering cannot always be determined without the file system.

create_img_from_file

Calls create_img_from_bytestream getting the bytes from a file. The pathname must already be in the right format for the file system.

display_chunk

Display binary to stdout in columns of hex, +ascii, and -ascii

display_track

Display track bytes to stdout in columns of hex, track mnemonics

update_img_and_save

Use the sectors on an 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.