Steven Haryanto > File-Trash-FreeDesktop-0.14 > File::Trash::FreeDesktop

Download:
File-Trash-FreeDesktop-0.14.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 0.14   Source  

NAME ^

File::Trash::FreeDesktop - Trash files

VERSION ^

This document describes version 0.14 of File::Trash::FreeDesktop (from Perl distribution File-Trash-FreeDesktop), released on 2014-05-17.

SYNOPSIS ^

 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;

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:

Some other notes:

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

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:

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

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

NOTES ^

Weird scenario: /PATH/.Trash-UID is mounted on its own scenario? How about /PATH/.Trash-UID/{files,info}.

SEE ALSO ^

[1] http://freedesktop.org/wiki/Specifications/trash-spec

Related modules on CPAN:

HOMEPAGE ^

Please visit the project's homepage at https://metacpan.org/release/File-Trash-FreeDesktop.

SOURCE ^

Source repository is at https://github.com/sharyanto/perl-File-Trash-FreeDesktop.

BUGS ^

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.

AUTHOR ^

Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE ^

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.

syntax highlighting: