must_be 1.0.0

data/lib/must_be/core.rb

@@ -0,0 +1,247 @@
+module MustBe
+  
+  ### Short Inspect ###
+  
+  SHORT_INSPECT_CUTOFF_LENGTH = 200
+  SHORT_INSPECT_WORD_BREAK_LENGTH = 20
+  SHORT_INSPECT_ELLIPSES = "..."
+
+  def self.short_inspect(obj)
+    s = obj.inspect
+    if s.bytesize > SHORT_INSPECT_CUTOFF_LENGTH
+      real_cutoff = SHORT_INSPECT_CUTOFF_LENGTH - SHORT_INSPECT_ELLIPSES.length
+      left_side = (real_cutoff + 1) / 2
+      right_side = -(real_cutoff / 2)
+      
+      left_start = left_side - SHORT_INSPECT_WORD_BREAK_LENGTH
+      left_word_break_area = s[left_start, SHORT_INSPECT_WORD_BREAK_LENGTH]
+      left_word_break = left_word_break_area.rindex(/\b\s/)
+      start = left_word_break ? left_start + left_word_break + 1 : left_side
+      
+      right_start = right_side
+      right_word_break_area = s[right_start, SHORT_INSPECT_WORD_BREAK_LENGTH]
+      right_word_break = right_word_break_area.index(/\s\b/)
+      stop = right_word_break ? right_start + right_word_break : right_side
+      
+      s[start...stop] = SHORT_INSPECT_ELLIPSES
+    end
+    s
+  end
+  
+  ### Enable ###
+  
+  @@disabled_method_for_method = Hash.new(:must_just_return)
+  @@disabled_handlers = []
+  
+  class <<self
+    def disable
+      return unless enabled?
+      
+      @disabled_methods = instance_methods.map do |method_name|
+        method_name = method_name.to_sym
+        method = instance_method(method_name)
+        disabled_method_name = @@disabled_method_for_method[method_name]
+        alias_method method_name, disabled_method_name
+        [method_name, method]
+      end
+      invoke_disabled_handlers
+    end
+    
+    def enable
+      return if enabled?
+      
+      @disabled_methods.each do |method_record|
+        define_method(*method_record)
+      end
+      @disabled_methods = nil
+      invoke_disabled_handlers
+    end
+    
+    def enabled?
+      @disabled_methods.nil?
+    end
+    
+    def register_disabled_method(method_name,
+        disabled_method_name = method_name)
+      @@disabled_method_for_method[method_name.to_sym] = 
+        disabled_method_name.to_sym
+    end
+    
+    def register_disabled_handler(&handler)
+      @@disabled_handlers << handler
+      handler[enabled?] unless enabled?
+    end
+    
+  private
+    
+    def invoke_disabled_handlers
+      @@disabled_handlers.each {|handler| handler[enabled?] }
+    end
+  end
+  
+  def must_just_return(*args)
+    self
+  end
+  
+  register_disabled_method(:must_just_return)
+  
+  def must_just_yield(*args)
+    yield
+  end
+  
+  register_disabled_method(:must_just_yield)
+  
+  ### Notifiers ###
+  
+  NOTIFIERS = {}
+  
+  class <<self
+    attr_accessor :notifier # should respond_to? :call with Note argument.
+    
+    def def_notifier(constant_name, key = nil, &notifier)
+      const_set(constant_name, notifier)
+      NOTIFIERS[key] = constant_name if key
+    end
+    
+    def set_notifier_from_env(key = ENV['MUST_BE__NOTIFIER'])
+      key = key.to_sym
+      
+      if key == :disable
+        disable
+        return
+      end
+      
+      constant_name = NOTIFIERS[key]
+      unless constant_name
+        raise ArgumentError, "no MustBe::NOTIFIERS called #{key.inspect}"
+      end
+      self.notifier = const_get(constant_name)
+    end
+  end
+  
+  def_notifier(:RaiseNotifier, :raise) {|note| true }
+  
+  def_notifier(:LogNotifier, :log) do |note|
+    begin
+      raise note
+    rescue Note
+      puts [note.message, *note.backtrace].join("\n\t")
+    end
+    false
+  end
+  
+  def_notifier(:DebugNotifier, :debug) do |note|
+    $must_be__note = note
+    puts note.message
+    puts "Starting debugger ($must_be__note stores the note)..."
+    require 'ruby-debug'
+    debugger
+    false
+  end
+
+  set_notifier_from_env(ENV['MUST_BE__NOTIFIER'] || :raise)
+  
+  ### Note ###
+  
+  class Note < StandardError
+    attr_accessor :receiver, :assertion, :args, :block, :additional_message,
+      :prefix
+    
+    def initialize(receiver, assertion = nil, args = nil, block = nil,
+        additional_message = nil)
+      if assertion
+        @receiver = receiver
+        @assertion = assertion
+        @args = args
+        @block = block
+        @additional_message = additional_message
+      else
+        super(receiver)
+      end
+    end
+    
+    def to_s
+      if assertion
+        "#{prefix}#{MustBe.short_inspect(receiver)}."\
+          "#{assertion}#{format_args_and_block}#{additional_message}"
+      else
+        super
+      end
+    end
+        
+    alias complete_backtrace backtrace
+    
+    def backtrace
+      complete_backtrace and complete_backtrace.drop_while do |line|
+        line =~ %r{lib/must_be.*\.rb:}
+      end
+    end
+  
+  private
+    
+    def format_args_and_block
+      if args.nil? or args.empty?
+        if block.nil?
+          ""
+        else
+          " {}"
+        end
+      else
+        args_format = "(#{args.map{|v| MustBe.short_inspect(v) }.join(", ")})"
+        if block.nil?
+          args_format
+        else
+          args_format+" {}"
+        end
+      end
+    end
+  end
+  
+  def must_notify(receiver = nil, assertion= nil, args = nil, block = nil,
+      additional_message = nil)
+    note = Note === receiver ? receiver :
+      Note.new(receiver, assertion, args, block, additional_message)
+    if Thread.current[:must_check__is_checking]
+      Thread.current[:must_check__found_note] = note
+    else
+      raise note if MustBe.notifier.call(note)
+    end
+    note
+  end
+  
+  def must_check(check_block = nil, &block)
+    if check_block
+      result = nil
+      note = must_check do |obj|
+        result = check_block.arity.zero? ? check_block[] : check_block[obj]
+      end
+      if note
+        must_notify(block[note])
+      end
+      return result
+    end
+    
+    begin
+      was_checking = Thread.current[:must_check__is_checking]
+      Thread.current[:must_check__is_checking] = true
+    
+      already_found = Thread.current[:must_check__found_note]
+      Thread.current[:must_check__found_note] = nil
+    
+      yield(self)
+    
+      Thread.current[:must_check__found_note]
+    ensure
+      Thread.current[:must_check__is_checking] = was_checking
+      Thread.current[:must_check__found_note] = already_found
+    end
+  end
+end
+
+### Automatically Include in Object ###
+
+unless ENV['MUST_BE__DO_NOT_AUTOMATICALLY_INCLUDE_IN_OBJECT']
+  class Object
+    include MustBe
+  end
+end

