MSDOS::Descript - Manage 4DOS style DESCRIPT.ION files
This document describes version 1.05 of MSDOS::Descript, released September 20, 2014.
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;
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.
update
write
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.
new
$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.
MSDOS::Descript
$filename
$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.)
$file
$desc
undef
$d->rename($old, $new)
Transfers the description of $old (if any) to $new. This does not actually rename the file on disk.
$old
$new
$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.
read
$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->write if $d->changed
$d->autoupdate([$auto])
Turns on automatic updates for $d if $auto is true or omitted. Otherwise, turns automatic updates off.
$d
$auto
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.
autoupdate
MSDOS::Descript requires no configuration files or environment variables.
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.
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.
None reported.
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.
rename($old, $new)
Christopher J. Madsen <perl AT cjmweb.net>
<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.
<bug-MSDOS-Descript AT rt.cpan.org>
You can follow or contribute to MSDOS-Descript's development at https://github.com/madsen/msdos-descript.
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.
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 MSDOS::Descript, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MSDOS::Descript
CPAN shell
perl -MCPAN -e shell install MSDOS::Descript
For more information on module installation, please visit the detailed CPAN module installation guide.