must_be 1.0.0

data/spec/must_be/proxy_spec.rb

@@ -0,0 +1,194 @@
+require 'spec_helper'
+
+describe MustBe do
+  include MustBeExampleHelper
+  
+  describe Proxy do
+    subject { Proxy.new(:moxie) }
+    
+    context "when initialized with method other than :must or :must_not" do
+      it "should raise ArgumentError" do
+        expect do
+          Proxy.new(:moxie, :must_could)
+        end.should raise_error(ArgumentError,
+          "assertion (:must_could) must be :must or :must_not")
+      end
+    end
+    
+    describe "it should not forward" do
+      example "#__id__" do
+        subject.__id__.should_not == :moxie.__id__
+      end
+      
+      example "#object_id" do
+        subject.object_id.should_not == :moxie.object_id
+      end
+    end
+  end
+  
+  module ItShouldNotifyExpectations
+    def it_should_notify(message, &implementation)
+      example "#{message} should notify" do
+        instance_eval &implementation
+        should notify(message)
+      end
+    end
+  
+    def it_should_not_notify(message, &implementation)
+      example "#{message} should not notify" do
+        instance_eval &implementation
+        should_not notify
+      end
+    end
+  end
+  
+  describe '#must' do
+    extend ItShouldNotifyExpectations
+    
+    context "when called with a block" do
+      it "should return the receiver" do
+        0xdad.must{}.object_id.should == 0xdad.object_id
+      end
+      
+      it "should notify if block returns false" do
+        :helm.must{|receiver| receiver == :harm }.should == :helm
+        should notify(":helm.must {}")
+      end
+      
+      it "should notify with message if provided" do
+        :ice.must("ice must be icy") do |receiver|
+          receiver == :icy
+        end.should == :ice
+        should notify("ice must be icy")
+      end
+      
+      it "should not notify if block returns true" do
+        :jinn.must{|receiver| receiver == :jinn }.should == :jinn
+        should_not notify
+      end
+      
+      it "should allow nested #must_notify" do
+        :keys.must("electrify kites") do |receiver, message|
+          must_notify("#{receiver} must #{message}")
+          true
+        end.should == :keys
+        should notify("keys must electrify kites")
+      end
+    end
+    
+    context "when used to proxy" do
+      subject { 230579.must }
+      
+      it_should_notify("230579.must.==(70581)") do
+        subject == 70581
+      end
+        
+      it_should_not_notify("230579.must.>(411)") do
+        subject > 411
+      end
+      
+      it_should_not_notify("230579.must.odd?") do
+        subject.odd?
+      end
+      
+      it_should_notify("230579.must.between?(-4, 4)") do
+        subject.between?(-4, 4)
+      end
+      
+      it_should_notify("230579.must.respond_to?(:finite?)") do
+        subject.respond_to? :finite?
+      end
+      
+      it_should_not_notify("230579.must.instance_of?(Fixnum)") do
+        subject.instance_of? Fixnum
+      end
+      
+      it_should_notify("230579.must.instance_of?(Integer)") do
+        subject.instance_of? Integer
+      end
+      
+      it "should have a different #object_id" do
+        subject.should == 230579
+        subject.object_id.should_not == 230579.object_id
+      end
+      
+      context "after MustBe.disable" do
+        before_disable_after_enable
+        
+        it "should have the same #object_id" do
+          subject.object_id.should == 230579.object_id
+        end
+      end
+    end
+  end
+  
+  describe '#must_not' do
+    extend ItShouldNotifyExpectations
+        
+    context "when called with a block" do
+      it "should return the receiver" do
+        0xdad.must_not{}.should == 0xdad
+      end
+      
+      it "should notify if block returns true" do
+        :helm.must_not{|receiver| receiver == :helm }.should == :helm
+        should notify(":helm.must_not {}")
+      end
+      
+      it "should notify with message if provided" do
+        :ice.must_not("ice must not be ice") do |receiver|
+          receiver == :ice
+        end.should == :ice
+        should notify("ice must not be ice")
+      end
+      
+      it "should not notify if block returns false" do
+        :jinn.must_not{|receiver| receiver == :gem }.should == :jinn
+        should_not notify
+      end
+      
+      it "should allow nested #must_notify" do
+        :keys.must_not("electrify kites") do |receiver, message|
+          must_notify("#{receiver} must not #{message}")
+          false
+        end.should == :keys
+        should notify("keys must not electrify kites")
+      end
+    end
+    
+    context "when used to proxy" do
+      subject { 230579.must_not }
+      
+      it_should_not_notify("230579.must_not.==(70581)") do
+        subject == 70581
+      end
+        
+      it_should_notify("230579.must_not.>(411)") do
+        subject > 411
+      end
+      
+      it_should_notify("230579.must_not.odd?") do
+        subject.odd?
+      end
+      
+      it_should_not_notify("230579.must_not.between?(-4, 4)") do
+        subject.between?(-4, 4)
+      end
+      
+      it_should_not_notify(
+          "230579.must_not.respond_to?(:finite?)") do
+        subject.respond_to? :finite?
+      end
+      
+      it_should_notify("230579.must_not.instance_of?(Fixnum)") do
+        subject.instance_of? Fixnum
+      end
+      
+      it_should_not_notify(
+          "230579.must_not.instance_of?(Integer)") do
+        subject.instance_of? Integer
+      end
+    end
+  end
+  
+end

data/spec/notify_matcher_spec.rb

@@ -0,0 +1,59 @@
+require 'spec_helper'
+
+# Since the notify matcher has lots of cases, we should spec out each
+# possible combination to make sure it has the expected behavior.
+#
+# Patterns are built by choosing:
+#   Whether there is a note:
+#     :note
+#     :no_note
+#   Polarity of the expectation:
+#     :should
+#     :should_not
+#   Message argument of notify matcher:
+#     nil
+#     'same'
+#     'different'
+#
+describe "Notify Matcher" do
+  include MustBeExampleHelper
+  
+  def self.it_should_follow_pattern(note, polarity, message, result)      
+    context "when there is #{note == :note ? "a" : "no"} note" do
+      message_arg = message ? %{("#{message}")} : ""
+      call = "#{polarity} notify#{message_arg}"
+      it "should #{result ? "fail" : "succeed"} if expecting #{call}" do
+        pattern_notify = lambda do
+          must_notify("same") if note == :note
+          send(polarity, notify(message))
+        end
+      
+        pattern_notify.send(result ? :should : :should_not, raise_error(
+          Spec::Expectations::ExpectationNotMetError, result))
+      end
+    end
+  end
+
+  it_should_follow_pattern :note, :should, nil, nil
+  it_should_follow_pattern :note, :should, 'same', nil
+  it_should_follow_pattern :note, :should, 'different',
+    'expected note with message: "different"' "\n"\
+    '     got note with message: "same"'
+  it_should_follow_pattern :note, :should_not, nil,
+    'expected no note' "\n"\
+    'got note with message: "same"'
+  it_should_follow_pattern :note, :should_not, 'same',
+    'did NOT expect note with message: "same"' "\n"\
+    '           got note with message: "same"'
+  it_should_follow_pattern :note, :should_not, 'different', nil
+
+  it_should_follow_pattern :no_note, :should, nil,
+    'expected a note'
+  it_should_follow_pattern :no_note, :should, 'same',
+    'expected a note with message: "same"'
+  it_should_follow_pattern :no_note, :should, 'different',
+    'expected a note with message: "different"'
+  it_should_follow_pattern :no_note, :should_not, nil, nil
+  it_should_follow_pattern :no_note, :should_not, 'same', nil
+  it_should_follow_pattern :no_note, :should_not, 'different', nil
+end

data/spec/spec_helper.rb