data/lib/must_be/nonstandard_control_flow.rb

@@ -0,0 +1,159 @@
+module MustBe
+
+private
+
+  def must_raise__body(method, args, &block)
+    if args.size > 2
+      raise ArgumentError, "wrong number of arguments (#{args.size} for 2)"
+    elsif args.size == 2
+      expected_exception = args[0]
+      expected_message = args[1]
+    else
+      case args[0]
+      when nil, String, Regexp
+        expected_exception = Exception
+        expected_message = args[0]
+      else
+        expected_exception = args[0]
+      end
+    end
+    
+    unless expected_exception.is_a?(Class) and
+        expected_exception.ancestors.include?(Exception)
+      raise TypeError, "exception class expected"
+    end
+    
+    case expected_message
+    when nil, String, Regexp
+    else
+      raise TypeError, "nil, string, or regexp required"
+    end
+    
+    begin
+      result = yield
+    rescue expected_exception => actual_exception
+      
+      is_match = expected_message.nil? ||
+        expected_message === actual_exception.message
+      
+      if is_match
+        if method == :must_not_raise
+          must_notify(self, :must_not_raise, args, block,
+            ", but raised #{actual_exception.class}"+(
+              expected_message ?
+                " with message #{actual_exception.message.inspect}" : ""))
+        end
+      else
+        if method == :must_raise
+          must_notify(self, :must_raise, args, block,
+            ", but #{actual_exception.class} with"\
+            " message #{actual_exception.message.inspect} was raised")
+        end
+      end
+
+      raise
+    rescue Exception => actual_exception
+      if method == :must_raise
+        must_notify(self, :must_raise, args, block,
+          ", but #{actual_exception.class} was raised")
+      end
+      raise
+    end
+    
+    if method == :must_raise
+      must_notify(self, :must_raise, args, block, ", but nothing was raised")
+    end
+    
+    result
+  end
+
+public
+  
+  def must_raise(*args, &block)
+    must_raise__body(:must_raise, args, &block)
+  end
+  
+  def must_not_raise(*args, &block)
+    must_raise__body(:must_not_raise, args, &block)
+  end
+  
+  register_disabled_method(:must_raise, :must_just_yield)
+  register_disabled_method(:must_not_raise, :must_just_yield)
+
+private
+  
+  @@must_throw__installed = false
+  
+  def must_throw__body(method, args, &block)    
+    if args.size > 2
+      raise ArgumentError, "wrong number of arguments (#{args.size} for 2)"
+    end
+    tag = args[0]
+    obj = args[1]
+    
+    unless @@must_throw__installed
+      original_throw = Kernel.instance_method(:throw)
+      Kernel.send(:define_method, :throw) do |*arguments|
+        Thread.current[:must_throw__args] = arguments
+        original_throw.bind(self)[*arguments]
+      end
+      @@must_throw__installed = true
+    end
+    
+    begin
+      raised = false
+      returned_normaly = false
+      result = yield
+      returned_normaly = true    
+      result
+    rescue Exception => ex
+      raised = true
+      if method == :must_throw
+        must_notify(self, :must_throw, args, block,
+          ", but raised #{ex.class}")
+      end
+      raise
+    ensure
+      if raised
+      elsif returned_normaly
+        if method == :must_throw
+          must_notify(self, :must_throw, args, block, ", but did not throw")
+        end
+      else
+        thrown = Thread.current[:must_throw__args]
+        thrown_tag = thrown[0]
+        thrown_obj = thrown[1]
+        
+        if method == :must_throw
+          if args.size >= 1 and tag != thrown_tag
+            must_notify(self, :must_throw, args, block,
+              ", but threw #{thrown.map(&:inspect).join(", ")}")
+          elsif args.size == 2 and thrown.size < 2 || obj != thrown_obj
+            must_notify(self, :must_throw, args, block,
+              ", but threw #{thrown.map(&:inspect).join(", ")}")
+          end
+        elsif method == :must_not_throw
+          if args.size == 0 or args.size == 1 && tag == thrown_tag or
+              args.size == 2 && tag == thrown_tag && thrown.size == 2 &&
+                obj == thrown_obj
+            must_notify(self, :must_not_throw, args, block,
+              ", but threw #{thrown.map(&:inspect).join(", ")}")
+          end
+        end
+      end
+    end
+  end
+
+public
+  
+  def must_throw(*args, &block)
+    must_throw__body(:must_throw, args, &block)
+  end
+  
+  def must_not_throw(*args, &block)
+    must_throw__body(:must_not_throw, args, &block)
+  end
+  
+  register_disabled_method(:must_throw, :must_just_yield)
+  register_disabled_method(:must_not_throw, :must_just_yield)
+end

