higher_expectations 0.0.1

data/History.txt

@@ -0,0 +1,4 @@
+== 0.0.1 2008-08-14
+
+* 1 major enhancement:
+  * Initial release

data/License.txt

@@ -0,0 +1,14 @@
+Copyright (C) 2008 Justin Tyler Wiley
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>

data/Manifest.txt

@@ -0,0 +1,30 @@
+History.txt
+License.txt
+Manifest.txt
+README.txt
+Rakefile
+config/hoe.rb
+config/requirements.rb
+lib/higher_expectations.rb
+lib/instance_methods.rb
+lib/version.rb
+script/console
+script/console.cmd
+script/destroy
+script/destroy.cmd
+script/generate
+script/generate.cmd
+script/txt2html
+script/txt2html.cmd
+setup.rb
+tasks/deployment.rake
+tasks/environment.rake
+tasks/website.rake
+spec/higher_expectations_spec.rb
+spec/instance_methods_spec.rb
+spec/spec_helper.rb
+website/index.html
+website/index.txt
+website/javascripts/rounded_corners_lite.inc.js
+website/stylesheets/screen.css
+website/template.html.erb

data/README.txt

@@ -0,0 +1,155 @@
+= higher_expectations
+
+* http://higher_expectations.rubyforge
+
+== DESCRIPTION:
+
+Provides an easy and quick way to make sure method arguments are what you expect them to be.
+
+You want to make sure that methods explode if they are given inappropriate inputs, but you don't want to deal with a complete design-by-contract implementation like RDBC.  Please note that this is nothing like a formal design-by-contract in any number of important ways.  It provides something -like- the "obligations" component of DBC.
+
+Writing explicit exception checking is tiring, redundant and error prone:
+
+def calc_sunrise(day, month, year, latitude, longitude, planet)
+  raise Exception.new("day should be numeric and in the range of 1-32) unless day.kind_of?(Numeric) && day > 0 && day < 32
+  ...etc. etc. ...
+end
+
+Higher expectations provides an easy and human readable alternative:
+
+def calc_sunrise(day, month, year)
+  has_expectations(day, month)
+  day.must_not_be(Numeric).and_must_be_in_range(0..5)
+  month.must_be(Numeric)
+  ...do other critical work below...
+end
+
+== FEATURES/PROBLEMS:
+
+* Please note that this is alpha software
+* Provides a set of usefull methods for determining what an object is at runtime, and raising an exception
+* Avoids creating these methods in Object directly, and instead extends the objects passed in (although it does add them directly to Numeric due to constraints in Ruby's Numeric implementation)
+* Allows for method changing and provides a dose of syntactic sugar
+
+== SYNOPSIS:
+
+Imagine you have a method to calculate sunrise buried within a 1D planet simulator codebase.  Throughout the codebase, validations are used to check data input, and there is a well thought-out and well written test suite.
+
+  def calc_sunrise(day, month)
+    sunrise = (day - 50000)/month   # arbitrary calculation that assumes day is a number and not negative
+  end
+
+However, Joey your coworker hacks and calls the following function:
+
+  PlanetEarth.sunrise = calc_sunrise(-5, 1)
+
+Code executes, no exceptions are raised, but earths sunrise changes to a weird value.  No amount of unit testing, specing, validating outside the model would have stopped Joey from making this hambone maneuver.
+
+Now you could have said something like:
+
+def calc_sunrise(day, month)
+  raise ArgumentError.new("day must be numeric") unless day.kind_of?(Numeric)
+  raise ArgumentError.new("day must be in range of 1-31") unless day > 1 && day < 31
+  raise ArgumentError.new("month must be numeric") unless month.kind_of?(Numeric)
+  raise ArgumentError.new("month must be in range of 1-31") unless month > 1 && day < 31  # note subtle bug
+  raise ArgumentError.new("month must not be nil") unless month > 1 && month < 31
+  ...sunrise calc...
+end
+
+Drudgery, duplication, error prone, etc. etc.  Wouldn't you like to do this instead?
+
+include HigherExpectations  # somewhere in the class
+def calc_sunrise(day, month)
+    has_expectations(day, month)    # attach expectation methods to each object
+    day.must_be(Numeric)            # day must be numeric or an exception will be raise
+    day.must_be_in_range(1..31)     # day must be in range or exception
+    month.must_be(Numeric).and_must_be_in_range(1..31)  # a neat combination of both
+    month.must_be_nil rescue nil                        # since it raises an exception, its trappable, allowing for more flexible handling
+  ...sunrise calc
+end
+
+...or even cleaner.
+
+def calc_sunrise(day,month)
+  has_expectations(day,month)
+  *args.map{|a| a.must_be(Numeric).and_must_be_in_range(1..31)}
+  month.must_be_nil
+  ...sunrise calc...
+end
+
+See spec below for details on methods possible.
+
+Copyright (c) 2008 Justin Tyler Wiley (justintylerwiley.com), under GPL V3
+
+== SPEC:
+
+HigherExpectations
+- should not raise an exception when included
+
+HigherExpectations#has_expectations
+- should loop through given objects, extending each with instance_expectations.rb methods
+
+InstanceMethods
+
+InstanceMethods#raise_ae
+- should raise an ArgumentException with the given message
+
+InstanceMethods#must_be_/must_not_be_ - true, false, and nil
+- should raise exception if expected to be true false or nil, and they are not
+- should not raise exception if expected to be true false or nil, and they are
+
+InstanceMethods#must_be and must_not_be a particular value
+- should raise exception if item must be something and isnt
+- should not raise exception if item must be something and IS
+- (#not) should raise exception if item must not be something and IS
+- (#not) should not raise exception if item must not be something and is not
+
+InstanceMethods#must_be_a and must_not_be_a particular class of object
+- should raise exception if item must be a class and isnt
+- should not raise exception if item must be a class and IS
+- (#not) should raise exception if item must not be a class and is not
+- (#not) should not raise exception if item must not be a class and IS
+
+InstanceMethods#must_be_in_range and must_not_be_in_range of numbers
+- should raise exception if item must be in a range and isnt
+- should not raise exception if item must be in a range and is
+- (#not) should raise exception if item in a range
+- (#not) should not raise exception if item not in range
+- should raise HigherExpectation exception if handed something besides and array or a range
+
+InstanceMethods#must_match and must_not_match a given pattern
+- should raise exception if item does not match
+- should not raise exception if item matches
+- (#not) should not raise exception if item does not match
+- (#not) should raise exception if item matches
+
+InstanceMethods#must_respond_to and must_not_respond_to a given method
+- should raise exception if item does not respond
+- should not raise exception if item respond
+- (#not) should raise exception if item responds
+- (#not) should not raise exception if does respond
+
+== REQUIREMENTS:
+
+* hoe
+
+== INSTALL:
+
+* sudo gem install higher-expectations
+
+== LICENSE:
+
+Copyright (C) 2008 Justin Tyler Wiley
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>

data/Rakefile

@@ -0,0 +1,4 @@
+require 'config/requirements'
+require 'config/hoe' # setup Hoe + all gem configuration
+
+Dir['tasks/**/*.rake'].each { |rake| load rake }

data/config/hoe.rb

@@ -0,0 +1,73 @@
+require 'higher_expectations/version'
+
+AUTHOR = 'FIXME full name'  # can also be an array of Authors
+EMAIL = "FIXME email"
+DESCRIPTION = "description of gem"
+GEM_NAME = 'higher_expectations' # what ppl will type to install your gem
+RUBYFORGE_PROJECT = 'higher_expectations' # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
+EXTRA_DEPENDENCIES = [
+#  ['activesupport', '>= 1.3.1']
+]    # An array of rubygem dependencies [name, version]
+
+@config_file = "~/.rubyforge/user-config.yml"
+@config = nil
+RUBYFORGE_USERNAME = "unknown"
+def rubyforge_username
+  unless @config
+    begin
+      @config = YAML.load(File.read(File.expand_path(@config_file)))
+    rescue
+      puts <<-EOS
+ERROR: No rubyforge config file found: #{@config_file}
+Run 'rubyforge setup' to prepare your env for access to Rubyforge
+ - See http://newgem.rubyforge.org/rubyforge.html for more details
+      EOS
+      exit
+    end
+  end
+  RUBYFORGE_USERNAME.replace @config["username"]
+end
+
+
+REV = nil
+# UNCOMMENT IF REQUIRED:
+# REV = YAML.load(`svn info`)['Revision']
+VERS = HigherExpectations::VERSION::STRING + (REV ? ".#{REV}" : "")
+RDOC_OPTS = ['--quiet', '--title', 'higher_expectations documentation',
+    "--opname", "index.html",
+    "--line-numbers",
+    "--main", "README",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps
+    @extra_deps.reject! { |x| Array(x).first == 'hoe' }
+    @extra_deps
+  end
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.developer(AUTHOR, EMAIL)
+  p.description = DESCRIPTION
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/test_*.rb"]
+  p.clean_globs |= ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']  #An array of file patterns to delete on clean.
+
+  # == Optional
+  p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  #p.extra_deps = EXTRA_DEPENDENCIES
+
+    #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
+  end
+
+CHANGES = $hoe.paragraphs_of('History.txt', 0..1).join("\\n\\n")
+PATH    = (RUBYFORGE_PROJECT == GEM_NAME) ? RUBYFORGE_PROJECT : "#{RUBYFORGE_PROJECT}/#{GEM_NAME}"
+$hoe.remote_rdoc_dir = File.join(PATH.gsub(/^#{RUBYFORGE_PROJECT}\/?/,''), 'rdoc')
+$hoe.rsync_args = '-av --delete --ignore-errors'
+$hoe.spec.post_install_message = File.open(File.dirname(__FILE__) + "/../PostInstall.txt").read rescue ""

data/config/requirements.rb

@@ -0,0 +1,15 @@
+require 'fileutils'
+include FileUtils
+
+require 'rubygems'
+%w[rake hoe newgem rubigen].each do |req_gem|
+  begin
+    require req_gem
+  rescue LoadError
+    puts "This Rakefile requires the '#{req_gem}' RubyGem."
+    puts "Installation: gem install #{req_gem} -y"
+    exit
+  end
+end
+
+$:.unshift(File.join(File.dirname(__FILE__), %w[.. lib]))

data/lib/higher_expectations.rb

@@ -0,0 +1,37 @@
+$:.unshift File.dirname(__FILE__)
+require 'rubygems'
+require 'instance_methods'
+
+##
+#  Higher expectations module
+#  Provides method to load instance methods in a group of arguments
+#  Requires instance methods
+#
+#  Usage:
+#
+#  class Something
+#    include HigherExpectations
+#  end
+#  ..or optionally inject into Object (not recommended)
+#
+module HigherExpectations
+  VERSION = '0.1.0'
+
+  # Should be called at method entrance
+  # instead of spaming up entire Object class method space, extend each given object with expectation methods
+  def has_expectations(*objects)
+    objects.map do |obj|
+      begin
+        obj.extend(HigherExpectations::InstanceMethods)
+      # TypeErrors are generated when trying to extend Numeric objects, which are not and cannot be singeltons and hence cannot get new methods.  
+      # Handled below via Numeric
+      rescue TypeError
+        next    
+      end
+    end
+  end
+  alias :has_expectation :has_expectations
+end
+
+# Provides instance methods for Fixnum class, which due to limitiations mentioned above must be treated as a special case
+class Fixnum; include HigherExpectations::InstanceMethods; end;

data/lib/instance_methods.rb

@@ -0,0 +1,103 @@
+module HigherExpectations
+  module InstanceMethods
+    # must_X functions raise the traditional "ArgumentException", this exception is for programic errors when using HigherExpectations
+    class HigherExpectationException < Exception; end;
+    
+    # defines must_be and must_not_be nil, true, false
+    [true, false].each do |value|
+      send :define_method, "must_be_#{value.to_s}".to_sym, lambda {
+        raise_ae(" to be #{value.to_s}") unless self == value; self;
+      }
+      send :define_method, "must_not_be_#{value.to_s}".to_sym, lambda {
+        raise_ae(" to be #{value.to_s}") unless self != value; self;
+      }
+    end
+    
+    # value must be nil, or must not be nil respectively
+    def must_be_nil; raise_ae(" to be nil") unless self == nil; end;
+    alias :and_must_be_nil :must_be_nil
+    def must_not_be_nil; raise_ae(" to be nil") unless self != nil; end;
+    alias :and_must_not_be_nil :must_not_be_nil
+    
+    # raise ArgumentError exception
+    def raise_ae(message)
+      raise ArgumentError.new("Method expects this argument" + message.to_s)
+    end
+    
+    # argument must be the given value
+    def must_be(*values)
+      values.each {|value| raise_ae(" must equal #{value}") unless self == value; } 
+      self   # allow for method concatonation "foo.must_be(String).and_must_not_be_nil
+    end
+    alias :and_must_be :must_be
+    
+    # argument must NOT be the given value
+    def must_not_be(*values)
+      values.each {|value| raise_ae(" must NOT equal #{value}") unless self != value; } 
+      self
+    end
+    alias :and_must_not_be :must_not_be
+    
+    # value(s) must be a specific class or in given set of classes
+    def must_be_a(*klasses)
+      klasses.each do |klass|
+        raise_ae(" should be #{klass.to_s}") unless self.kind_of?(klass)
+      end
+      self
+    end
+    alias :and_must_be_a :must_be_a
+    
+    # value(s)  must not be in a specific class or set of klasses
+    def must_not_be_a(*klasses)
+      klasses.each do |klass|
+        raise_ae(" should NOT be #{klass.to_s}") if self.kind_of?(klass)
+      end
+      self
+    end
+    alias :and_must_not_be_a :must_not_be_a
+
+    # value(s)  must be in a specific numeric range
+    def must_be_in_range(range)
+      raise HigherExpectationException.new("Must pass in two values ('foo.must_be_in_range(0,5)')") unless range.kind_of?(Range) || range.kind_of?(Array)
+      raise_ae("'s value to be in the range of #{range.first} to #{range.last} (it was #{self.to_s})") unless self >= range.first && self <= range.last
+      self
+    end
+    alias :and_must_be_in_range :must_be_in_range
+    
+    # value(s)  must be in a specific numeric range
+    def must_not_be_in_range(range)
+      raise HigherExpectationException.new("Must pass in two values ('foo.must_be_in_range(0,5)')") unless range.kind_of?(Range) || range.kind_of?(Array)
+      raise_ae("'s value NOT to be in the range of #{range.first} to #{range.last} (it was #{self.to_s})") if self >= range.first && self <= range.last
+      self
+    end
+    alias :and_must_not_be_in_range :must_not_be_in_range
+    
+    def must_match(pattern)
+      raise_ae(" to match pattern #{pattern.to_s}") unless self =~ pattern
+      self
+    end
+    alias :and_must_match :must_match
+
+    def must_not_match(pattern)
+      raise_ae(" to match pattern #{pattern.to_s}") if self =~ pattern
+      self
+    end
+    alias :and_must_not_match :must_not_match
+    
+    def must_respond_to(*meths)
+      meths.each do |meth|
+        raise_ae(" to respond to #{meth}") unless self.respond_to?(meth.to_s)
+      end
+      self
+    end
+    alias :and_must_respond_to :must_respond_to
+    
+    def must_not_respond_to(*meths)
+      meths.each do |meth|
+        raise_ae(" to respond to #{meth}") if self.respond_to?(meth.to_s)
+      end
+      self
+    end
+    alias :and_must_not_respond_to :must_not_respond_to
+  end
+end