preconditions 0.1.2 → 0.2.0

data/README.md

@@ -7,98 +7,56 @@ Preconditions</a> class
 
 ## Overview ##
 
-The Preconditions package provides a single module, Preconditions, with methods for:
-
-* Checking if an argument is nil
-* Checking if an argument satisfies a boolean condition (e.g. x > 10)
-* Checking if an argument responds to a certain method (duck typing)
-* Checking if an argument is of a specific type (strict typing)
-
-Each of these methods will raise an appropriate exception if the rule it is
-applying is violated.
-
-Preconditions can be checked either by using the `Preconditions` module
-directly, as in `Preconditions::check_not_nil(x)`, or by mixing the
-`Preconditions` module into your class to make the methods available without the
-`Preconditions` prefix.  If the module is mixed in the precondition checking
-methods will be available to both class and instance methods equivalently.
+The preconditions package provides a single module, `Preconditions`, which in turn provides a number of methods to check
+the validity of method arguments.  Two API styles are provided: a standard "command query" interface, where each check
+is a single method call with an optional message format, and a fluent DSL interface, where checks are built up using
+a more natural language.
 
 ## Usage ##
 
-To check for nil arguments:
-
-    def my_meth(arg)
-      Preconditions.check_not_nil(arg)
-      ...
-    end
-
-If you wish to supply a message simply include a string as your second
-parameter:
-
-    def my_meth(arg)
-      Preconditions.check_not_nil(arg, "nil values are evil!")
-      ...
-    end
+To use the command-query API you can access the `check_XXX` methods directly through the Preconditions module, like so:
 
-You can even use a format if you want to interpolate some variables into your
-message lazily:
-
-    def my_meth(arg)
-      Preconditions.check_not_nil(arg, "Using nil in context of: %s", @bigobj.to_s)
-      ...
+    class MyMath
+      def sqrt(num)
+        Preconditions.check_not_nil(num)
+        Preconditions.check_type(num, Integer, "num argument must be an integer: non integer types are unsupported")
+        Preconditions.check_argument(num >= 0, "num argument must be greater than zero")
+        num.sqrt
+      end
     end
 
-All methods support both a message and a message/format argument pair.
+You can also `include Preconditions` to import the command-query calls into your class for use without the
+`Preconditions` module prefix.  The full list of command-query calls is documented in the `Preconditions` module itself.
 
-To check an argument property:
+To use the fluent DSL API use the `check(arg).is {}` form like so:
 
-    def sqrt(num)
-      Preconditions.check_argument(num > 0)
-      ...
-    end
-
-or alternatively
-    
-    def sqrt(num)
-      Preconditions.check_block("sqrt doesn't yet support complex numbers") { num > 0 }
-      ...
+    class MyMath
+      def sqrt(num)
+        Preconditions.check(num) { is_not_nil and has_type(Integer) and satisfies(">= 0") { arg >= 0 } }
+        num.sqrt
+      end
     end
 
-To check the type of an object being supplied:
+Note that there is less opportunity for custom messaging in the fluent API.  However, a second argument to `check` can
+be supplied to add the argument name to any raised errors:
 
-    def sqrt(num)
-      Preconditions.check_type(num, Integer, 
-                               "sqrt is integer only, you supplied a %s", num.class)
-      ...
+    class MyMath
+      def sqrt(num)
+        Preconditions.check(num, 'num') { is_not_nil and has_type(Integer) and satisfies(">= 0") { arg >= 0 } }
+        num.sqrt
+      end
     end
 
-To check if an object will respond to a method you intend to call:
+In this case, if `num` is the value -10 then an [ArgumentError] will be raised with a message along the lines of
+"Argument 'num' must be >= 0, but was -10".
 
-    def sqrt(num)
-      Preconditions.check_reponds_to(num, :sqrt,
-                                     "yup, we're that lazy")
-      ...
-    end
+The set of available checks is documented in the `ConditionChecker` documentation.
 
-If you wish to avoid the `Preconditions` prefix on every call, you can include the `Preconditions` module into your class:
-
-    class SpiffyClass
-      include Preconditions
-      
-      def a(x)
-        check_not_nil(x)
-        ...
-      end
-      
-      def self.b(y)
-        check_not_nil(y)
-        ...
-      end
-    end
+The `check` method on the fluent API will not be imported when the `Preconditions` module is included: it can only be
+addressed with the `Preconditions` prefix.  This is to prevent possible name clashes with existing `check` methods in
+client code (check being a somewhat common verb).  The use of `and` as a separator in the DSL expression is purely
+for readability: newlines and semi-colons work just as well (all DSL methods either raise an exception or return true).
 
