The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
D64-Disk-Layout-Sector-0.02
River stage one • 1 direct dependent • 1 total dependent
++
/ D64::Disk::Layout::Sector

NAME

D64::Disk::Layout::Sector - An abstraction layer over physical sector data of various Commodore disk image formats

SYNOPSIS

  use D64::Disk::Layout::Sector;

  # Create a new disk sector object instance:
  my $object = D64::Disk::Layout::Sector->new(data => $data, track => $track, sector => $sector);
  my $object = D64::Disk::Layout::Sector->new(data => \@data, track => $track, sector => $sector);

  # Fetch sector data as a scalar of 256 bytes:
  my $data = $object->data();
  # Fetch sector data as an array of 256 bytes:
  my @data = $object->data();

  # Update sector providing 256 bytes of scalar data:
  $object->data($data);
  # Update sector given array with 256 bytes of data:
  $object->data(@data);
  $object->data(\@data);

  # Fetch the actual file contents from sector data as a scalar of allocated number of bytes:
  my $file_data = $object->file_data();
  # Fetch the actual file contents from sector data as an array of allocated number of bytes:
  my @file_data = $object->file_data();

  # Update the actual file contents providing number of scalar data bytes to allocate:
  $object->file_data($file_data);
  # Update the actual file contents given array with number of bytes of data to allocate:
  $object->file_data(@file_data);
  $object->file_data(\@file_data);

  # Get/set track location of the object data in the actual disk image:
  my $track = $object->track();
  $object->track($track);

  # Get/set sector location of the object data in the actual disk image:
  my $sector = $object->sector();
  $object->sector($sector);

  # Check if first two bytes of data point to the next chunk of data in a chain:
  my $is_valid_ts_link = $object->is_valid_ts_link();

  # Get/set track and sector link values to the next chunk of data in a chain:
  my ($track, $sector) = $object->ts_link();
  $object->ts_link($track, $sector);

  # Check if first two bytes of data indicate index of the last allocated byte:
  my $is_last_in_chain = $object->is_last_in_chain();

  # Get/set index of the last allocated byte within the sector data:
  my $alloc_size = $object->alloc_size();
  $object->alloc_size($alloc_size);

  # Check if sector object is empty:
  my $is_empty = $object->empty();

  # Set/clear boolean flag marking sector object as empty:
  $object->empty($empty);

  # Wipe out an entire sector data, and mark it as empty:
  $object->clean();

  # Print out formatted disk sector data:
  $object->print();

DESCRIPTION

D64::Disk::Layout::Sector provides a helper class for D64::Disk::Layout module and defines an abstraction layer over physical sector data of various Commodore disk image formats, enabling users to access and modify disk sector data in an object oriented way without the hassle of worrying about the meaning of individual bits and bytes, describing their function in a disk image layout. The whole family of D64::Disk::Layout modules has been implemented in pure Perl as an alternative to Per Olofsson's "diskimage.c" library originally written in an ANSI C.

METHODS

new

Create an instance of a D64::Disk::Layout::Sector class as an empty disk sector:

  my $object = D64::Disk::Layout::Sector->new();

Create an instance of a D64::Disk::Layout::Sector class providing 256 bytes of data retrieved from a disk image:

  my $object = D64::Disk::Layout::Sector->new(data => $data, track => $track, sector => $sector);
  my $object = D64::Disk::Layout::Sector->new(data => \@data, track => $track, sector => $sector);

$track and $sector values are expected to be single bytes, an exception will be thrown when non-byte or non-numeric or non-scalar value is provided (please note that a default value of undef is internally translated into the value of 0x00). For more information about $data and @data validation, see the data section below.

data

Fetch sector data as a scalar of 256 bytes:

  my $data = $object->data();

Fetch sector data as an array of 256 bytes:

  my @data = $object->data();

Update sector providing 256 bytes of scalar data retrieved from a disk image:

  $object->data($data);

$data value is expected to be a scalar of 256 bytes in length, an exception will be thrown when non-scalar value or a scalar which does not have a length of 256 bytes or a scalar which contains wide non-byte character is provided.

Update sector given array with 256 bytes of data retrieved from a disk image:

  $object->data(@data);
  $object->data(\@data);

@data value is expected to be an array of 256 bytes in size, an exception will be thrown when non-array or an array with any other number of elements or an array with non-scalar byte values is provided.

file_data

Fetch the actual file contents from sector data as a scalar of allocated number of bytes:

  my $file_data = $object->file_data();

