AppleII::ProDOS - Access files on Apple II ProDOS disk images
This document describes version 0.10 of AppleII::ProDOS, released December 26, 2013 as part of LibA2 version 0.11.
use AppleII::ProDOS; my $vol = AppleII::ProDOS->open('image.dsk'); # Open an existing disk print $vol->catalog; # List files in volume directory my $file = $vol->get_file('Startup'); # Read file from disk $vol->path('Subdir'); # Move into a subdirectory $vol->put_file($file); # And write it back there
AppleII::ProDOS provides high-level access to ProDOS volumes stored in the 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.) It uses the AppleII::Disk module to handle low-level access to image files.
AppleII::ProDOS
All the following classes have two constructors. Constructors named open are for creating an object to represent existing data in the image file. Constructors named new are for creating a new object to be added to an image file.
open
new
AppleII::ProDOS is the primary interface to ProDOS volumes. It provides the following methods:
Constructs a new image file and an AppleII::ProDOS object to access it. $volume is the volume name. $size is the size in blocks. $filename is the name of the image file. The optional $mode is a string specifying how to open the image (see the open method for details). You always receive read and write access.
$volume
$size
$filename
$mode
Constructs an AppleII::ProDOS object to access an existing image file. $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
Constructs an AppleII::ProDOS object to access an existing image file. $disk is the AppleII::Disk object representing the image file.
$disk
AppleII::Disk
Returns the volume bitmap as an AppleII::ProDOS::Bitmap object.
AppleII::ProDOS::Bitmap
Returns the current directory as an AppleII::ProDOS::Directory object.
Returns the AppleII::ProDOS::Disk object which represents the image file.
AppleII::ProDOS::Disk
Returns the size of the volume in blocks. This is the logical size of the ProDOS volume, which is not necessarily the same as the actual size of the image file.
Returns the volume name.
Gets or sets the current path. $newpath is the new pathname, which may be either relative or absolute. `..' may be used to specify the parent directory, but this must occur at the beginning of the path (`../../dir' is valid, but `../dir/..' is not). If $newpath is omitted, then the current path is not changed. Returns the current path as a string beginning and ending with /.
$newpath
/
These methods are passed to the current directory. See AppleII::ProDOS::Directory for details.
AppleII::ProDOS::Directory
AppleII::ProDOS::Directory represents a ProDOS directory. It provides the following methods:
Constructs a new AppleII::ProDOS::Directory object. $name is the name of the directory. $disk is the AppleII::Disk to create it on. $blocks is a block number or an array of block numbers to store the directory in. $bitmap is the AppleII::ProDOS::Bitmap representing the volume bitmap. For a subdirectory, $parent must be the block number in the parent directory where the subdirectory is listed, and $parentNum is the entry number in that block (with 1 being the first entry).
$name
$blocks
$bitmap
$parent
$parentNum
Constructs an AppleII::ProDOS::Directory object to access an existing directory in the image file. $disk is the AppleII::Disk object representing the image file. $block is the block number where the directory begins. $bitmap is the AppleII::ProDOS::Bitmap representing the volume bitmap.
$block
Returns the directory listing in ProDOS format with free space information.
Returns the contents of the directory as a list of AppleII::ProDOS::DirEntry objects.
AppleII::ProDOS::DirEntry
Returns the AppleII::ProDOS::DirEntry object for $filename, or undef if the specified file does not exist.
Retrieves a file from the directory. $filename may be either a filename or an AppleII::ProDOS::DirEntry object. Returns a new AppleII::ProDOS::File object.
AppleII::ProDOS::File
Returns a list of the AppleII::ProDOS::DirEntry objects matching the regexp $pattern. If $filter is specified, it is either a subroutine reference or one of the strings 'DIR' or '!DIR'. 'DIR' matches only directories, and '!DIR' matches only regular files. If $filter is a subroutine, it is called (as \&$filter($entry)) for each entry. It should return true if the entry is acceptable (the entry's name must still match $pattern). Returns the null list if there are no matching entries.
$pattern
$filter
\&$filter($entry)
Creates a new subdirectory in the directory. $name is the name of the new subdirectory. Returns the AppleII::ProDOS::DirEntry object representing the new subdirectory entry.
Opens a subdirectory of the directory. $dirname may be either a subdirectory name or an AppleII::ProDOS::DirEntry object. Returns a new AppleII::ProDOS::Directory object.
$dirname
Stores a file in the directory. $file must be an AppleII::ProDOS::File object.
$file
Adds a new entry to the directory. $entry is an AppleII::ProDOS::DirEntry object.
$entry
Rereads the directory contents from the image file. You can use this to undo changes to a directory before they have been written to the image file.
Writes the current directory contents to the image file. You must use this if you alter the directory contents in any way except the high-level methods new_dir and put_file, which do this automatically.
new_dir
put_file
AppleII::ProDOS::DirEntry provides access to directory entries. It provides the following methods:
Constructs a new AppleII::ProDOS::DirEntry object. $num is the entry number in the directory, and $entry is the packed directory entry. If $num and $entry are omitted, then a blank directory entry is created. This is a low-level function; you shouldn't need to explicitly construct DirEntry objects.
$num
Return the directory entry in packed format. $key_block is the starting block number of the directory containing this entry.
$key_block
Gets or sets the access attributes. This is a bitfield with the following entries:
0x80 File can be deleted 0x40 File can be renamed 0x20 File has changed since last backup 0x02 File can be written to 0x01 File can be read
Normal values are 0xC3 or 0xE3 for an unlocked file, and 0x01 for a locked file.
Gets or sets the auxiliary type. This is a number between 0x0000 and 0xFFFF. Its meaning depends on the filetype.
Gets or sets the creation date and time in ProDOS format.
Gets or sets the modification date and time in ProDOS format.
Gets or sets the filename.
Gets or sets the filetype. This is a number between 0x00 and 0xFF. Use parse_type to convert it to a more meaningful abbreviation.
parse_type
AppleII::ProDOS::parse_type($entry->type)
The following methods allow access to read-only fields. They can be used to initialize a DirEntry object created with new, but raise an exception if the field already has a value.
Gets or sets the key block for the file.
Gets or sets the number of blocks used by the file.
Gets or sets the entry number in the directory.
Gets or sets the size of the file in bytes.
Gets or sets the storage type.
This is the point where I ran out of steam in documentation writing. :-) If I get at least one email from someone who'd actually read the rest of this documentation, I'll try to finish it.
AppleII::ProDOS::File represents a file's data and other attributes.
AppleII::ProDOS::Bitmap represents the volume bitmap.
AppleII::ProDOS::Index
AppleII::ProDOS::Index represents an index block.
AppleII::ProDOS requires no configuration files or environment variables.
None reported.
This document isn't finished yet. I haven't been working on it recently, so I decided I might as well just release what I have. If somebody writes me, I'm more likely to finish. (That's a hint, folks.)
Mixed case filenames (ala GS/OS) are not supported. All filenames are converted to upper case.
Christopher J. Madsen <perl AT cjmweb.net>
<perl AT cjmweb.net>
Please report any bugs or feature requests to <bug-LibA2 AT rt.cpan.org> or through the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=LibA2.
<bug-LibA2 AT rt.cpan.org>
You can follow or contribute to LibA2's development at https://github.com/madsen/perl-libA2.
This software is copyright (c) 2013 by Christopher J. Madsen.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
To install AppleII::Disk, copy and paste the appropriate command in to your terminal.
cpanm
cpanm AppleII::Disk
CPAN shell
perl -MCPAN -e shell install AppleII::Disk
For more information on module installation, please visit the detailed CPAN module installation guide.