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:

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

      * 

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/mince/.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/mince/file1", deletion_date=>1342061508,
       trash_dir=>"/home/mince/.local/share/Trash"},
      {entry=>"file1.2", path=>"/home/mince/sub/file1", deletion_date=>1342061580,
       trash_dir=>"/home/mince/.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:

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

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

      * 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 => STR

      Only recover file having the specified suffix, chosen previously
      during 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.

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:

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

