/ 
MSDOS-Descript-1.05
River stage zero No dependents
/ MSDOS::Descript

NAME

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

VERSION

This document describes version 1.05 of MSDOS::Descript, released September 20, 2014.

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.

CONFIGURATION AND ENVIRONMENT

MSDOS::Descript requires no configuration files or environment variables.

DEPENDENCIES

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.

SEE ALSO

JP Software (http://jpsoft.com), makers of 4DOS, 4NT, and Take Command. These alternate shells for DOS & Windows originated (and can still use) the DESCRIPT.ION file format.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

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 report any bugs or feature requests to <bug-MSDOS-Descript AT rt.cpan.org> or through the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=MSDOS-Descript.

You can follow or contribute to MSDOS-Descript's development at https://github.com/madsen/msdos-descript.

COPYRIGHT AND LICENSE

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