Merge pull request #11408 from carlocab/s/reason/requirement

formula: tweak preset `pour_bottle?` symbols

Library/Homebrew/formula.rb

@@ -2920,16 +2920,16 @@ class Formula
     # the {Formula} will be built from source and `reason` will be printed.
     #
     # Alternatively, a preset reason can be passed as a symbol:
-    # <pre>pour_bottle? reason: :clt_required</pre>
+    # <pre>pour_bottle? only_if: :clt_installed</pre>
-    def pour_bottle?(reason: nil, &block)
+    def pour_bottle?(only_if: nil, &block)
       @pour_bottle_check = PourBottleCheck.new(self)
 
-      if reason.present? && block.present?
+      if only_if.present? && block.present?
-        raise ArgumentError, "Do not pass both a reason and a block to `pour_bottle?`"
+        raise ArgumentError, "Do not pass both a preset condition and a block to `pour_bottle?`"
       end
 
-      block ||= case reason
+      block ||= case only_if
-      when :clt_required
+      when :clt_installed
         lambda do |_|
           on_macos do
             T.cast(self, PourBottleCheck).reason(+<<~EOS)
@@ -2941,7 +2941,7 @@ class Formula
           end
         end
       else
-        raise ArgumentError, "Invalid `pour_bottle?` reason" if reason.present?
+        raise ArgumentError, "Invalid preset `pour_bottle?` condition" if only_if.present?
       end
 
       @pour_bottle_check.instance_eval(&block)

Library/Homebrew/test/formula_spec.rb

@@ -996,37 +996,37 @@ describe Formula do
       expect(f).to pour_bottle
     end
 
-    it "returns false with `reason: :clt_required` on macOS", :needs_macos do
+    it "returns false with `only_if: :clt_installed` on macOS", :needs_macos do
       # Pretend CLT is not installed
       allow(MacOS::CLT).to receive(:installed?).and_return(false)
 
       f = formula "foo" do
         url "foo-1.0"
 
-        pour_bottle? reason: :clt_required
+        pour_bottle? only_if: :clt_installed
       end
 
       expect(f).not_to pour_bottle
     end
 
-    it "returns true with `reason: :clt_required` on macOS", :needs_macos do
+    it "returns true with `only_if: :clt_installed` on macOS", :needs_macos do
       # Pretend CLT is installed
       allow(MacOS::CLT).to receive(:installed?).and_return(true)
 
       f = formula "foo" do
         url "foo-1.0"
 
-        pour_bottle? reason: :clt_required
+        pour_bottle? only_if: :clt_installed
       end
 
       expect(f).to pour_bottle
     end
 
-    it "returns true with `reason: :clt_required` on Linux", :needs_linux do
+    it "returns true with `only_if: :clt_installed` on Linux", :needs_linux do
       f = formula "foo" do
         url "foo-1.0"
 
-        pour_bottle? reason: :clt_required
+        pour_bottle? only_if: :clt_installed
       end
 
       expect(f).to pour_bottle
@@ -1037,12 +1037,12 @@ describe Formula do
         formula "foo" do
           url "foo-1.0"
 
-          pour_bottle? reason: :clt_required do
+          pour_bottle? only_if: :clt_installed do
             reason "true reason"
             satisfy { true }
           end
         end
-      end.to raise_error(ArgumentError, "Do not pass both a reason and a block to `pour_bottle?`")
+      end.to raise_error(ArgumentError, "Do not pass both a preset condition and a block to `pour_bottle?`")
     end
 
     it "throws an error if passed an invalid symbol" do
@@ -1050,9 +1050,9 @@ describe Formula do
         formula "foo" do
           url "foo-1.0"
 
-          pour_bottle? reason: :foo
+          pour_bottle? only_if: :foo
         end
-      end.to raise_error(ArgumentError, "Invalid `pour_bottle?` reason")
+      end.to raise_error(ArgumentError, "Invalid preset `pour_bottle?` condition")
     end
   end
 

docs/Bottles.md

@@ -68,7 +68,13 @@ A full example:
 
 ```ruby
 pour_bottle? do
-  reason "The bottle needs the Xcode CLT to be installed."
+  reason "The bottle needs to be installed into #{Homebrew::DEFAULT_PREFIX}."
-  satisfy { MacOS::CLT.installed? }
+  satisfy { HOMEBREW_PREFIX.to_s == Homebrew::DEFAULT_PREFIX }
 end
 ```
+
+Commonly used `pour_bottle?` conditions can be added as preset symbols to the `pour_bottle?` method, allowing them to be specified like this:
+
+```ruby
+pour_bottle? only_if: :clt_installed
+```