DSL: add stanza stage_only (new caskroom_only)

`caskroom_only` was never documented.  Its original purpose was
obsoleted in #4865, and its use has been recently been reduced to
two Casks.

This PR
* continues the rationalization of naming by changing `caskroom_only`
  to `stage_only`. "stage" is the verb for "make a copy under the
  caskroom directory"
* documents `stage_only`
* adds tests for `stage_only`
* validates the argument to `stage_only`
* gives sensible output in `brew cask info` for `stage_only` Casks
* enforces that `stage_only` cannot coexist with any activatable
  artifacts

`caskroom_only` is still supported for backward compatibility,
but should be removed before 0.50.0.

doc/CASK_LANGUAGE_REFERENCE.md

@@ -119,6 +119,7 @@ Each Cask must declare one or more *artifacts* (i.e. something to install)
 | `container :type =>`   | no                            | a symbol to override container-type autodetect. may be one of: `:air`, `:bz2`, `:cab`, `:dmg`, `:generic_unar`, `:gzip`, `:otf`, `:pkg`, `:rar`, `:seven_zip`, `:sit`, `:tar`, `:ttf`, `:xar`, `:zip`, `:naked`.  (example [parse.rb](../Casks/parse.rb))
 | `tags`                 | no                            | a list of key-value pairs for Cask annotation.  Not free-form.  (see also [Tags Stanza Details](#tags-stanza-details))
 | `gpg`                  | no                            | *stub: not yet functional.*  (see also [GPG Stanza Details](#gpg-stanza-details))
+| `stage_only`           | no                            | `true`.  Assert that the Cask contains no activatable artifacts.
 
 
 ## Legacy Stanzas
@@ -136,6 +137,7 @@ The following stanzas are no longer in use.
 | `install`                 | an obsolete alternative to `pkg`
 | `link`                    | an obsolete alternative to `artifact`
 | `no_checksum`             | an obsolete alternative to `sha256 :no_check`
+| `caskroom_only`           | an obsolete alternative to `stage_only`
 
 
 ## Legacy Forms

doc/cask_language_deltas.md

@@ -50,6 +50,7 @@ This notice will be removed for the final form.**
  * `installer :script`
  * `license`
  * `suite`
+ * `stage_only`
  * `tags`
  * `uninstall :rmdir`
  * `uninstall :trash`

lib/cask/artifact.rb

@@ -20,7 +20,7 @@ module Cask::Artifact; end
 require 'cask/artifact/widget'
 require 'cask/artifact/service'
 require 'cask/artifact/suite'
-require 'cask/artifact/caskroom_only'
+require 'cask/artifact/stage_only'
 require 'cask/artifact/input_method'
 require 'cask/artifact/internet_plugin'
 require 'cask/artifact/screen_saver'
@@ -46,7 +46,7 @@ def self.artifacts
       Cask::Artifact::Font,
       Cask::Artifact::Widget,
       Cask::Artifact::Service,
-      Cask::Artifact::CaskroomOnly,
+      Cask::Artifact::StageOnly,
       Cask::Artifact::Binary,
       Cask::Artifact::InputMethod,
       Cask::Artifact::InternetPlugin,

lib/cask/artifact/caskroom_only.rb → lib/cask/artifact/stage_only.rb

@@ -1,6 +1,6 @@
-class Cask::Artifact::CaskroomOnly < Cask::Artifact::Base
+class Cask::Artifact::StageOnly < Cask::Artifact::Base
   def self.artifact_dsl_key
-    :caskroom_only
+    :stage_only
   end
 
   def install_phase

lib/cask/cli/info.rb

@@ -56,7 +56,8 @@ def self.artifact_info(cask)
       if cask.artifacts[type].length > 0
         retval = "#{Tty.blue}==>#{Tty.white} Contents#{Tty.reset}\n" unless retval.length > 0
         cask.artifacts[type].each do |artifact|
-          retval.concat "  #{artifact.first} (#{type.to_s})\n"
+          activatable_item = type == :stage_only ? '<none>' : artifact.first
+          retval.concat "  #{activatable_item} (#{type.to_s})\n"
         end
       end
     end

lib/cask/cli/internal_stanza.rb

@@ -36,7 +36,7 @@ class Cask::CLI::InternalStanza < Cask::CLI::InternalUseBase
                        :internet_plugin,
                        :screen_saver,
                        :pkg,
-                       :caskroom_only,
+                       :stage_only,
                        :nested_container,
                        :uninstall,
                        :postflight,

lib/cask/dsl.rb

@@ -225,15 +225,50 @@ def self.ordinary_artifact_types
                                      :internet_plugin,
                                      :screen_saver,
                                      :pkg,
+                                     :stage_only,
                                     ]
     end
 
-    installable_artifact_types = ordinary_artifact_types
-    installable_artifact_types.push :caskroom_only
+    def self.activatable_artifact_types
+      @@activatable_artifact_types ||= [:installer, *ordinary_artifact_types] - [:stage_only]
+    end
 
-    installable_artifact_types.each do |type|
+    ordinary_artifact_types.each do |type|
       define_method(type) do |*args|
+        if type == :stage_only and args != [true]
+          raise CaskInvalidError.new(self.title, "'stage_only' takes a single argument: true")
+        end
         artifacts[type] << args
+        if artifacts.key?(:stage_only) and
+          artifacts.keys.count > 1 and
+          ! (artifacts.keys & Cask::DSL::ClassMethods.activatable_artifact_types).empty?
+          raise CaskInvalidError.new(self.title, "'stage_only' must be the only activatable artifact")
+        end
+      end
+    end
+
+    # todo transitional removeme
+    define_method(:caskroom_only) do |*args|
+      if args != [true]
+        raise CaskInvalidError.new(self.title, "'caskroom_only' takes a single argument: true")
+      end
+      artifacts[:stage_only] << args
+      if artifacts.key?(:stage_only) and
+        artifacts.keys.count > 1 and
+        ! (artifacts.keys & Cask::DSL::ClassMethods.activatable_artifact_types).empty?
+        raise CaskInvalidError.new(self.title, "'caskroom_only' must be the only activatable artifact")
+      end
+    end
+
+    def installer(*args)
+      if args.empty?
+        return artifacts[:installer]
+      end
+      begin
+        artifacts[:installer] << Cask::DSL::Installer.new(*args)
+        raise "'stage_only' must be the only activatable artifact" if artifacts.key?(:stage_only)
+      rescue StandardError => e
+        raise CaskInvalidError.new(self.title, e)
       end
     end
 
@@ -262,17 +297,6 @@ def self.ordinary_artifact_types
       end
     end
 
-    def installer(*args)
-      if args.empty?
-        return artifacts[:installer]
-      end
-      begin
-        artifacts[:installer] << Cask::DSL::Installer.new(*args)
-      rescue StandardError => e
-        raise CaskInvalidError.new(self.title, e)
-      end
-    end
-
     attr_reader :sums
 
     def hash_name(hash_type)

test/cask/dsl_test.rb

@@ -295,4 +295,18 @@ def caveats; <<-EOS.undent
       }.must_raise(CaskInvalidError)
     end
   end
+
+  describe "stage_only stanza" do
+    it "allows stage_only stanza to be specified" do
+      cask = Cask.load('stage-only')
+      cask.artifacts[:stage_only].first.must_equal [true]
+    end
+
+    it "prevents specifying stage_only with other activatables" do
+      err = lambda {
+        invalid_cask = Cask.load('invalid/invalid-stage-only-conflict')
+      }.must_raise(CaskInvalidError)
+      err.message.must_include "'stage_only' must be the only activatable artifact"
+    end
+  end
 end

test/support/Casks/invalid/invalid-stage-only-conflict.rb

@@ -0,0 +1,10 @@
+class InvalidStageOnlyConflict < TestCask
+  version '2.61'
+  sha256 'd26d7481cf1229f879c05e11cbdf440d99db6d6342f26c73d8ba7861b975532f'
+
+  url TestHelper.local_binary_url('transmission-2.61.dmg')
+  homepage 'http://example.com/invalid-stage-only-conflict'
+
+  stage_only true
+  app 'Transmission.app'
+end

test/support/Casks/stage-only.rb

@@ -0,0 +1,9 @@
+class StageOnly < TestCask
+  version '2.61'
+  sha256 'd26d7481cf1229f879c05e11cbdf440d99db6d6342f26c73d8ba7861b975532f'
+
+  url TestHelper.local_binary_url('transmission-2.61.dmg')
+  homepage 'http://example.com/stage-only'
+
+  stage_only true
+end