-Where possible the `check_` methods will return the object being checked.  In
-the cases where this is not possible (`check_argument` and `check_block`) the
-boolean result of the expression is returned.
 
 ## Contributing to preconditions ##
  

data/VERSION

@@ -1 +1 @@
-0.1.2
+0.2.0

data/lib/condition_checker.rb

@@ -0,0 +1,81 @@
+# The ConditionChecker supplied the DSL host environment to evaluate expressions in the Preconditions DSL language.
+# The #is method takes a block that is evaluated in the context of the ConditionChecker instance, with access to all
+# of the ConditionChecker methods.  Typical usage will be of the form:
+#
+#    Preconditions.check(x).is { not_nil and responds_to(:hello)
+#
+class ConditionChecker
+
+  attr_reader :arg, :name
+
+  def initialize(arg, name=nil, &block)
+    @arg = arg
+    @name = name
+  end
+
+  # DSL call.  Establishes that the checked argument is non-nil.
+  # @raises [ArgumentError] if the argument is nil
+  # @return true
+  def is_not_nil
+    if arg.nil?
+      raise ArgumentError, format_message("may not be nil")
+    end
+    true
+  end
+
+  # DSL call.  Establishes that the checked argument is of the given type.  nil is treated as a bottom type (i.e. it
+  # is compatible with all types)
+  # @raises [TypeError] if the argument is not type-compatible with the argument
+  # @return true
+  def has_type(type)
+    if !arg.nil? && !arg.kind_of?(type)
+      raise TypeError, format_message("must be of type #{type.name}, but is of type #{arg.class.name}")
+    end
+    true
+  end
+
+  # DSL call.  Establishes that the checked argument can respond to the requested method, identified by symbol.
+  # @raises [NameError] if the argument cannot respond to the supplied method name
+  # @return true
+  def can_respond_to(method_symbol)
+    if !arg.respond_to?(method_symbol)
+      raise NameError, format_message("must respond to method #{method_symbol}")
+    end
+    true
+  end
+
+  # DSL call.  Establishes that the checked argument satisfies an arbitrary condition specified in a block.  If the
+  # block evaluates to true the argument passes; if it evaluates to false it fails and an [ArgumentError] is raised.
+  # An optional message may be supplied to describe what the block is checking.
+  #
+  # If the block requests a bound variable that variable will be assigned the value of the argument we're checking.  The
+  # block may also access the argument value using the `arg` name.  Note, also, that the block is a closure and will
+  # have natural access to variables in lexical scope at the time the DSL expression is created.  Thus, one can do
+  # something like:
+  #    def sqrt(num)
+  #       Preconditions.check(num) { satisfies { num >= 0 } }
+  #    end
+  def satisfies(msg = nil, &block)
+    success = if block.arity > 0
+                yield(arg)
+              else
+                instance_eval(&block)
+              end
+    if !success
+      raise ArgumentError, msg.nil? ? format_message("must satisfy given conditions") : format_message("must be #{msg}")
+    end
+    true
+  end
+
+  private
+
+  def format_message(message)
+    name_str = if name
+                 "'#{name}' "
+               else
+                 ''
+               end
+    "Argument #{name_str}#{message}"
+  end
+
+end

data/lib/preconditions.rb

@@ -1,7 +1,8 @@
-# 
+require 'condition_checker'
+
 module Preconditions
 
-  module PreconditionMethods
+  module PreconditionMixinMethods
 
     # Check that arg is not nil, raising an ArgumentError with an optional
     # message and format if it is nil
@@ -72,7 +73,7 @@ module Preconditions
     end
 
     def self.included(receiver)
-      receiver.extend PreconditionMethods
+      receiver.extend PreconditionMixinMethods
     end
 
     private
@@ -89,11 +90,24 @@ module Preconditions
     end
   end
 
+  module PreconditionModuleClassMethods
+    # Introduce a DSL expression to check the given argument, with the optionally given name.  This will return a
+    #[ConditionChecker] instance that can be used to build the DSL expression.
+    def check(argument, name = nil, &block)
+      cc = ConditionChecker.new(argument, name)
+      if block_given?
+        cc.instance_eval(&block)
+      end
+      argument
+    end
+  end
+
   class << self
-    include PreconditionMethods
+    include PreconditionMixinMethods
+    include PreconditionModuleClassMethods
   end
 
   def self.included(receiver)
-    receiver.send :include, PreconditionMethods
+    receiver.send :include, PreconditionMixinMethods
   end
 end

data/preconditions.gemspec

