NAME
    File::Trash::FreeDesktop - Trash files

VERSION
    version 0.02

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($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").

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