D64::Disk::Dir::Item - Handling individual Commodore (D64/D71/D81) disk image directory items in pure Perl
use D64::Disk::Dir::Item qw(:all); # Create a new disk image directory item instance: my $item = D64::Disk::Dir::Item->new($data); my $item = D64::Disk::Dir::Item->new(@data); my $item = D64::Disk::Dir::Item->new(\@data); # Fetch item data as a scalar of 30 bytes: my $data = $item->data(); # Fetch item data as an array of 30 bytes: my @data = $item->data(); # Update item providing 30 bytes of scalar data: $item->data($data); # Update item given array with 30 bytes of data: $item->data(@data); $item->data(\@data); # Get/set the actual file type: my $type = $item->type(); $item->type($type); # Get/set "closed" flag (when not set produces "*", or "splat" files): my $is_closed = $item->closed(); $item->closed($is_closed); # Get/set "locked" flag (when set produces ">" locked files): my $is_locked = $item->locked(); $item->locked($is_locked); # Get/set track location of first sector of file: my $track = $item->track(); $item->track($track); # Get/set sector location of first sector of file: my $sector = $item->sector(); $item->sector($sector); # Get/set 16 character filename (in CBM ASCII, padded with $A0): my $name = $item->name(); $item->name($name); # Get/set track location of first side-sector block (REL file only): my $side_track = $item->side_track(); $item->side_track($side_track); # Get/set sector location of first side-sector block (REL file only): my $side_sector = $item->side_sector(); $item->side_sector($side_sector); # Get/set relative file record length (REL file only): my $record_length = $item->record_length(); $item->record_length($record_length); # Get/set file size in sectors: my $size = $item->size(); $item->size($size); # Print out formatted disk image directory item: $item->print(); # Validate item data against all possible errors: my $is_valid = $item->validate(); # Check if directory item contains information about the actual disk file: my $is_empty = $item->empty(); # Check if directory item is writable and can be replaced by any new file: my $is_writable = $item->writable(); # Clone disk directory item: my $clone = $item->clone(); # Check if filename matches given CBM ASCII pattern: my $is_matched = $item->match_name($petscii_pattern); # Convert any given file type into its three-letter printable string representation: my $string = D64::Disk::Dir::Item->type_to_string($type);
D64::Disk::Dir::Item provides a helper class for D64::Disk::Layout module, enabling users to manipulate individual directory entries in an object oriented way without the hassle of worrying about the meaning of individual bits and bytes describing each entry in a disk directory. 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.
D64::Disk::Dir::Item
D64::Disk::Layout
Create an instance of a D64::Disk::Dir::Item class as an empty directory entry:
my $item = D64::Disk::Dir::Item->new();
Create an instance of a D64::Disk::Dir::Item class providing 30 bytes of data retrieved from a disk directory:
my $item = D64::Disk::Dir::Item->new(data => $data); my $item = D64::Disk::Dir::Item->new(data => \@data);
Fetch item data as a scalar of 30 bytes:
my $data = $item->data();
Fetch item data as an array of 30 bytes:
my @data = $item->data();
Update item providing 30 bytes of scalar data retrieved from a disk directory:
$item->data($data);
Update item given array with 30 bytes of data retrieved from a disk directory:
$item->data(@data); $item->data(\@data);
bytes is simply a convenient alias for data.
bytes
data
my $bytes = $item->bytes();
my @bytes = $item->bytes();
$item->bytes($bytes);
$item->bytes(@bytes); $item->bytes(\@bytes);
Get the actual file type:
my $type = $item->type();
Set the actual file type:
$item->type($type);
The following file type constants are the only valid values that may be used to update current item type: $T_DEL, $T_SEQ, $T_PRG, $T_USR, $T_REL, $T_CBM, and $T_DIR.
$T_DEL
$T_SEQ
$T_PRG
$T_USR
$T_REL
$T_CBM
$T_DIR
Get "closed" flag:
my $is_closed = $item->closed();
Returns true when "closed" flag is set, and false otherwise.
Set "closed" flag:
$item->closed($is_closed);
When "closed" flag is not set, it produces "*", or "splat" files.
Get "locked" flag:
my $is_locked = $item->locked();
Returns true when "locked" flag is set, and false otherwise.
Set "locked" flag:
$item->locked($is_locked);
When "locked" flag is set, it produces ">" locked files.
Get track location of first sector of file:
my $track = $item->track();
Set track location of first sector of file:
$item->track($track);
Get sector location of first sector of file:
my $sector = $item->sector();
Set sector location of first sector of file:
$item->sector($sector);
Get 16 character filename:
my $name = $item->name();
Returned value is a CBM ASCII string. Unless specified otherwise, it will be padded with $A0.
$A0
Get filename (without $A0 padding):
my $name = $item->name(padding_with_a0 => 0);
padding_with_a0 input parameter defaults to 1. That means every time filename is fetched from a D64::Disk::Dir::Item object, length of a retrieved string will be 16 characters.
padding_with_a0
1
Set 16 character filename:
$item->name($name);
Input name parameter is expected to be CBM ASCII string. Unless specified otherwise, it will be padded with $A0.
Set 16 character filename (without $A0 padding):
$item->name($name, padding_with_a0 => 0);
padding_with_a0 input parameter defaults to 1. That means every time filename is written into a D64::Disk::Dir::Item object, it gets complemented with additional $A0 bytes up to the maximum length of a filename, which is 16 bytes. Thus by default 16 characters of filename data are always stored in a disk directory item.
In order to convert a PETSCII string to an ASCII string and vice versa, use the following subroutines provided by Text::Convert::PETSCII module:
Text::Convert::PETSCII
use Text::Convert::PETSCII qw/:all/; my $ascii_name = petscii_to_ascii($petscii_name); my $petscii_name = ascii_to_petscii($ascii_name);
See Text::Convert::PETSCII module description for more details on ASCII/PETSCII text conversion.
Get track location of first side-sector block:
my $side_track = $item->side_track();
A track location of first side-sector block is returned for relative files only, an undefined value otherwise.
Set track location of first side-sector block:
$item->side_track($side_track);
When attempting to assign track location of first side-sector block for a non-relative file, an exception will be thrown.
Get sector location of first side-sector block:
my $side_sector = $item->side_sector();
A sector location of first side-sector block is returned for relative files only, an undefined value otherwise.
Set sector location of first side-sector block:
$item->side_sector($side_sector);
When attempting to assign sector location of first side-sector block for a non-relative file, an exception will be thrown.
Get relative file record length:
my $record_length = $item->record_length();
A relative file record length is returned for relative files only, an undefined value otherwise.
Get relative file record length (relative file only, maximum value 254):
$item->record_length($record_length);
When attempting to assign relative file record length for a non-relative file or a record length greater than 254, an exception will be thrown.
Get file size in sectors:
my $size = $item->size();
The approximate file size in bytes is <= number_of_sectors * 254.
Set file size in sectors:
$item->size($size);
Get exact file size in bytes:
my $exact_size = $item->exact_size(disk_image => $disk_image_ref);
Warning! Do not use! This method has not been implemented (yet)!
Print out formatted disk image directory item:
$item->print(fh => $fh, as_petscii => $as_petscii);
fh defaults to the standard output. as_petscii defaults to false (meaning that ASCII characters will be printed out by default).
fh
as_petscii
Validate item data against all possible errors:
my $is_valid = $item->validate();
Returns true when all item data is valid, and false otherwise.
Check if directory item contains information about the actual disk file:
my $is_empty = $item->empty();
True value will be returned when directory item object is empty.
Check if slot occupied by this item in a disk directory is writable and can be replaced by any new file that would be written into disk:
my $is_writable = $item->writable();
True value will be returned when directory item object is writable.
Clone disk directory item:
my $clone = $item->clone();
Check if filename matches given CBM ASCII pattern:
my $is_matched = $item->match_name($petscii_pattern);
$petscii_pattern is expected to be a CBM ASCII string containing optional wildcard characters. The following wildcards are allowed/recognized:
$petscii_pattern
An asterisk * character following any program name will yield successful match if filename is starting with that name.
*
A question mark ? character used as a wildcard will match any character in a filename.
?
Convert given file type into its three-letter printable ASCII/PETSCII string representation:
my $string = D64::Disk::Dir::Item->type_to_string($type, $as_petscii);
as_petscii defaults to false (meaning that ASCII characters will be returned by default).
There are no known bugs at the moment. Please report any bugs or feature requests.
No GEOS-specific properties are supported by accessor methods of this module. Due to low popularity of GEOS system and rare amount of GEOS D64 disk images available on the net, I have decided to intentionally skip implementation of VLIR file type format here. Thus all the information needed for the windowing system (icon, window position, creation time/date) cannot be right now accessed conveniently without the knowledge of specific VLIR format details.
VLIR
D64::Disk::Dir::Item exports nothing by default.
You may request the import of file type constants ($T_DEL, $T_SEQ, $T_PRG, $T_USR, $T_REL, $T_CBM, and $T_DIR) individually. All of these constants can be explicitly imported from D64::Disk::Dir::Item by using it with the ":types" tag. All constants can be explicitly imported from D64::Disk::Dir::Item by using it with the ":all" tag.
D64::Disk::Image, D64::Disk::Layout, Text::Convert::PETSCII.
Pawel Krol, <pawelkrol@cpan.org>.
Version 0.07 (2013-03-08)
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!
To install D64::Disk::Dir::Item, copy and paste the appropriate command in to your terminal.
cpanm
cpanm D64::Disk::Dir::Item
CPAN shell
perl -MCPAN -e shell install D64::Disk::Dir::Item
For more information on module installation, please visit the detailed CPAN module installation guide.