file_discard 0.0.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3b38d7bdbec2c063fabda64c3d04131b3c63e5d8
-  data.tar.gz: bae85f1bdf78a07e9c2cb7ec56662a3677507b20
+  metadata.gz: 14285e9f6da20d84c8fcef7ab05e5925d23227da
+  data.tar.gz: ba1853b5b923df31f372412dd4e4eae15f51851e
 SHA512:
-  metadata.gz: 5fb8dfe12a6a995b00ab7cbac31ef85b1345c7d05bd6e13fc96f01a3defbeaf4c67a93ed7d5ddc2d60561416ade98f115c5a3ea9b27d91cb9ae25445c74e7d13
-  data.tar.gz: 4d6d3acb2213a9b2b1d7bdbca853da477cef1569178e57c53427a4683a492df4e0eda90d8e6b60d10e86e22306b6530314b5761bd47b22d38cbfa5ceab1540cf
+  metadata.gz: aef2386c47392dd81be16d1b80b65db910dc96dfd7a2e67e8d1b5ab921136c65d9b40234170e93b06b18514065677acf383a31ddc2edbc9a11124c926df6ddc7
+  data.tar.gz: 618672724fac62bbcef2ea0a57571cb4c4f3f8317ecdae0d026424365dfbe8be1a53f4c38cf84bec81675bc9cf0176e45672bd5192170f802a9b9a0acade83af

data/.gitignore

