view release on metacpan or  search on metacpan

lib/AppleII/Disk.pm  view on Meta::CPAN

sub write_block
{
    my ($self, $block, $data, $pad) = @_;
    croak("Disk image is read/only") unless $self->{writable};
    my ($track, $sector1, $sector2) = block2sector($block);

    $data = AppleII::Disk::pad_block($data, $pad || '');

    $self->write_sector($track, $sector1, substr($data,0,0x100));
    $self->write_sector($track, $sector2, substr($data,0x100,0x100));
} # end AppleII::Disk::DOS33::write_block

#=====================================================================
# Package Return Value:

1;

__END__

=head1 NAME

AppleII::Disk - Block-level access to Apple II disk image files

=head1 VERSION

This document describes version 0.201 of
AppleII::Disk, released September 12, 2015
as part of AppleII-LibA2 version 0.201.

=head1 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 :-)

=head1 DESCRIPTION

C<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
L<http://www.ecnet.net/users/mumbv/pages/apple2.shtml>.)  For a
higher-level interface, use the L<AppleII::ProDOS> module.

C<AppleII::Disk> provides the following methods:

=over 4

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

Constructs a new C<AppleII::Disk> object.  C<$filename> is the name of
the image file.  The optional C<$mode> is a string specifying how to
open the image.  It can consist of the following characters (I<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 don't 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 doesn't already exist.

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

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

This refers to the I<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 C<blocks> to set its
size before writing to it.

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

Reads one block from the disk image.  C<$block> is the block number to
read.

=item $contents = $disk->read_blocks(\@blocks)

Reads a sequence of blocks from the disk image.  C<\@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.

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

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

=item $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.

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

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

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

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