add `--force` option for `brew cask uninstall`

also update some related docs for verbs `install` and `uninstall`

USAGE.md

@@ -66,6 +66,15 @@ $ brew cask uninstall google-chrome
 This will both uninstall the Cask and remove symlinks which were created in
 `~/Applications`.
 
+To uninstall all versions of a Cask, use `--force`:
+
+```bash
+$ brew cask uninstall --force google-chrome
+```
+
+Note that `uninstall --force` is currently imperfect.  See the man page for
+more information.
+
 ## Other Commands
 
 * `info` -- displays information about the given Cask

doc/src/brew-cask.1.md

@@ -19,10 +19,10 @@ names, and other aspects of this manual are still subject to change.
 
 ## FREQUENTLY USED COMMANDS
 
-  * `install` <Cask>:
+  * `install [--force]` <Cask>:
     Install <Cask>.
 
-  * `uninstall` <Cask>:
+  * `uninstall [--force]` <Cask>:
     Uninstall <Cask>.
 
   * `search` <text> | /<regexp>/:
@@ -74,7 +74,8 @@ names, and other aspects of this manual are still subject to change.
     Display information about <Cask>.
 
   * `install [--force]` <Cask>:
-    Install <Cask>.
+    Install <Cask>.  With `--force`, re-install even if the Cask appears to
+    be already present.
 
     <Cask> is usually the name of a Cask as returned by `brew cask search`,
     but see [OTHER WAYS TO SPECIFY A CASK][] for variations.
@@ -86,8 +87,21 @@ names, and other aspects of this manual are still subject to change.
 
     If <Casks> are given, list the installed files for <Casks>.
 
-  * `uninstall` or `rm` or `remove` <Cask>:
-    Uninstall <Cask>.
+  * `uninstall [--force]` or `rm` or `remove` <Cask>:
+    Uninstall <Cask>.  With `--force`, uninstall even if the Cask does
+    not appear to be present.
+
+    Note that `uninstall --force` is currently imperfect.  It will follow
+    the `uninstall` instructions from *newest* Cask definition, even if
+    the given Cask has changed since you installed it.  The result is that
+    `uninstall --force` will always succeed in removing relevant files
+    under `/opt/homebrew-cask`, but will sometimes fail to remove relevant
+    installed files outside of `/opt/homebrew-cask`.  This issue is being
+    addressed.
+
+    `uninstall` without `--force` is also imperfect.  It may be unable to
+    perform an `uninstall` operation if the given Cask has changed since you
+    installed it.  This issue is being addressed.
 
   * `zap` <Cask>:
     Unconditionally remove _all_ files associated with <Cask>.

lib/cask/cli/uninstall.rb

@@ -2,11 +2,12 @@ class Cask::CLI::Uninstall < Cask::CLI::Base
   def self.run(*args)
     raise CaskUnspecifiedError if args.empty?
     cask_names = args.reject { |a| a.chars.first == '-' }
+    force = args.include? '--force'
     cask_names.each do |cask_name|
       odebug "Uninstalling Cask #{cask_name}"
       cask = Cask.load(cask_name)
-      raise CaskNotInstalledError.new(cask) unless cask.installed?
-      Cask::Installer.new(cask).uninstall
+      raise CaskNotInstalledError.new(cask) unless cask.installed? or force
+      Cask::Installer.new(cask).uninstall(force)
     end
   end
 

lib/cask/installer.rb

@@ -122,10 +122,11 @@ class Cask::Installer
     self.class.print_caveats(@cask)
   end
 
-  def uninstall
+  def uninstall(force=false)
     odebug "Cask::Installer.uninstall"
     uninstall_artifacts
     purge_versioned_files
+    purge_caskroom_path if force
   end
 
   def uninstall_artifacts

test/cask/cli/uninstall_test.rb

@@ -13,6 +13,12 @@ describe Cask::CLI::Uninstall do
     }.must_raise CaskNotInstalledError
   end
 
+  it "tries anyway on a non-present Cask when --force is given" do
+    lambda {
+      Cask::CLI::Uninstall.run('anvil', '--force')
+    } # wont_raise
+  end
+
   it "can uninstall and unlink multiple casks at once" do
     caffeine = Cask.load('local-caffeine')
     transmission = Cask.load('local-transmission')

test/cask/installer_test.rb

@@ -315,5 +315,29 @@ describe Cask::Installer do
       (Cask.caskroom/'local-caffeine'/caffeine.version).wont_be :directory?
       (Cask.caskroom/'local-caffeine').wont_be :directory?
     end
+
+    it "uninstalls all versions if force is set" do
+      caffeine = Cask.load('local-caffeine')
+      installer = Cask::Installer.new(caffeine)
+      mutated_version = caffeine.version + '.1'
+
+      shutup do
+        installer.install
+      end
+
+      (Cask.caskroom/'local-caffeine'/caffeine.version).must_be :directory?
+      (Cask.caskroom/'local-caffeine'/mutated_version).wont_be  :directory?
+      FileUtils.mv(Cask.caskroom/'local-caffeine'/caffeine.version, Cask.caskroom/'local-caffeine'/mutated_version)
+      (Cask.caskroom/'local-caffeine'/caffeine.version).wont_be :directory?
+      (Cask.caskroom/'local-caffeine'/mutated_version).must_be  :directory?
+
+      shutup do
+        installer.uninstall(true)
+      end
+
+      (Cask.caskroom/'local-caffeine'/caffeine.version).wont_be :directory?
+      (Cask.caskroom/'local-caffeine'/mutated_version).wont_be  :directory?
+      (Cask.caskroom/'local-caffeine').wont_be :directory?
+    end
   end
 end