@@ -0,0 +1,180 @@
+### MUST_BE__DO_NOT_AUTOMATICALLY_INCLUDE_IN_OBJECT ###
+#
+# Hard to describe within normal RSpec control flow.  Instead we raise a
+# RuntimeError if MUST_BE__DO_NOT_AUTOMATICALLY_INCLUDE_IN_OBJECT doesn't
+# behave as expected.
+#
+
+ENV['MUST_BE__NOTIFIER'] = nil # to make `rake spec` work.
+ENV['MUST_BE__DO_NOT_AUTOMATICALLY_INCLUDE_IN_OBJECT'] = "" # any string.
+
+require 'lib/must_be'
+
+if Object.include? MustBe
+  raise "MustBe should not be automatically included in Object."
+end
+
+def expect_error(error_type)
+  begin
+    raised_error = false
+    yield
+  rescue error_type
+    raised_error = true
+  end
+  raise "expected #{error_type}" unless raised_error
+end
+
+# Show that MustBe does not need to be included in Object to be useful.
+def example_of_must_be_inclusion
+  example = Object.new
+  example.extend(MustBe)
+  example.must == example
+  example.must_not_be_nil
+
+  # must_only_contain and must_not_contain require contents to also include
+  # MustBe.
+  contents = Object.new
+
+  container = [contents]
+  container.extend(MustBe)
+
+  expect_error(NoMethodError) do
+    container.must_only_contain
+  end
+
+  contents.extend(MustBe)
+  expect_error(MustBe::Note) do
+    container.must_not_contain
+  end
+end
+example_of_must_be_inclusion
+
+class Object
+  include MustBe
+end
+
+### MustBeExampleHelper ###
+
+module MustBeExampleHelper
+  
+  $default_must_be_notifier = MustBe.notifier
+  
+  def self.included(example_group)
+    example_group.before do
+      MustBe.notifier = lambda do |note|
+        @note = note
+        false
+      end
+    end
+
+    class <<example_group
+      
+      ### Value Assertion ###
+      
+      def it_should_have_must_be_value_assertion(method, value, alt = 411)
+        describe '##{method}' do
+          it "should not notify if receiver is #{value.inspect}" do
+            value.send(method).should == value
+            should_not notify
+          end
+
+          it "should notify if receiver is not #{value.inspect}" do
+            alt.send(method).should == alt
+            should notify("#{alt.inspect}.#{method}")
+          end
+        end
+      end
+
+      def it_should_have_must_not_be_value_assertion(method, value, alt = 411)
+        describe '##{method}' do
+          it "should notify if receiver is #{value.inspect}" do
+            value.send(method)
+            should notify("#{value.inspect}.#{method}")
+          end
+
+          it "should not notify if receiver is not #{value.inspect}" do
+            alt.send(method)
+            should_not notify
+          end
+        end
+      end
+    
+      ### Notify Example ###
+
+      def notify_example(expression, message = nil)
+        expression = expression.gsub(/\n\s*/, " ")
+        if message.is_a? Module
+          message = expression+", but matches #{message}"
+        end
+        example "#{expression} should #{message ? "" : "not "}notify" do
+          eval(expression)
+          if message == true
+            should notify
+          elsif message
+            should notify(message)
+          else
+            should_not notify
+          end
+        end
+      end
+      
+      ### Enable ###
+      
+      def before_disable_after_enable
+        before do
+          MustBe.disable
+        end
+        
+        after do
+          MustBe.enable
+        end
+      end
+      
+      def before_disable_and_reenable
+        before do
+         MustBe.disable
+         MustBe.enable
+        end
+      end
+    end
+  end
+  
+  ### Notify Matcher ###
+  
+  def notify(message = nil)
+    simple_matcher do |given, matcher|
+      result, message =
+        if @note
+          if message
+            if message === @note.message
+              [true,
+                "did NOT expect note with message: #{message.inspect}\n"\
+                "           got note with message: #{@note.message.inspect}"]
+            else
+              [false,
+                "expected note with message: #{message.inspect}\n"\
+                "     got note with message: #{@note.message.inspect}"]
+            end
+          else
+            [true,
+              "expected no note\n"\
+              "got note with message: #{@note.message.inspect}"]
+          end
+        else
+          [false, if message
+            "expected a note with message: #{message.inspect}"
+          else
+            "expected a note"
+          end]
+        end
+    
+      if result
+        matcher.negative_failure_message = message
+      else
+        matcher.failure_message = message
+      end
+    
+      result
+    end
+  end
+end

data/spec/typical_usage_spec.rb

