File::Trash::FreeDesktop - Trash files
This document describes version 0.14 of File::Trash::FreeDesktop (from Perl distribution File-Trash-FreeDesktop), released on 2014-05-17.
use File::Trash::FreeDesktop; my $trash = File::Trash::FreeDesktop->new; # list available (for the running user) trash directories my @trashes = $trash->list_trashes; # list the content of a trash directory my @content = $trash->list_contents("/tmp/.Trash-1000"); # list the content of all available trash directories my @content = $trash->list_contents; # trash a file $trash->trash("/foo/bar"); # specify some options when trashing $trash->trash({on_not_found=>'ignore'}, "/foo/bar"); # recover a file from trash (untrash) $trash->recover('/foo/bar'); # untrash a file from a specific trash directory $trash->recover('/tmp/file', '/tmp/.Trash-1000'); # specify some options when untrashing $trash->recover({on_not_found=>'ignore', on_target_exists=>'ignore'}, '/path'); # empty a trash directory $trash->empty("$ENV{HOME}/.local/share/Trash"); # empty all available trashes $trash->empty;
This module lets you trash/erase/restore files, also list the contents of trash directories. This module follows the freedesktop.org trash specification [1], with some notes/caveats:
For home trash, $HOME/.local/share/Trash is used instead of $HOME/.Trash
This is what KDE and GNOME use these days.
Symlinks are currently not checked
The spec requires implementation to check whether trash directory is a symlink, and refuse to use it in that case. This module currently does not do said checking.
Currently cross-device copying is not implemented/done
It should not matter though, because trash directories are per-filesystem.
Some other notes:
Constructor.
Currently there are no known options.
List user's existing trash directories on the system.
Return a list of trash directories. Sample output:
("/home/steven/.local/share/Trash", "/tmp/.Trash-1000")
List contents of trash director(y|ies).
If $trash_dir is not specified, list contents from all existing trash directories. Die if $trash_dir does not exist or inaccessible or corrupt. Return a list of records like the sample below:
({entry=>"file1", path=>"/home/steven/file1", deletion_date=>1342061508, trash_dir=>"/home/steven/.local/share/Trash"}, {entry=>"file1.2", path=>"/home/steven/sub/file1", deletion_date=>1342061580, trash_dir=>"/home/steven/.local/share/Trash"}, {entry=>"dir1", path=>"/tmp/dir1", deletion_date=>1342061510, trash_dir=>"/tmp/.Trash-1000"})
Trash a file (move it into trash dir).
Will try to find a trash dir that resides in the same filesystem/device as the file and is writable. $home/.local/share/Trash is tried first, then $device_root/.Trash-$uid, then $device_root/tmp/.Trash-$uid. Will die if no suitable trash dir is found.
$home/.local/share/Trash
$device_root/.Trash-$uid
$device_root/tmp/.Trash-$uid
Will also die if moving file to trash (currently using rename()) fails.
Upon success, will return the location of the file in the trash dir (e.g. /tmp/.Trash-1000/files/foo).
/tmp/.Trash-1000/files/foo
If first argument is a hashref, it will be accepted as options. Known options:
on_not_found => STR (default 'die')
Specify what to do when the file to be deleted is not found. The default is 'die', but can also be set to 'ignore' and return immediately.
suffix => STR
Pick a suffix. Normally, file will be stored in files/ORIGNAME inside trash directory, or, if that file already exists, in files/ORIGNAME.1, files/ORIGNAME.2, and so on. This setting overrides this behavior and picks files/ORIGNAME.SUFFIX. Can be used to identify and restore particular file later. However, will die if file with that suffix already exists, so be sure to pick a unique suffix.
files/ORIGNAME
files/ORIGNAME.1
files/ORIGNAME.2
files/ORIGNAME.SUFFIX
Recover a file from trash.
Unless $trash_dir is specified, will search in all existing user's trash dirs. Will die on errors.
Specify what to do when file is not found in the trash. The default is 'die', but can also be set to 'ignore' and return immediately.
on_target_exists => STR (default 'die')
Specify what to do when restore target already exists. The default is 'die', but can also be set to 'ignore' and return immediately.
mtime => INT
Only recover file if file's mtime is the one specified. This can be useful to make sure that the file we recover is really the one that we trashed earlier, especially if we trash several files with the same path.
(Ideally, instead of mtime we should use some unique ID that we write in the .trashinfo file, but I fear that an extra parameter in .trashinfo file might confuse other implementations.)
See also suffix, which is the recommended way to identify and recover particular file.
suffix
Only recover file having the specified suffix, chosen previously during trash().
Erase (unlink()) a file in trash.
Unless $trash_dir is specified, will empty all existing user's trash dirs. Will ignore if file does not exist in trash. Will die on errors.
Return list of files erased.
Empty trash.
Unless $trash_dir is specified, will empty all existing user's trash dirs. Will die on errors.
Weird scenario: /PATH/.Trash-UID is mounted on its own scenario? How about /PATH/.Trash-UID/{files,info}.
[1] http://freedesktop.org/wiki/Specifications/trash-spec
Related modules on CPAN:
Trash::Park
Different trash structure (a single CSV file per trash to hold a list of deleted files, files stored using original path structure, e.g. home/dir/file). Does not create per-filesystem trash.
home/dir/file
File::Trash
Different trash structure (does not keep info file, files stored using original path structure, e.g. home/dir/file). Does not create per-filesystem trash.
File::Remove
File::Remove includes the trash() function which supports Win32, but no undeletion function is provided at the time of this writing.
Please visit the project's homepage at https://metacpan.org/release/File-Trash-FreeDesktop.
Source repository is at https://github.com/sharyanto/perl-File-Trash-FreeDesktop.
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=File-Trash-FreeDesktop
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
Steven Haryanto <stevenharyanto@gmail.com>
This software is copyright (c) 2014 by Steven Haryanto.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install File::Trash::FreeDesktop, copy and paste the appropriate command in to your terminal.
cpanm
cpanm File::Trash::FreeDesktop
CPAN shell
perl -MCPAN -e shell install File::Trash::FreeDesktop
For more information on module installation, please visit the detailed CPAN module installation guide.