NAME
D64::Disk::Dir::Item - Handling individual Commodore (D64/D71/D81) disk image directory items in pure Perl
SYNOPSIS
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);DESCRIPTION
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.
METHODS
new
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);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
bytes is simply a convenient alias for data.
Fetch item data as a scalar of 30 bytes:
my $bytes = $item->bytes();Fetch item data as an array of 30 bytes:
my @bytes = $item->bytes();Update item providing 30 bytes of scalar data retrieved from a disk directory:
$item->bytes($bytes);Update item given array with 30 bytes of data retrieved from a disk directory:
$item->bytes(@bytes);
$item->bytes(\@bytes);type
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.
closed
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.
locked
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.
track
Get track location of first sector of file:
my $track = $item->track();Set track location of first sector of file:
$item->track($track);sector
Get sector location of first sector of file:
my $sector = $item->sector();Set sector location of first sector of file:
$item->sector($sector);name
Get 16 character filename:
my $name = $item->name();Returned value is a CBM ASCII string. Unless specified otherwise, it will be padded with $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.
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:
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.
side_track
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.
side_sector
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.
record_length
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.
size
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);exact_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, verbose => $verbose);fh defaults to the standard output. as_petscii defaults to false (meaning that ASCII characters will be printed out by default). verbose defaults to false (changing it to true will additionally print out file's track and sector values).
validate
Validate item data against all possible errors:
my $is_valid = $item->validate();Returns true when all item data is valid, and false otherwise.
empty
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.
writable
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
Clone disk directory item:
my $clone = $item->clone();match_name
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:
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.
type_to_string
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).
BUGS
There are no known bugs at the moment. Please report any bugs or feature requests.
CAVEATS
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.
EXPORT
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.
SEE ALSO
D64::Disk::Image, D64::Disk::Layout, Text::Convert::PETSCII.
AUTHOR
Pawel Krol, <pawelkrol@cpan.org>.
VERSION
Version 0.08 (2023-05-12)
COPYRIGHT AND LICENSE
Copyright 2013-2023 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!