The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
AppleII-LibA2-0.201
River stage zero No dependents
++
/ AppleII::ProDOS

NAME

AppleII::ProDOS - Access files on Apple II ProDOS disk images

VERSION

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

SYNOPSIS

    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

DESCRIPTION

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.

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.

AppleII::ProDOS

AppleII::ProDOS is the primary interface to ProDOS volumes. It provides the following methods:

$vol = AppleII::ProDOS->new($volume, $size, $filename, [$mode])

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.

$vol = AppleII::ProDOS->open($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
$vol = AppleII::ProDOS->open($disk)

Constructs an AppleII::ProDOS object to access an existing image file. $disk is the AppleII::Disk object representing the image file.

$bitmap = $vol->bitmap

Returns the volume bitmap as an AppleII::ProDOS::Bitmap object.

$dir = $vol->dir

Returns the current directory as an AppleII::ProDOS::Directory object.

$disk = $vol->disk

Returns the AppleII::ProDOS::Disk object which represents the image file.

$disk = $vol->disk_size

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.

$name = $vol->name

Returns the volume name.

$path = $vol->path([$newpath])

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 /.

$catalog = $vol->catalog
$file = $vol->get_file($filename)
$entry = $vol->new_dir($name)
$vol->put_file($file)

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:

$dir = AppleII::ProDOS::Directory->new($name, $disk, $blocks, $bitmap, [$parent, $parentNum])

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).

$dir = AppleII::ProDOS->open($disk, $block, $bitmap)

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.

$catalog = $dir->catalog

Returns the directory listing in ProDOS format with free space information.

@entries = $dir->entries

Returns the contents of the directory as a list of AppleII::ProDOS::DirEntry objects.

$entry = $dir->find_entry($filename)

Returns the AppleII::ProDOS::DirEntry object for $filename, or undef if the specified file does not exist.

$file = $dir->get_file($filename)

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.

@entries = $dir->list_matches($pattern, [$filter])

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.

$entry = $dir->new_dir($name)

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.

$entry = $dir->open_dir($dirname)

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.

$dir->put_file($file)

Stores a file in the directory. $file must be an AppleII::ProDOS::File object.

$dir->add_entry($entry)

Adds a new entry to the directory. $entry is an AppleII::ProDOS::DirEntry object.

$dir->read_disk

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.

$dir->write_disk

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.

AppleII::ProDOS::DirEntry

AppleII::ProDOS::DirEntry provides access to directory entries. It provides the following methods:

$entry = AppleII::ProDOS::DirEntry->new([$num, $entry])

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.

$packed_entry = $entry->packed($key_block)

Return the directory entry in packed format. $key_block is the starting block number of the directory containing this entry.

$access = $entry->access([$new])

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.

$auxtype = $entry->auxtype([$new])

Gets or sets the auxiliary type. This is a number between 0x0000 and 0xFFFF. Its meaning depends on the filetype.

$creation_date = $entry->created([$date])

Gets or sets the creation date and time in ProDOS format.

$modification_date = $entry->modified([$date])

Gets or sets the modification date and time in ProDOS format.

$name = $entry->name([$new])

Gets or sets the filename.

$type = $entry->type([$new])

Gets or sets the filetype. This is a number between 0x00 and 0xFF. Use parse_type to convert it to a more meaningful abbreviation.

$type = $entry->short_type Returns the standard abbreviation for the filetype. It is equivalent to calling 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.

$block = $entry->block([$new])

Gets or sets the key block for the file.

$used = $entry->blks_used([$new])

Gets or sets the number of blocks used by the file.

$entry_num = $entry->num([$new])

Gets or sets the entry number in the directory.

$size = $entry->size([$new])

Gets or sets the size of the file in bytes.

$storage = $entry->storage([$new])

Gets or sets the storage type.

NOTE

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

AppleII::ProDOS::File represents a file's data and other attributes.

AppleII::ProDOS::Bitmap

AppleII::ProDOS::Bitmap represents the volume bitmap.

AppleII::ProDOS::Index

AppleII::ProDOS::Index represents an index block.

CONFIGURATION AND ENVIRONMENT

AppleII::ProDOS requires no configuration files or environment variables.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

  • 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.

AUTHOR

Christopher J. Madsen <perl AT cjmweb.net>

Please report any bugs or feature requests to <bug-AppleII-LibA2 AT rt.cpan.org> or through the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=AppleII-LibA2.

You can follow or contribute to AppleII-LibA2's development at https://github.com/madsen/perl-libA2.

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 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.

DISCLAIMER OF WARRANTY

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.