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

NAME

File::Trash::FreeDesktop - Trash files

VERSION

version 0.01

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},
 {entry=>"file1.2", path=>"/home/steven/sub/file1", deletion_date=>1342061580},
 {entry=>"dir1", path=>"/tmp/dir1", deletion_date=>1342061510})

$trash->trash($file)

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.

$trash->recover($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 (e.g. file is not found in trash).

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