@@ -0,0 +1,176 @@
+require 'spec_helper'
+
+describe MustBe, " typical usage" do
+  include MustBeExampleHelper
+  
+  describe '#must_be', " notifies when receiver doesn't case-equal (===) any"\
+      " of its arguments" do
+    context "when called with a Class, it notifies unless"\
+        " receiver.is_a? Class" do
+      notify_example %{4.must_be(Numeric)}
+      notify_example %{4.must_be(Float)}, Fixnum
+    end
+    
+    context "when called with a regexp, it notifies unless"\
+        " regexp =~ receiver" do
+      notify_example %{"funny".must_be(/n{2}/)}
+      notify_example %{"funny".must_be(/\d/)}, String
+    end
+    
+    context "when called with a range, it notifies unless"\
+        " range.include? receiver" do
+      notify_example %{5.must_be(1..5)}
+      notify_example %{5.must_be(1...5)}, Fixnum
+    end
+    
+    context "when called with an array, it notifies unless"\
+        " array == receiver" do
+      notify_example %{[3, 5].must_be([3, 5])}
+      notify_example %{3.must_be([3, 5])}, Fixnum
+    end
+    
+    context "when called with a proc, it notifies unless proc[receiver]" do
+      notify_example %{:anything.must_be(lambda {|v| true })}
+      notify_example %{:anything.must_be(lambda {|v| false })}, true
+    end
+    
+    context "when called with most other objects, it notifies unless"\
+        " object == receiver" do
+      notify_example %{:yep.must_be(:yep)}
+      notify_example %{:yep.must_be(:nope)}, Symbol
+    end
+    
+    context "when called without arguments, it notifies if receiver is"\
+        " false or nil" do
+      notify_example %{5.must_be}
+      notify_example %{nil.must_be}, NilClass
+      notify_example %{false.must_be}, FalseClass
+    end
+    
+    context "when called with multiple arguments, it notifies unless"\
+        " receiver case-equals (===) one of them" do
+      notify_example %{:happy.must_be(String, Symbol)}
+      notify_example %{934.must_be(String, Symbol)}, Fixnum
+    end
+  end
+  
+  describe '#must' do
+    context "when called with a block, it notifies if the result is"\
+        " false or nil" do
+      notify_example %{:helm.must("message") {|receiver, message| message ==
+        "mess" }}, "message"
+      notify_example %{:helm.must {|receiver| receiver == :helm }}
+    end
+    
+    context "when called with no argument, it returns a proxy which notifies"\
+        " when a method returning false or nil is called" do
+      notify_example %{5.must == 4}, "5.must.==(4)"
+      notify_example %{5.must > 4}
+    end
+  end
+  
+  describe '#must_only_contain' do
+    context "with Array receiver, it should notify unless each member in the"\
+        " array case-equals (===) one of the arguments" do
+      notify_example %{[1, :hi, "wow"].must_only_contain(Numeric, Symbol,
+        String)}
+      notify_example %{[1, :hi, "wow"].must_only_contain(Numeric, String)},
+        "must_only_contain: :hi.must_be(Numeric, String), but matches"\
+        " Symbol in container [1, :hi, \"wow\"]"
+    end
+    
+    context "with Hash receiver, it should notify unless each pair"\
+        " case-equals (===) a pair in an argument hash" do
+      notify_example %{{:key => "value"}.must_only_contain({Symbol => [Symbol,
+        String]})}
+      notify_example %{{:key => "value"}.must_only_contain({Symbol => Symbol},
+        {Symbol => Numeric})}, "must_only_contain: pair {:key=>\"value\"}"\
+          " does not match [{Symbol=>Symbol}, {Symbol=>Numeric}] in"\
+          " container {:key=>\"value\"}"
+    end
+  end
+  
+  describe '#must_only_ever_contain' do
+    context "like #must_only_contain, it notifies unless each member"\
+        " case-equals (===) one of the arguments" do
+      notify_example %{[1, :hi, "wow"].must_only_ever_contain(Numeric, Symbol,
+        String)}
+      notify_example %{[1, :hi, "wow"].must_only_ever_contain(Numeric, 
+          String)},
+        "must_only_ever_contain: :hi.must_be(Numeric, String), but"\
+        " matches Symbol in container [1, :hi, \"wow\"]"
+    end
+    
+    context "it notifies whenever the container is updated to hold an member"\
+        " which does not case-equal (===) one of the arguments" do
+      describe "[1, 2, 3].must_only_ever_contain(Numeric)" do
+        subject { [1, 2, 3].must_only_ever_contain(Numeric) }
+        
+        notify_example %{subject << 3.14}
+        notify_example %{subject << nil}, "must_only_ever_contain:"\
+          " Array#<<(nil): nil.must_be(Numeric), but matches NilClass in"\
+          " container [1, 2, 3, nil]"
+      end
+    end
+  end
+  
+  describe '#must_notify', " is a primitive used to define other must_be"\
+      " methods" do
+    context "when called with a string, it notifies with a string message" do
+      notify_example %{must_notify("message")}, "message"
+    end
+    
+    context "when called with multiple arguments, it notifies with method"\
+        " invocation details" do
+      notify_example %{must_notify(:receiver, :method_name,
+          [:arg, :arg, :arg], lambda {}, " additional message")},
+        ":receiver.method_name(:arg, :arg, :arg) {} additional message"
+    end
+  end
+  
+  describe '#must_check', " interrupts normal notification" do
+    context "when called with a block, it yields to the block" do
+      example "#must_check returns a note if the block calls #must_notify" do
+        note = must_check do
+          must_notify("message")
+        end
+        note.message.should == "message"
+        should_not notify
+      end
+      
+      example "#must_check returns nil if the block does not call"\
+          " #must_notify" do
+        note = must_check do
+          :would_not_notify
+        end
+        note.should be_nil
+        should_not notify
+      end
+    end
+    
+    context "when called with a proc and a block, #must_check calls the"\
+        " proc" do
+      example "#must_check passes the note to the block and notifies with"\
+          " the result of the block if the proc calls #must_notify" do
+        must_check(lambda do
+          must_notify("original message")
+        end) do |note|
+          note.message.should == "original message"
+          "new message"
+        end
+        should notify("new message")
+      end
+      
+      example "the block is not called if the proc does not call"\
+          " #must_notify" do
+        did_call_block = false
+        must_check(lambda do
+          :would_not_notify
+        end) do |note|
+          did_call_block = true
+        end
+        did_call_block.should be_false
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification 
+name: must_be
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- William Taysom
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-09-12 00:00:00 +08:00
+default_executable: 
+dependencies: []
+
+description: must_be provides runtime assertions which can easily be disabled in production environments.  Likewise, the notifier can be customized to raise errors, log failure, enter the debugger, or anything else.
+email: wtaysom@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+files: 
+- .gitignore
+- README.md
+- Rakefile
+- VERSION
+- doc/readme/examples.rb
+- doc/readme/run_examples.rb
+- lib/must_be.rb
+- lib/must_be/attr_typed.rb
+- lib/must_be/basic.rb
+- lib/must_be/containers.rb
+- lib/must_be/containers_registered_classes.rb
+- lib/must_be/core.rb
+- lib/must_be/nonstandard_control_flow.rb
+- lib/must_be/proxy.rb
+- must_be.gemspec
+- spec/must_be/attr_typed_spec.rb
+- spec/must_be/basic_spec.rb
+- spec/must_be/containers_spec.rb
+- spec/must_be/core_spec.rb
+- spec/must_be/nonstandard_control_flow_spec.rb
+- spec/must_be/proxy_spec.rb
+- spec/notify_matcher_spec.rb
+- spec/spec_helper.rb
+- spec/typical_usage_spec.rb
+has_rdoc: true
+homepage: http://github.com/wtaysom/must_be
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: must_be Runtime Assertions
+test_files: 
+- spec/must_be/attr_typed_spec.rb
+- spec/must_be/basic_spec.rb
+- spec/must_be/containers_spec.rb
+- spec/must_be/core_spec.rb
+- spec/must_be/nonstandard_control_flow_spec.rb
+- spec/must_be/proxy_spec.rb
+- spec/notify_matcher_spec.rb
+- spec/spec_helper.rb
+- spec/typical_usage_spec.rb