AppleII::Disk 0.08

AppleII::Disk is a Perl module for block-level access to Apple II disk image files.

SYNOPSIS

use AppleII::Disk;
my $disk = AppleII::Disk->new(image.dsk);
my $data = $disk->read_block(1); # Read block 1
$disk->write_block(1, $data); # And write it back :-)

AppleII::Disk provides block-level access to the Apple II disk image files used by most Apple II emulators. (For information about Apple II emulators, try the Apple II Emulator Page at http://www.ecnet.net/users/mumbv/pages/apple2.shtml.) For a higher-level interface, use the AppleII::ProDOS module.
AppleII::Disk provides the following methods:

$disk = AppleII::Disk->new($filename, [$mode])

Constructs a new AppleII::Disk object. $filename is the name of the image file. The optional $mode is a string specifying how to open the image. It can consist of the following characters (case sensitive):

r Allow reads (this is actually ignored; you can always read)
w Allow writes
d Disk image is in DOS 3.3 order
p Disk image is in ProDOS order

If you dont specify d or p, then the format is guessed from the filename. .PO and .HDV files are ProDOS order, and anything else is assumed to be DOS 3.3 order.

If you specify w to allow writes, then the image file is created if it doesnt already exist.

$size = $disk->blocks([$newsize])

Gets or sets the size of the disk in blocks. $newsize is the new size of the disk in blocks. If $newsize is omitted, then the size is not changed. Returns the size of the disk image in blocks.

This refers to the logical size of the disk image. Blocks outside the physical size of the disk image read as all zeros. Writing to such a block will expand the image file.

When you create a new image file, you must use blocks to set its size before writing to it.

$contents = $disk->read_block($block)

Reads one block from the disk image. $block is the block number to read.
$contents = $disk->read_blocks(@blocks)

Reads a sequence of blocks from the disk image. @blocks is a reference to an array of block numbers. As a special case, block 0 cannot be read by this method. Instead, it returns a block full of 0 bytes. This is how sparse files are implemented. If you want to read the actual contents of block 0, you must call $disk->read_block(0) directly.

$contents = $disk->read_sector($track, $sector)

Reads one sector from the disk image. $track is the track number, and $sector is the DOS 3.3 logical sector number. This is currently implemented only for DOS 3.3 order images.

$disk->fully_allocate()

Expands the the physical size of the disk image file to match the logical size of the disk image. It will be expanded as a sparse file if the filesystem containing the image file supports sparse files.

$disk->write_block($block, $contents, [$pad])

Writes one block to the disk image. $block is the block number to write. $contents is the data to write. The optional $pad is a character to pad the block with (out to 512 bytes). If $pad is omitted or null, then $contents must be exactly 512 bytes.

$disk->write_blocks(@blocks, $contents, [$pad])

Writes a sequence of blocks to the disk image. @blocks is a reference to an array of block numbers to write. $contents is the data to write. It is broken up into 512 byte chunks and written to the blocks. The optional $pad is a character to pad the data with (out to a multiple of 512 bytes). If $pad is omitted or null, then $contents must be exactly 512 bytes times the number of blocks.

As a special case, block 0 cannot be written by this method. Instead, that block of $contents is just skipped. This is how sparse files are implemented. If you want to write the contents of block 0, you must call $disk->write_block directly.

$disk->write_sector($track, $sector, $contents, [$pad])

Writes one sector to the disk image. $track is the track number, and $sector is the DOS 3.3 logical sector number. $contents is the data to write. The optional $pad is a character to pad the sector with (out to 256 bytes). If $pad is omitted or null, then $contents must be exactly 256 bytes. This is currently implemented only for DOS 3.3 order images.

$padded = AppleII::Disk::pad_block($data, [$pad, [$length]])

Pads $data out to $length bytes with $pad. Returns the padded string; the original is not altered. Dies if $data is longer than $length. The default $pad is " ", and the default $length is 512 bytes.

If $pad is the null string (not undef), just checks to make sure that $data is exactly $length bytes and returns the original string. Dies if $data is not exactly $length bytes.

pad_block is a subroutine, not a method, and is not exported. You probably dont need to call it directly anyway, because the write_XXX methods will call it for you.