NAME

MSDOS::Descript - Manage 4DOS style DESCRIPT.ION files

SYNOPSIS

use MSDOS::Descript;
$d = new MSDOS::Descript;
print $d->description('foo.txt');
$d->rename('foo.txt', 'bar.txt');
$d->description('baz.txt','This is Baz.txt');
$d->description('frotz.txt', ''); # Remove description for frotz.txt
$d->update;

DESCRIPTION

MSDOS::Descript provides access to 4DOS style DESCRIPT.ION files.

Remember that changes to the descriptions are not saved unless you call the update or write methods.

By default, MSDOS::Descript uses relative paths, so if you change the current directory between new and update, you'll be writing to a different file. To avoid this, you can pass an absolute path to new.

Methods

$d = MSDOS::Descript->new([$filename])

Constructs a new MSDOS::Descript object. $filename may be a directory or a 4DOS DESCRIPT.ION format file. If it's a directory, looks for a DESCRIPT.ION file in that directory. If $filename is omitted, it defaults to the current directory.

$d->description($file, [$desc])

Gets or sets the description of $file. If $desc is omitted, returns the description of $file or undef if it doesn't have one. Otherwise, sets the description of $file to $desc and returns the old description. (If $desc is the null string or undef, the description is deleted.)

$d->rename($old, $new)

Transfers the description of $old (if any) to $new. This does not actually rename the file on disk.

$d->read([$file])

Load the descriptions from $file. If $file is omitted, then re-read the original description file. Since new does this automatically, you shouldn't have to call read yourself.

$d->read_add($file)

Add the descriptions from $file to the current descriptions.

$d->write([$file])

Writes the descriptions to $file, or the original description file if $file is omitted. Marks the descriptions as unchanged if writing to the original description file. If the current directory has changed since the descriptions were loaded, and the description file was specified by a relative path (which is the default), you will be writing to a different file.

$d->changed

Returns a true value if the descriptions have changed since being loaded from the file.

$d->update

Saves the descriptions to the original file if any changes have been made. The same warning about the current directory applies (see write). Equivalent to $d->write if $d->changed.

$d->autoupdate([$auto])

Turns on automatic updates for $d if $auto is true or omitted. Otherwise, turns automatic updates off.

When automatic updates are on, the descriptions are automatically saved when the object is destroyed. Beware of relative paths! If the current directory changes before the object is destroyed, you're going to be writing to a different file! I strongly suggest that you use absolute paths if you're going to use autoupdate.

REQUIREMENTS

MSDOS::Descript requires the Tie::CPHash module (a case-insensitive hash).

It also uses MSDOS::Attrib to hide DESCRIPT.ION files after it changes them. If you don't have MSDOS::Attrib, it will still work, but any DESCRIPT.ION files changed by MSDOS::Descript will become visible.

Both Tie::CPHash and MSDOS::Attrib are available from CPAN.

BUGS

Uses relative paths, so changing the current directory after loading a description file can cause problems.

If you call rename($old, $new), and $new already had a description but $old did not, $new's description is preserved (instead of being erased). I can't decide if this is a bug or a feature, so I'm leaving it alone for now. This behavior may change in the future.

AUTHOR

Christopher J. Madsen <perl AT cjmweb.net>

Please send bug reports to bug-MSDOS-Descript AT rt.cpan.org, or use the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=MSDOS-Descript