/ 
File-Trash-FreeDesktop-0.04
River stage two • 4 direct dependents • 17 total dependents
/ File::Trash::FreeDesktop

NAME

File::Trash::FreeDesktop - Trash files

VERSION

version 0.04

SYNOPSIS

use File::Trash::FreeDesktop;

my $trash = File::Trash::FreeDesktop->new;

DESCRIPTION

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

  • Currently meant to be used by normal users, not administrators

    This means, among others, this module only creates $topdir/.Trash-$uid instead of $topdir/.Trash. And there are less paranoid checks being done.

METHODS

$trash = File::Trash::FreeDesktop->new(%opts)

Constructor.

Currently there are no known options.

$trash->list_trashes() => LIST

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

$trash->list_contents([$trash_dir]) => LIST

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->trash([\%opts, ]$file) => STR

Trash a file (move it into trash dir).

Will attempt to create $home/.local/share/Trash (or $topdir/.Trash-$uid if file does not reside in the same filesystem/device as user's home). Will die if attempt fails.

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

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.

$trash->recover([\%opts, ]$file[, $trash_dir])

Recover a file from trash.

Unless $trash_dir is specified, will search in all existing user's trash dirs. Will die on errors.

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 file is not found in the trash. The default is 'die', but can also be set to 'ignore' and return immediately.

$trash->erase($file[, $trash_dir]) => LIST

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.

$trash->empty([$trash_dir]) => LIST

Empty trash.

Unless $trash_dir is specified, will empty all existing user's trash dirs. Will die on errors.

Return list of files erased.

SEE ALSO

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

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

AUTHOR

Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE

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