file_discard 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 14285e9f6da20d84c8fcef7ab05e5925d23227da
-  data.tar.gz: ba1853b5b923df31f372412dd4e4eae15f51851e
+  metadata.gz: 80106d989c491a8d79a5b2f6eca34d4a73a12bd1
+  data.tar.gz: 262dc75d7c97871b948ea70064df0f0021f07dcc
 SHA512:
-  metadata.gz: aef2386c47392dd81be16d1b80b65db910dc96dfd7a2e67e8d1b5ab921136c65d9b40234170e93b06b18514065677acf383a31ddc2edbc9a11124c926df6ddc7
-  data.tar.gz: 618672724fac62bbcef2ea0a57571cb4c4f3f8317ecdae0d026424365dfbe8be1a53f4c38cf84bec81675bc9cf0176e45672bd5192170f802a9b9a0acade83af
+  metadata.gz: e4370a3a0c0228c31b4f402224a1d3edf5d1918f4ee5c502ba6983fefc4bd27abf2e9c8c897f27310713229c4e1f1cbeda65ed2e5c127c4d2334f20550cb0bfb
+  data.tar.gz: 1f84dc4c065f51175c48332aacc3976b29a40c0db72f331bc79498ab6ae2dfcf1cb68aa1f1f94caa3ee54d42feabe59c81964e00eff2fda8af8d406141fd84a3

data/README.md

@@ -1,4 +1,4 @@
-`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).
+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
 
@@ -9,17 +9,17 @@ Part of the `file_discard` gem is an executable that can be used as a drop-in re
 ```shell
 > discard
 Usage: discard [options] file ...
+    -d, --dir                        allow empty directories to be discarded
+    -r                               allow directories to be discarded recursively
+    -R, --recursive                  allow directories to be discarded recursively
     -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