Fetch the actual file contents from sector data as an array of allocated number of bytes:

  my @file_data = $object->file_data();

Update the actual file contents providing number of scalar data bytes to allocate:

  $object->file_data($file_data, set_alloc_size => $set_alloc_size);

$file_data value is expected to be a scalar of between 0 and 254 bytes in length, an exception will be thrown when non-scalar value or a scalar which does not have a length between 0 and 254 bytes or a scalar which contains wide non-byte character is provided. $set_alloc_size input parameter defaults to 0. That means every file data assignment modifies only certain data bytes. This may or may not be a desired behaviour. If $file_data contains 254 bytes of data, it is likely that the first two bytes of sector data should still point to the next chunk of data in a chain and thus remain unchanged. If $set_alloc_size flag is set, this operation will additionally mark sector object as the last sector in chain and calculate the last allocated byte within sector data based on the number of bytes provided in $file_data value. This value will then be assigned to the alloc_size object property.

Update the actual file contents given array with number of bytes of data to allocate:

  $object->file_data(\@file_data, set_alloc_size => $set_alloc_size);

@file_data value is expected to be an array of between 0 and 254 bytes in size, an exception will be thrown when non-array or an array with any other number of elements not in between 0 and 254 or an array with non-scalar byte values is provided. $set_alloc_size input parameter defaults to 0. The same remarks apply here as the ones desribed in a paragraph above.

track

Get track location of sector data in the actual disk image:

  my $track = $object->track();

Set track location of sector data in the actual disk image:

  $object->track($track);

$track value is expected to be a single byte, an exception will be thrown when non-byte or non-numeric or non-scalar value is provided.

sector

Get sector location of sector data in the actual disk image:

  my $sector = $object->sector();

Set sector location of sector data in the actual disk image:

  $object->sector($sector);

$sector value is expected to be a single byte, an exception will be thrown when non-byte or non-numeric or non-scalar value is provided.

Check if first two bytes of data point to the next chunk of data in a chain:

  my $is_valid_ts_link = $object->is_valid_ts_link();

Get track and sector link values to the next chunk of data in a chain:

  my ($track, $sector) = $object->ts_link();

Track and sector values will be returned if first two bytes of data point to the next chunk of data in a chain, indicating this sector is in a link chain. When two first bytes of data indicate an index of the last allocated byte, an undefined value will be returned. An undefined value indicates that this is the last sector in a chain (and alloc_size can be used to fetch index of the last allocated byte within sector data).

Set track and sector link values to the next chunk of data in a chain:

  $object->ts_link($track, $sector);

Setting track/sector link includes sector in a chain and adds link to the next sector of data, at the same time allocating an entire sector for storing file data.

is_last_in_chain

Check if two first bytes of data indicate an index of the last allocated byte, meaning this is the last sector in a chain:

  my $is_last_in_chain = $object->is_last_in_chain();

Note that alloc_size method will always correctly return index of the last allocated byte within the sector data (even if first two bytes of data contain track and sector link values to the next chunk of data in a chain).

alloc_size

Get index of the last allocated byte within the sector data:

  my $alloc_size = $object->alloc_size();

Index of the last valid (loaded) file byte will be returned when this is the last sector in a chain. When 0xff value is returned, this sector may be included in a link chain (if that is the case, ts_link can be used to fetch track and sector link values to the next chunk of data in a chain).

Set index of the last allocated byte within the sector data:

  $object->alloc_size($alloc_size);

Setting index of the last allocated byte marks sector as the last one in a chain.

empty

Check if sector object is empty:

  my $is_empty = $object->empty();

Set boolean flag to mark sector object as empty:

  $object->empty(1);

Clear boolean flag to mark sector object as non-empty:

  $object->empty(0);

clean

Wipe out an entire sector data, and mark it as empty:

  $object->clean();

print

Print out formatted disk sector data:

  $object->print(fh => $fh);

$fh defaults to the standard output.

BUGS

There are no known bugs at the moment. Please report any bugs or feature requests.

EXPORT

None. No method is exported into the caller's namespace neither by default nor explicitly.

SEE ALSO

D64::Disk::Image, D64::Disk::Layout.

AUTHOR

Pawel Krol, <pawelkrol@cpan.org>.

VERSION

Version 0.02 (2013-02-10)

COPYRIGHT AND LICENSE

Copyright 2013 by Pawel Krol <pawelkrol@cpan.org>.

This library is free open source software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.

PLEASE NOTE THAT IT COMES WITHOUT A WARRANTY OF ANY KIND!