@@ -0,0 +1,75 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{preconditions}
+  s.version = "0.2.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = [%q{tucker}]
+  s.date = %q{2011-05-24}
+  s.description = %q{The Preconditions library provides a simple set of methods for checking arguments being passed into a method.  Instead of writing custom checks and raising exceptions directly in your code you can use Preconditions to verify basic properties of your arguments (not-nil, satisfying a boolean expression, being of a certain type/duck-type) and raise the appropriate exception for you.
+}
+  s.email = %q{tucker+rubygems@glyde.com}
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.md"
+  ]
+  s.files = [
+    ".document",
+    "Gemfile",
+    "LICENSE.txt",
+    "README.md",
+    "Rakefile",
+    "VERSION",
+    "lib/condition_checker.rb",
+    "lib/preconditions.rb",
+    "preconditions.gemspec",
+    "spec/preconditions_dsl_spec.rb",
+    "spec/preconditions_spec.rb",
+    "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/ctucker/preconditions}
+  s.licenses = [%q{MIT}]
+  s.require_paths = [%q{lib}]
+  s.rubygems_version = %q{1.8.3}
+  s.summary = %q{Preconditions checking support inspired by Guava}
+  s.test_files = [
+    "spec/preconditions_dsl_spec.rb",
+    "spec/preconditions_spec.rb",
+    "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<yard>, ["~> 0.6.0"])
+      s.add_development_dependency(%q<bluecloth>, [">= 0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.5.2"])
+      s.add_development_dependency(%q<rcov>, [">= 0"])
+      s.add_development_dependency(%q<rspec>, [">= 2.6.0"])
+      s.add_development_dependency(%q<ci_reporter>, [">= 0"])
+    else
+      s.add_dependency(%q<yard>, ["~> 0.6.0"])
+      s.add_dependency(%q<bluecloth>, [">= 0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+      s.add_dependency(%q<rcov>, [">= 0"])
+      s.add_dependency(%q<rspec>, [">= 2.6.0"])
+      s.add_dependency(%q<ci_reporter>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<yard>, ["~> 0.6.0"])
+    s.add_dependency(%q<bluecloth>, [">= 0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+    s.add_dependency(%q<rcov>, [">= 0"])
+    s.add_dependency(%q<rspec>, [">= 2.6.0"])
+    s.add_dependency(%q<ci_reporter>, [">= 0"])
+  end
+end
+

data/spec/preconditions_dsl_spec.rb

@@ -0,0 +1,59 @@
+require "rspec"
+require 'preconditions'
+
+describe "dsl expression" do
+
+  it "should pass with no checks in the is() block" do
+    arg = 1
+    res = Preconditions.check(arg) {}
+    res.should == arg
+  end
+
+  it "should pass with no is() call" do
+    arg = 1
+    res = Preconditions.check(arg)
+    # res will be a ConditionChecker instance, but should not have raised an exception
+  end
+
+  it "should raise on a failing condition check" do
+    arg = nil
+    expect {
+      Preconditions.check(arg, 'arg') { is_not_nil }
+    }.to raise_exception(ArgumentError)
+  end
+
+  it "should raise on a failing condition check in a conjugated list" do
+    arg = 1
+    expect {
+      Preconditions.check(arg, 'arg') { is_not_nil and has_type(String) }
+    }.to raise_exception(TypeError)
+  end
+
+  it "should return the argument if all condition checks pass" do
+    arg = 1
+    res = Preconditions.check(arg, 'arg') { is_not_nil and has_type(Integer) }
+    res.should == arg
+  end
+
+  it "should evaluate a satisfies block using the instance-local arg value" do
+    x = 1
+    expect {
+      Preconditions.check(x, 'x') { is_not_nil and satisfies("less than zero") { arg <= 0 } }
+    }.to raise_exception(ArgumentError, "Argument 'x' must be less than zero")
+  end
+
+  it "should pass argument in to yielded satisfies block if requested" do
+    x = 1
+    expect {
+      Preconditions.check(x, 'x') { is_not_nil and satisfies("less than zero") { |v| v <= 0 } }
+    }.to raise_exception(ArgumentError, "Argument 'x' must be less than zero")
+  end
+
+  it "should evaluate a satisfies block binding in the arg name as an accessible variable" do
+    x = 1
+    expect {
+      Preconditions.check(x, 'x') { is_not_nil and satisfies("less than zero") { x <= 0 } }
+    }.to raise_exception(ArgumentError, "Argument 'x' must be less than zero")
+  end
+
+end

data/spec/preconditions_spec.rb

@@ -71,6 +71,12 @@ end
     it "returns the argument when it supports the requested method" do
       subject.check_responds_to(1, :succ).should == 1
     end
+
+    it "should not expose dsl-only method #check when included" do
+      should_have_check = subject.class == Module
+      subject.respond_to?(:check).should == should_have_check
+    end
+
   end
 
 end

data/spec/spec_helper.rb

@@ -6,7 +6,3 @@ require 'preconditions'
 # Requires supporting files with custom matchers and macros, etc,
 # in ./support/ and its subdirectories.
 Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
-
-RSpec.configure do |config|
-  
-end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: preconditions
 version: !ruby/object:Gem::Version 
-  hash: 31
+  hash: 23
   prerelease: 
   segments: 
   - 0
-  - 1
   - 2
-  version: 0.1.2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - tucker
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-22 00:00:00 Z
+date: 2011-05-24 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   version_requirements: &id001 !ruby/object:Gem::Requirement 
@@ -29,10 +29,10 @@ dependencies:
         - 6
         - 0
         version: 0.6.0
-  name: yard
-  prerelease: false
   type: :development
   requirement: *id001
+  prerelease: false
+  name: yard
 - !ruby/object:Gem::Dependency 
   version_requirements: &id002 !ruby/object:Gem::Requirement 
     none: false
@@ -43,10 +43,10 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  name: bluecloth
-  prerelease: false
   type: :development
   requirement: *id002
+  prerelease: false
+  name: bluecloth
 - !ruby/object:Gem::Dependency 
   version_requirements: &id003 !ruby/object:Gem::Requirement 
     none: false
@@ -59,10 +59,10 @@ dependencies:
         - 0
         - 0
         version: 1.0.0
-  name: bundler
-  prerelease: false
   type: :development
   requirement: *id003
+  prerelease: false
+  name: bundler
 - !ruby/object:Gem::Dependency 
   version_requirements: &id004 !ruby/object:Gem::Requirement 
     none: false
@@ -75,10 +75,10 @@ dependencies:
         - 5
         - 2
         version: 1.5.2
-  name: jeweler
-  prerelease: false
   type: :development
   requirement: *id004
+  prerelease: false
+  name: jeweler
 - !ruby/object:Gem::Dependency 
   version_requirements: &id005 !ruby/object:Gem::Requirement 
     none: false
@@ -89,10 +89,10 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  name: rcov
-  prerelease: false
   type: :development
   requirement: *id005
+  prerelease: false
+  name: rcov
 - !ruby/object:Gem::Dependency 
   version_requirements: &id006 !ruby/object:Gem::Requirement 
     none: false
@@ -105,10 +105,10 @@ dependencies:
         - 6
         - 0
         version: 2.6.0
-  name: rspec
-  prerelease: false
   type: :development
   requirement: *id006
+  prerelease: false
+  name: rspec
 - !ruby/object:Gem::Dependency 
   version_requirements: &id007 !ruby/object:Gem::Requirement 
     none: false
@@ -119,10 +119,10 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  name: ci_reporter
-  prerelease: false
   type: :development
   requirement: *id007
+  prerelease: false
+  name: ci_reporter
 description: |
   The Preconditions library provides a simple set of methods for checking arguments being passed into a method.  Instead of writing custom checks and raising exceptions directly in your code you can use Preconditions to verify basic properties of your arguments (not-nil, satisfying a boolean expression, being of a certain type/duck-type) and raise the appropriate exception for you.
 
@@ -141,10 +141,12 @@ files:
 - README.md
 - Rakefile
 - VERSION
+- lib/condition_checker.rb
 - lib/preconditions.rb
+- preconditions.gemspec
+- spec/preconditions_dsl_spec.rb
 - spec/preconditions_spec.rb
 - spec/spec_helper.rb
-- test/helper.rb
 homepage: http://github.com/ctucker/preconditions
 licenses: 
 - MIT
@@ -174,11 +176,11 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.7.2
+rubygems_version: 1.8.3
 signing_key: 
 specification_version: 3
 summary: Preconditions checking support inspired by Guava
 test_files: 
+- spec/preconditions_dsl_spec.rb
 - spec/preconditions_spec.rb
 - spec/spec_helper.rb
-- test/helper.rb

data/test/helper.rb

@@ -1,17 +0,0 @@
-require 'rubygems'
-require 'bundler'
-begin
-  Bundler.setup(:default, :development)
-rescue Bundler::BundlerError => e
-  $stderr.puts e.message
-  $stderr.puts "Run `bundle install` to install missing gems"
-  exit e.status_code
-end
-require 'test/unit'
-
-$LOAD_PATH.unshift(File.dirname(__FILE__))
-$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
-require 'preconditions'
-
-class Test::Unit::TestCase
-end