+    -I
 ```
 
 ### Using the Library
@@ -54,7 +54,7 @@ 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`:
+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'
@@ -73,7 +73,7 @@ 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:
+A call to discard can enable a report of the operation that is taking place:
 
 ```ruby
 require 'file_discard'
@@ -94,7 +94,9 @@ 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:
+Other options can be enabled to allow discarding empty directories (:directory) or directories with items in them (:recursive).
+
+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'
@@ -154,16 +156,16 @@ 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):
+Each FileDiscard::Discarder is expected to provide the following (as passed to FileDiscard::Discarder.new):
 
-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).
+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.
+The FileDiscard::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.
+If the trash location does not already exist, the FileDiscard::Discarder will not automatically create it. Instead, it will raise a FileDiscard::TrashMissing 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 or make use of FileDiscard.create_trash_when_missing= to enable automatically creating missing trash folders.
 
-For a more complex example, check out the [`FileDiscard::LinuxDiscarder`](lib/file_discard.rb#L144-L164).
+For a more complex example, see FileDiscard::LinuxDiscarder.

data/Rakefile

@@ -1,57 +1,84 @@
 require 'rake'
 require 'rake/testtask'
 require 'rake/clean'
+require 'rdoc/task'
 require 'rubygems/package_task'
 
 task default: :test
 task spec: :test
 task build: :package
 
-PKG_VERSION = '0.1.2'
+PKG_VERSION = '0.1.3'
 NOW = Time.now.utc
 
 # delay updating the version file unless building the gem or package
+VER_FN = 'lib/file_discard_version.rb'
 task :update_version do
-  File.open('lib/file_discard_version.rb','w') do |f|
+  File.open(VER_FN,'w') do |f|
     f.puts <<EOF
 module FileDiscard
+  # :nodoc:
   VERSION = '#{PKG_VERSION}'
+  # :nodoc:
   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
+
+if File.exist? VER_FN
+  task package: :update_version
+  task gem: :update_version
+else
+  Rake::Task[:update_version].execute
+end
 
 Rake::TestTask.new do |t|
   t.pattern = "spec/*_spec.rb"
 end
 
+RDOC_EXTRA_FILES = ['README.md','LICENSE']
+
+RDoc::Task.new :rdoc do |rdoc|
+  rdoc.rdoc_files.include(*RDOC_EXTRA_FILES, 'lib/**/*.rb')
+  rdoc.title    = 'FileDiscard'
+  rdoc.main     = 'README.md'
+  rdoc.rdoc_dir = 'rdoc'
+end
+
 def list_files
   if Dir.exist? '.git'
-    `git ls-files -z`.split("\x0")
+    files = `git ls-files -z`.split("\x0")
   else
     # e.g. when installed and tasks are run from there...
-    Dir.glob('**/*').select{|e| File.file? e}
+    files = Dir.glob('**/*').select{|e| File.file? e}
   end
+  files.delete '.gitignore'
+  files
 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.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.homepage = 'https://github.com/bradrf/file_discard#readme'
+  s.license  = 'MIT'
+
+  s.version = PKG_VERSION
+  s.date    = NOW.strftime('%Y-%m-%d')
+
+  s.required_ruby_version = '>= 1.9.0'
+
   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'
+  s.has_rdoc          = true
+  s.rdoc_options     += ['--title','FileDiscard','--main','README.md']
+  s.extra_rdoc_files += RDOC_EXTRA_FILES
 end
 
 Gem::PackageTask.new(spec) do |pkg|
@@ -64,4 +91,4 @@ task :grip do
   exec 'grip --gfm --context=bradrf/file_discard'
 end
 
-CLOBBER.add 'coverage'
+CLOBBER.include 'coverage', VER_FN

data/bin/discard

@@ -9,6 +9,16 @@ parser  = OptionParser.new do |opts|
   Version = FileDiscard::VERSION
   Release = FileDiscard::RELEASE
 
+  opts.on('-d', '--dir', 'allow empty directories to be discarded') do |v|
+    options.directory = v
+  end
+
+  [?r,?R].each do |o|
+    opts.on("-#{o}", '--recursive', 'allow directories to be discarded recursively') do |v|
+      options.recursive = v
+    end
+  end
+
   opts.on('-v', '--verbose', 'show where files are discarded') do |v|
     options.verbose = v
   end
@@ -25,7 +35,7 @@ parser  = OptionParser.new do |opts|
 
   opts.separator('')
   opts.separator('Options ignored to provide compatibility with "rm":')
-  [?d,?f,?i,?P,?R,?r].each {|a| opts.on("-#{a}")}
+  [?f,?i,?I].each {|o| opts.on("-#{o}")}
 
   opts.banner << ' file ...'
 end

data/lib/file_discard.rb

@@ -30,12 +30,15 @@ module FileDiscard
   ######################################################################
   # Module Methods
 
+  # Extend Ruby's +File+ and +Pathname+ classes with Discarder.discard methods.
   def self.mix_it_in!
     [File, Pathname].each do |klass|
       klass.class_eval do
+        # :nodoc:
         def self.discard(*args)
           FileDiscard.discarder.discard(*args)
         end
+        # :nodoc:
         def discard(options = {})
           FileDiscard.discarder.discard(self, options)
         end
@@ -44,10 +47,12 @@ module FileDiscard
     self
   end
 
+  # See Discarder.discard for usage.
   def self.discard(*args)
     discarder.discard(*args)
   end
 
+  # Set the default discarder to use.
   def self.discarder=(discarder)
     @@discarder = discarder
   end
@@ -62,11 +67,27 @@ module FileDiscard
                     end
   end
 
+  @@create_trash_when_missing = false
+
+  # Enable or disable the automatic creation of trash directories if they do not exist. The default
+  # is to raise a TrashMissing exception).
+  def self.create_trash_when_missing=(value)
+    @@create_trash_when_missing = value
+  end
+
+  def self.create_trash_when_missing
+    @@create_trash_when_missing
+  end
+
   ######################################################################
   # Discarders
 
+  # Raised when the configured trash directory for a given mountpoint does not exist.
+  class TrashMissing < Errno::ENOENT; end;
+
+  # The core logic for moving files to an appropriate trash directory.
   class Discarder
-    SPECIAL_DIRS = ['.','..']
+    SPECIAL_DIRS = ['.','..'] # :nodoc:
 
     def initialize(home, home_trash, mountpoint_trash_fmt)
       home = pathname_for(home).expand_path
@@ -75,13 +96,39 @@ module FileDiscard
       @mountpoint_trash_fmt = mountpoint_trash_fmt
     end
 
-    def discard(obj, move_options = {})
+    # Request that +obj+ be moved to the trash.
+    #
+    # +options+ - a hash of any of the following:
+    # * :directory - allow an empty directory to be discarded
+    # * :recursive - allow a directory to be discarded even if not empty
+    # * :verbose - report the move operation
+    #
+    # May raise:
+    # * Errno::EINVAL - +obj+ is "." or ".." which are not allowed to be discarded
+    # * Errno::EISDIR - +obj+ is a directory
+    # * Errno::ENOTEMPTY - +obj+ is a directory with children
+    # * Errno::ENOENT - +obj+ does not exist on the file system
+    # * TrashMissing - the trash directory for the mountpoint associated with +obj+ did not exist
+    #
+    def discard(obj, 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')
+      if pn.directory?
+        if SPECIAL_DIRS.include?(pn.basename.to_s)
+          raise Errno::EINVAL.new(SPECIAL_DIRS.join(' and ') << ' may not be removed')
+        end
+        unless options[:recursive]
+          raise Errno::EISDIR.new(pn.to_s)    unless options[:directory]
+          raise Errno::ENOTEMPTY.new(pn.to_s) if pn.children.any?
+        end
       end
+
       trash = find_trash_for pn
-      raise Errno::ENOENT.new(trash.to_s) unless trash.exist?
+      unless trash.exist?
+        raise TrashMissing.new(trash.to_s) unless FileDiscard.create_trash_when_missing
+        trash.mkpath
+      end
+
+      move_options = options.has_key?(:verbose) ? {verbose: options[:verbose]} : {}
       move(pn, trash, move_options)
     end
 

data/lib/file_discard_version.rb

@@ -1,4 +1,6 @@
 module FileDiscard
-  VERSION = '0.1.2'
-  RELEASE = '6f7c646:20140606035238'
+  # :nodoc:
+  VERSION = '0.1.3'
+  # :nodoc:
+  RELEASE = '168a436:20140607032530'
 end

data/spec/file_discard_spec.rb

@@ -24,6 +24,7 @@ describe FileDiscard do
 
       @discarder = FileDiscard::OsxDiscarder.new(@home)
       FileDiscard.discarder = @discarder
+      FileDiscard.create_trash_when_missing = false
     end
 
     after do
@@ -49,7 +50,13 @@ describe FileDiscard do
 
       it 'should fail without trash' do
         f = File.new(@base.join('file.txt').to_s, 'w')
-        ->{ f.discard }.must_raise Errno::ENOENT
+        ->{ f.discard }.must_raise FileDiscard::TrashMissing
+      end
+
+      it 'should support creating missing trash' do
+        FileDiscard.create_trash_when_missing = true
+        f = File.new(@base.join('file.txt').to_s, 'w')
+        f.discard
       end
 
       describe 'with trash in the home' do
@@ -62,6 +69,22 @@ describe FileDiscard do
           @trash.children(false).collect(&:to_s).sort
         end
 
+        it 'should conditionally allow removal of empty directories' do
+          d = @base.join('foozy')
+          d.mkdir
+          ->{ FileDiscard.discard(d) }.must_raise Errno::EISDIR
+          FileDiscard.discard(d, directory: true)
+        end
+
+        it 'should conditionally allow removal of non-empty directories' do
+          d = @base.join('foozy')
+          d.mkdir
+          f = d.join('stuff.txt')
+          f.open('w') {|io| io.puts 'stuff'}
+          ->{ FileDiscard.discard(d, directory: true) }.must_raise Errno::ENOTEMPTY
+          FileDiscard.discard(d, recursive: true)
+        end
+
         it 'should discard a file' do
           f = File.new(@base.join('file.txt').to_s, 'w')
           f.discard

metadata

@@ -1,23 +1,24 @@
 --- !ruby/object:Gem::Specification
 name: file_discard
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Brad Robel-Forrest
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-06 00:00:00.000000000 Z
+date: 2014-06-07 00:00:00.000000000 Z
 dependencies: []
-description: Simple helper to move files to the trash folder
+description: Simple helper to move files to the trash folder.
 email: brad+filediscard@gigglewax.com
 executables:
 - discard
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- README.md
+- LICENSE
 files:
-- ".gitignore"
 - LICENSE
 - README.md
 - Rakefile
@@ -30,7 +31,11 @@ licenses:
 - MIT
 metadata: {}
 post_install_message: 
-rdoc_options: []
+rdoc_options:
+- "--title"
+- FileDiscard
+- "--main"
+- README.md
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
@@ -48,6 +53,6 @@ rubyforge_project:
 rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
-summary: Move files to the trash
+summary: Move files to the trash.
 test_files:
 - spec/file_discard_spec.rb

data/.gitignore

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