@@ -0,0 +1,16 @@
+lib/file_discard_version.rb
+
+*.gem
+*.rbc
+/coverage/
+/pkg/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+.ruby-version
+.ruby-gemset
+.rvmrc

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Brad Robel-Forrest
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,169 @@
+`FileDiscard` is a simple helper to make it easy for applications to move files to the correct trash folder. The location is determined by the platform and what file is being discarded (the latter is important so that files on other volumes/mountpoints are moved in to the appropriate trash folder).
+
+## Getting Started
+
+### Using the Executable
+
+Part of the `file_discard` gem is an executable that can be used as a drop-in replacement for "rm":
+
+```shell
+> discard
+Usage: discard [options] file ...
+    -v, --verbose                    show where files are discarded
+    -h, --help                       show this message
+        --version                    show version
+
+Options ignored to provide compatibility with "rm":
+    -d
+    -f
+    -i
+    -P
+    -R
+    -r
+```
+
+### Using the Library
+
+There are two ways for making discard requests. The easiest method extends Ruby's [`File`](http://www.ruby-doc.org/core/File.html) and [`Pathname`](http://www.ruby-doc.org/stdlib/libdoc/pathname/rdoc/Pathname.html) classes to use the new `discard` method instead of `unlink`:
+
+```ruby
+require 'file_discard'
+
+FileDiscard.mix_it_in!
+
+# open a file and discard it from the instance object...
+f = File.open 'file1.txt', 'w'
+f.puts 'one'
+f.close
+f.discard
+
+# create a pathname and discard it from the instance object...
+p = Pathname.new 'file2.txt'
+p.open('w') {|io| io.puts 'two'}
+p.discard
+
+# open a file and discard it using the class...
+f = File.open 'file3.txt', 'w'
+f.puts 'three'
+f.close
+File.discard 'file3.txt'
+
+# create a pathname and discard it using the class...
+p = Pathname.new 'file4.txt'
+p.open('w') {|io| io.puts 'four'}
+Pathname.discard 'file4.txt'
+```
+
+Another approach is to leave Ruby's [`File`](http://www.ruby-doc.org/core/File.html) and [`Pathname`](http://www.ruby-doc.org/stdlib/libdoc/pathname/rdoc/Pathname.html) classes alone and work directly with `FileDiscard`:
+
+```ruby
+require 'file_discard'
+
+# open a file and discard it...
+f = File.open 'file5.txt', 'w'
+f.puts 'five'
+f.close
+FileDiscard.discard 'file5.txt'
+
+# create a pathname and discard it...
+p = Pathname.new 'file6.txt'
+p.open('w') {|io| io.puts 'six'}
+FileDiscard.discard 'file6.txt'
+```
+
+#### More Options
+
+Under the covers, `FileDiscard` makes use of [`FileUtils.mv`](http://ruby-doc.org/stdlib/libdoc/fileutils/rdoc/FileUtils.html#method-c-mv) and passes any other options through:
+
+```ruby
+require 'file_discard'
+
+FileDiscard.mix_it_in!
+
+# open a file and discard it from the instance object...
+f = File.open 'file7.txt', 'w'
+f.puts 'seven'
+f.close
+f.discard verbose:true
+# ===> mv /path/to/file7.txt /Users/brad/.Trash/file7.txt
+
+# create a pathname and discard it using the class...
+p = Pathname.new 'file8.txt'
+p.open('w') {|io| io.puts 'eight'}
+Pathname.discard 'file8.txt', verbose:true
+# ===> mv /path/to/file8.txt /Users/brad/.Trash/file8.txt
+```
+
+Also of note is that `FileDiscard` will not blindly stomp on existing files already present in the trash. Instead, much like OS X's Finder, `FileDiscard` creates new file names based on the time when a collision occurs:
+
+```ruby
+require 'file_discard'
+
+FileDiscard.mix_it_in!
+
+# open a file and discard it from the instance object...
+f = File.open 'samename.txt', 'w'
+f.puts 'samename'
+f.close
+f.discard verbose:true
+# ===> mv /path/to/samename.txt /Users/brad/.Trash/samename.txt
+
+# create a pathname and discard it using the class...
+p = Pathname.new 'samename.txt'
+p.open('w') {|io| io.puts 'samename'}
+Pathname.discard 'samename.txt', verbose:true
+# ===> mv /path/to/samename.txt /Users/brad/.Trash/samename 17.49.44.txt
+```
+
+#### Exceptions
+
+The most common exception raised will be if a discard request is made for a file that does not exist:
+
+```ruby
+require 'file_discard'
+
+FileDiscard.mix_it_in!
+
+p = Pathname.new 'missing1.txt'
+p.discard
+# ===> Errno::ENOENT: No such file or directory @ realpath_rec - /path/to/missing1.txt
+```
+
+## Creating New Discarders
+
+If the built-in trash support isn't working for your platform, creating one is quite simple:
+
+```ruby
+require 'file_discard'
+
+FileDiscard.mix_it_in!
+
+class MyDiscarder < FileDiscard::Discarder
+  def initialize(home = '/path/to/my/home')
+    super home, 'a/trash/folder', '.place-for-mounted-trash-%s'
+  end
+end
+
+FileDiscard.discarder = MyDiscarder.new
+
+p = Pathname.new 'myfile.txt'
+p.open('w') {|io| io.puts 'myfile'}
+p.discard 'myfile.txt'
+
+Pathname.new('/path/to/my/home/a/trash/folder').children
+# ===> [#<Pathname:/path/to/my/home/a/trash/folder/myfile.txt>]
+```
+
+Each `Discarder` is expected to provide the following (as passed to the base class initializer):
+
+1. `home`: An _absolute_ path to the home directory of the current user. `FileDiscard` will expand the path, so on systems that support it, special variables can be used (e.g. a tilde (~) will expand to the current user's home directory on OS X and Linux).
+
+2. `home_trash`: A _relative_ path where the trash is expected from the `home` directory.
+
+3. `mountpoint_trash_fmt`: A _relative_ path where the trash is expected from any given mountpoint. This string can optionally include a `%s` format specifier which will be replaced by the current user's numeric ID (ie. UID).
+
+The base `Discarder` will rely on comparison between mountpoints (as determined by [`Pathname#mountpoint?`](http://www.ruby-doc.org/stdlib/libdoc/pathname/rdoc/Pathname.html#method-i-mountpoint-3F)) to decide if the home trash should be used or if a shared trash for another mounted volume should be used. In other words, if the mountpoint of the file being trashed is _not_ the same as the `home` directory's mountpoint, the `Discarder` will use the trash located in the mountpoint associated with the file being discarded using the `mountpoint_trash_fmt` relative result as presented by the discarder.
+
+If the trash location does not already exist, the `Discarder` will not automatically create it. Instead, it will raise a `Errno::ENOENT` exception for any discard request that attempts to move a file to a trash that does not exist. It is expected that the caller will ensure the trash directories are present before attempting to discard files.
+
+For a more complex example, check out the [`FileDiscard::LinuxDiscarder`](lib/file_discard.rb#L144-L164).

data/Rakefile

@@ -0,0 +1,67 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/clean'
+require 'rubygems/package_task'
+
+task default: :test
+task spec: :test
+task build: :package
+
+PKG_VERSION = '0.1.2'
+NOW = Time.now.utc
+
+# delay updating the version file unless building the gem or package
+task :update_version do
+  File.open('lib/file_discard_version.rb','w') do |f|
+    f.puts <<EOF
+module FileDiscard
+  VERSION = '#{PKG_VERSION}'
+  RELEASE = '#{`git rev-parse --short HEAD`.chomp}:#{NOW.strftime('%Y%m%d%H%M%S')}'
+end
+EOF
+  end
+end
+task package: :update_version
+task gem: :update_version
+
+Rake::TestTask.new do |t|
+  t.pattern = "spec/*_spec.rb"
+end
+
+def list_files
+  if Dir.exist? '.git'
+    `git ls-files -z`.split("\x0")
+  else
+    # e.g. when installed and tasks are run from there...
+    Dir.glob('**/*').select{|e| File.file? e}
+  end
+end
+
+spec = Gem::Specification.new do |s|
+  s.name        = 'file_discard'
+  s.version     = PKG_VERSION
+  s.date        = NOW.strftime('%Y-%m-%d')
+  s.summary     = 'Move files to the trash'
+  s.description = 'Simple helper to move files to the trash folder'
+  s.authors     = ['Brad Robel-Forrest']
+  s.email       = 'brad+filediscard@gigglewax.com'
+  s.files       = list_files << 'lib/file_discard_version.rb'
+  s.test_files  = s.files.grep(%r{^spec/})
+  s.executables = %w(discard)
+  s.homepage    = 'https://github.com/bradrf/file_discard#readme'
+  s.license     = 'MIT'
+
+  s.required_ruby_version = '>= 1.9.0'
+end
+
+Gem::PackageTask.new(spec) do |pkg|
+  pkg.need_zip = true
+  pkg.need_tar = true
+end
+
+desc 'Start GitHub Readme Instant Preview service (see https://github.com/joeyespo/grip)'
+task :grip do
+  exec 'grip --gfm --context=bradrf/file_discard'
+end
+
+CLOBBER.add 'coverage'

data/bin/discard

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'ostruct'
+require 'file_discard'
+
+options = OpenStruct.new
+parser  = OptionParser.new do |opts|
+  Version = FileDiscard::VERSION
+  Release = FileDiscard::RELEASE
+
+  opts.on('-v', '--verbose', 'show where files are discarded') do |v|
+    options.verbose = v
+  end
+
+  opts.on('-h', '--help', 'show this message') do
+    puts opts
+    exit
+  end
+
+  opts.on('--version', 'show version') do
+    puts opts.ver
+    exit
+  end
+
+  opts.separator('')
+  opts.separator('Options ignored to provide compatibility with "rm":')
+  [?d,?f,?i,?P,?R,?r].each {|a| opts.on("-#{a}")}
+
+  opts.banner << ' file ...'
+end
+
+parser.parse!
+
+if ARGV.size < 1
+  puts parser
+  exit 64 # use same exit status as rm with no files
+end
+
+status = 0
+ARGV.each do |file|
+  begin
+    FileDiscard.discard(file, options.marshal_dump)
+  rescue Errno::EINVAL, Errno::ENOENT => ex
+    $stderr.puts "#{parser.program_name}: #{file}: #{ex.message}"
+    status = 1
+  rescue Exception => ex
+    $stderr.puts "#{parser.program_name}: #{file}: #{ex.class} #{ex.message}"
+    $stderr.puts ex.backtrace if options.verbose
+    status = 2
+  end
+end
+
+exit status

data/lib/file_discard.rb

@@ -25,14 +25,14 @@ require 'fileutils'
 
 module FileDiscard
 
-  VERSION = '0.0.1'
+  load "#{File.dirname(__FILE__)}/file_discard_version.rb"
 
   ######################################################################
   # Module Methods
 
   def self.mix_it_in!
-    [File, Pathname].each do |c|
-      c.class_eval do
+    [File, Pathname].each do |klass|
+      klass.class_eval do
         def self.discard(*args)
           FileDiscard.discarder.discard(*args)
         end
@@ -66,8 +66,10 @@ module FileDiscard
   # Discarders
 
   class Discarder
-    def initialize(home_trash, mountpoint_trash_fmt)
-      home = Pathname.new('~').expand_path
+    SPECIAL_DIRS = ['.','..']
+
+    def initialize(home, home_trash, mountpoint_trash_fmt)
+      home = pathname_for(home).expand_path
       @home_trash = home.join(home_trash)
       @home_mountpoint = mountpoint_of home
       @mountpoint_trash_fmt = mountpoint_trash_fmt
@@ -75,10 +77,12 @@ module FileDiscard
 
     def discard(obj, move_options = {})
       pn = pathname_for obj
+      if SPECIAL_DIRS.include?(pn.basename.to_s)
+        raise Errno::EINVAL.new(SPECIAL_DIRS.join(' and ') << ' may not be removed')
+      end
       trash = find_trash_for pn
       raise Errno::ENOENT.new(trash.to_s) unless trash.exist?
-      dst = uniquify(trash.join(pn.basename))
-      FileUtils.mv pn.expand_path, dst, move_options
+      move(pn, trash, move_options)
     end
 
     private
@@ -104,36 +108,58 @@ module FileDiscard
         end
       end
 
+      def move(src, dst, options)
+        src = src.expand_path
+        dst = uniquify(dst.join(src.basename))
+        FileUtils.mv src, dst, options
+        yield src, dst if block_given?
+      end
+
       def uniquify(pn)
         return pn unless pn.exist?
 
+        dn   = pn.dirname
         ext  = pn.extname
         base = pn.basename(ext).to_s
-        dn   = pn.dirname
 
-        count = 0
         fmt = bfmt = '%H.%M.%S'
 
-        loop do
+        10.times do |i|
           ts = Time.now.strftime(fmt)
           pn = dn.join("#{base} #{ts}#{ext}")
           return pn unless pn.exist?
-          fmt = bfmt + ".%#{count}N" # use fractional seconds, with increasing precision
-          count += 1
+          fmt = bfmt + ".%#{i}N" # use fractional seconds, with increasing precision
         end
+
+        raise RuntimeError.new(%{Unable to uniquify "#{base}" (last attempt: #{pn})})
       end
   end # class Discarder
 
   class OsxDiscarder < Discarder
-    def initialize
-      super '.Trash', '.Trashes/%s'
+    def initialize(home = '~')
+      super home, '.Trash', '.Trashes/%s'
     end
   end
 
   class LinuxDiscarder < Discarder
-    def initialize
-      super '.local/share/Trash', '.Trash-%s'
+    def initialize(home = '~')
+      super home, '.local/share/Trash/files', '.Trash-%s/files'
     end
+
+    # Linux has a special layout for the trash folder and tracking for restore.
+    # See http://www.freedesktop.org/wiki/Specifications/trash-spec/
+    private
+      def move(*args)
+        super do |src, dst|
+          dst.dirname.dirname.join('info',"#{dst.basename}.trashinfo").open('w') do |io|
+            io.write <<EOF
+[Trash Info]
+Path=#{src}
+DeletionDate=#{Time.now.strftime('%Y-%m-%dT%H:%M:%S')}
+EOF
+          end
+        end
+      end
   end
 
 end # module FileDiscard

data/spec/file_discard_spec.rb

@@ -0,0 +1,148 @@
+#!/usr/bin/env ruby
+
+begin
+  require 'simplecov'
+  SimpleCov.start
+rescue LoadError
+  # not required, but nice for reports on what code the tests have touched
+end
+
+require 'tmpdir'
+require 'minitest/spec'
+require 'minitest/autorun'
+
+load File.expand_path(File.join(File.dirname(__FILE__),'..','lib','file_discard.rb'))
+
+describe FileDiscard do
+
+  describe :Discarder do
+    before do
+      @base = Pathname.new(Dir.mktmpdir(File.basename(__FILE__,'.rb') + '_'))
+      @home = @base.join('home')
+      @home.mkdir
+      @home_trash = '.Trash'
+
+      @discarder = FileDiscard::OsxDiscarder.new(@home)
+      FileDiscard.discarder = @discarder
+    end
+
+    after do
+      @base.rmtree if @base && @base.exist?
+    end
+
+    it 'should not allow removal of special directories' do
+      ['.','..'].each do |dir|
+        ->{ FileDiscard.discard(dir) }.must_raise Errno::EINVAL
+      end
+    end
+
+    describe 'when mixed in' do
+      before do
+        FileDiscard.mix_it_in!
+      end
+
+      it 'should extend classes' do
+        [File, Pathname].each do |klass|
+          klass.must_respond_to :discard
+        end
+      end
+
+      it 'should fail without trash' do
+        f = File.new(@base.join('file.txt').to_s, 'w')
+        ->{ f.discard }.must_raise Errno::ENOENT
+      end
+
+      describe 'with trash in the home' do
+        before do
+          @trash = @home.join(@home_trash)
+          @trash.mkdir
+        end
+
+        def sorted_trash
+          @trash.children(false).collect(&:to_s).sort
+        end
+
+        it 'should discard a file' do
+          f = File.new(@base.join('file.txt').to_s, 'w')
+          f.discard
+          sorted_trash.must_equal ['file.txt']
+        end
+
+        it 'should discard a pathname' do
+          f = @base.join('file.txt')
+          f.open('w') {|io| io.puts 'nothing'}
+          f.discard
+          sorted_trash.must_equal ['file.txt']
+        end
+
+        describe 'with control over time' do
+          before do
+            # replace Time's strftime which FileDiscard relies on for uniquify
+            class Time
+              alias :orig_strftime :strftime
+              @@strftime_count = 0
+              def strftime(fmt)
+                @@strftime_count += 1
+                "9.8.#{@@strftime_count}"
+              end
+            end
+          end
+
+          after do
+            if Time.now.respond_to? :orig_strftime
+              class Time
+                alias :strftime :orig_strftime
+              end
+            end
+          end
+
+          it 'should not overwite other trashed files' do
+            f = @trash.join('file.txt')
+            f.open('w') {|io| io.puts 'nothing'}
+
+            f = @base.join('file.txt')
+            f.open('w') {|io| io.puts 'nothing'}
+            FileDiscard.discard(f.to_s)
+            sorted_trash.must_equal ['file 9.8.1.txt','file.txt']
+          end
+
+          it 'should use increasing precision for collisions' do
+            3.times do |i|
+              f = @trash.join(%{file#{i == 0 ? '' : " 9.8.#{i}"}.txt})
+              f.open('w') {|io| io.puts 'nothing'}
+            end
+
+            f = @base.join('file.txt')
+            f.open('w') {|io| io.puts 'nothing'}
+            File.discard(f.to_s)
+            sorted_trash
+              .must_equal ['file 9.8.1.txt', 'file 9.8.2.txt', 'file 9.8.3.txt', 'file.txt']
+          end
+        end
+
+        describe 'with control over mountpoints' do
+          class MyDiscarder < FileDiscard::Discarder
+            private
+            def mountpoint_of(pn)
+              pn
+            end
+          end
+
+          before do
+            @trash = @base.join('mytrash-%s' % Process.uid)
+            @trash.mkdir
+            @discarder = MyDiscarder.new(@home, 'mytrash', 'mytrash-%s')
+            FileDiscard.discarder = @discarder
+          end
+
+          it 'should not use the home trash' do
+            f = @base.join('file.txt')
+            f.open('w') {|io| io.puts 'nothing'}
+            f.discard
+            sorted_trash.must_equal ['file.txt']
+          end
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,22 +1,30 @@
 --- !ruby/object:Gem::Specification
 name: file_discard
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Brad Robel-Forrest
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-04 00:00:00.000000000 Z
+date: 2014-06-06 00:00:00.000000000 Z
 dependencies: []
-description: Simple helper to move files to the trash on OS X or Linux platforms
+description: Simple helper to move files to the trash folder
 email: brad+filediscard@gigglewax.com
-executables: []
+executables:
+- discard
 extensions: []
 extra_rdoc_files: []
 files:
+- ".gitignore"
+- LICENSE
+- README.md
+- Rakefile
+- bin/discard
 - lib/file_discard.rb
+- lib/file_discard_version.rb
+- spec/file_discard_spec.rb
 homepage: https://github.com/bradrf/file_discard#readme
 licenses:
 - MIT
@@ -29,7 +37,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.9.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -41,4 +49,5 @@ rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: Move files to the trash
-test_files: []
+test_files:
+- spec/file_discard_spec.rb