data/lib/must_be/proxy.rb

@@ -0,0 +1,62 @@
+module MustBe
+  class Proxy
+    mandatory_methods = [:__id__, :object_id, :__send__]
+    
+    if RUBY_VERSION < "1.9"
+      mandatory_methods.map! &:to_s
+    end
+    
+    (instance_methods - mandatory_methods).each do |method|
+      undef_method(method)
+    end
+    
+    def initialize(delegate, assertion = :must)
+      unless assertion == :must or assertion == :must_not
+        raise ArgumentError,
+          "assertion (#{assertion.inspect}) must be :must or :must_not"
+      end
+      @delegate = delegate
+      @assertion = assertion
+    end
+    
+    def method_missing(symbol, *args, &block)
+      result = @delegate.send(symbol, *args, &block)
+      assertion = result ? true : false
+      unless assertion == (@assertion == :must)
+        @delegate.must_notify(@delegate, "#{@assertion}.#{symbol}", args, 
+          block)
+      end
+      result
+    end
+  end
+  
+  def must(message = nil, &block)
+    if block_given?
+      unless block.arity > 1 ? yield(self, message) : yield(self)
+        if message
+          must_notify(message)
+        else
+          must_notify(self, __method__, nil, block)
+        end
+      end
+      self
+    else
+      Proxy.new(self, :must)
+    end
+  end
+  
+  def must_not(message = nil, &block)
+    if block_given?
+      if block.arity > 1 ? yield(self, message) : yield(self)
+        if message
+          must_notify(message)
+        else
+          must_notify(self, __method__, nil, block)
+        end
+      end
+      self
+    else
+      Proxy.new(self, :must_not)
+    end
+  end
+end

data/lib/must_be.rb

@@ -0,0 +1,9 @@
+here = File.expand_path(File.dirname(__FILE__))
+
+require here+'/must_be/core'
+require here+'/must_be/basic'
+require here+'/must_be/proxy'
+require here+'/must_be/containers'
+require here+'/must_be/containers_registered_classes'
+require here+'/must_be/attr_typed'
+require here+'/must_be/nonstandard_control_flow'

data/must_be.gemspec

@@ -0,0 +1,71 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{must_be}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["William Taysom"]
+  s.date = %q{2010-09-12}
+  s.description = %q{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.}
+  s.email = %q{wtaysom@gmail.com}
+  s.extra_rdoc_files = [
+    "README.md"
+  ]
+  s.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"
+  ]
+  s.homepage = %q{http://github.com/wtaysom/must_be}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{must_be Runtime Assertions}
+  s.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"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end
+