contracts 0.0.2 → 0.0.3

data/lib/builtin_contracts.rb

@@ -1,40 +1,73 @@
+=begin rdoc
+This module contains all the builtin contracts.
+If you want to use them, first:
+  
+  import Contracts
+
+And then use these or write your own!
+
+A simple example:
+
+  Contract Num, Num, Num
+  def add(a, b)
+     a + b
+   end
+
+The contract is <tt>Contract Num, Num, Num</tt>. That says that the +add+ function takes two numbers and returns a number.
+=end
 module Contracts
+  # Check that an argument is +Numeric+.
   class Num
     def self.valid? val
       val.is_a? Numeric
     end
   end
 
+  # Check that an argument is a positive number.
   class Pos
     def self.valid? val
       val > 0
     end
   end
 
+  # Check that an argument is a negative number.
   class Neg
     def self.valid? val
       val < 0
     end
   end
 
+  # Passes for any argument.
   class Any
     def self.valid? val
       true
     end
   end
 
+  # Fails for any argument.
   class None
     def self.valid? val
       false
     end
   end
 
+  # Use this when you are writing your own contract classes.
+  # Allows your contract to be called with <tt>[]</tt> instead of <tt>.new</tt>:
+  #
+  # Old: <tt>Or.new(param1, param2)</tt>
+  #
+  # New: <tt>Or[param1, param2]</tt>
+  #
+  # Of course, <tt>.new</tt> still works.
   class CallableClass
     def self.[](*vals)
       self.new(*vals)
     end
   end
 
+  # Takes a variable number of contracts.
+  # The contract passes if any of the contracts pass.
+  # Example: <tt>Or[Fixnum, Float]</tt>
   class Or < CallableClass
     def initialize(*vals)
       @vals = vals
@@ -52,6 +85,9 @@ module Contracts
     end
   end
 
+  # Takes a variable number of contracts.
+  # The contract passes if exactly one of those contracts pass.
+  # Example: <tt>Xor[Fixnum, Float]</tt>
   class Xor < CallableClass
     def initialize(*vals)
       @vals = vals
@@ -70,6 +106,9 @@ module Contracts
     end
   end  
 
+  # Takes a variable number of contracts.
+  # The contract passes if all contracts pass.
+  # Example: <tt>And[Fixnum, Float]</tt>  
   class And < CallableClass
     def initialize(*vals)
       @vals = vals
@@ -87,6 +126,10 @@ module Contracts
     end
   end
 
+  # Takes a variable number of method names as symbols.
+  # The contract passes if the argument responds to all
+  # of those methods.
+  # Example: <tt>RespondsTo[:password, :credit_card]</tt>
   class RespondsTo < CallableClass
     def initialize(*meths)
       @meths = meths
@@ -103,6 +146,11 @@ module Contracts
     end
   end
 
+  # Takes a variable number of method names as symbols.
+  # Given an argument, all of those methods are called
+  # on the argument one by one. If they all return true,
+  # the contract passes.
+  # Example: <tt>Send[:valid?]</tt>
   class Send < CallableClass
     def initialize(*meths)
       @meths = meths
@@ -119,6 +167,8 @@ module Contracts
     end  
   end
 
+  # Takes a class +A+. If argument.is_a? +A+, the contract passes.
+  # Example: <tt>IsA[Numeric]</tt>
   class IsA < CallableClass
     def initialize(cls)
       @cls = cls
@@ -133,6 +183,9 @@ module Contracts
     end
   end
 
+  # Takes a variable number of contracts. The contract
+  # passes if all of those contracts fail for the given argument.
+  # Example: <tt>Not[nil]</tt>
   class Not < CallableClass
     def initialize(*vals)
       @vals = vals
@@ -150,6 +203,10 @@ module Contracts
     end
   end
 
+  # Takes a contract. The related argument must be an array.
+  # Checks the contract against every element of the array.
+  # If it passes for all elements, the contract passes.
+  # Example: <tt>ArrayOf[Num]</tt>
   class ArrayOf < CallableClass
     def initialize(contract)
       @contract = contract
@@ -166,4 +223,19 @@ module Contracts
       "an array of #{@contract}"
     end
   end
+
+  # Used for <tt>*args</tt> (variadic functions). Takes a contract
+  # and uses it to validate every element passed in
+  # through <tt>*args</tt>.
+  # Example: <tt>Args[Or[String, Num]]</tt>
+  class Args < CallableClass
+    attr_reader :contract
+    def initialize(contract)
+      @contract = contract
+    end
+
+    def to_s
+      "Args[#{@contract}]"
+    end
+  end  
 end

data/lib/contracts.rb

@@ -5,7 +5,12 @@ class Class
   include MethodDecorators
 end
 
-
+# This is the main Contract class. When you write a new contract, you'll
+# write it as:
+#
+#   Contract [contract names]
+#
+# This class also provides useful callbacks and a validation method.
 class Contract < Decorator
   attr_accessor :contracts, :klass, :method
   decorator_name :contract
@@ -13,87 +18,59 @@ class Contract < Decorator
     @klass, @method, @contracts = klass, method, contracts
   end
 
-  def self.mkerror(validates, arg, contract)
-    if validates
-      [true, {}]
-    else
-      [false, { :arg => arg, :contract => contract }]
-    end
-  end
-
+  # Given a hash, prints out a failure message.
+  # This function is used by the default #failure_callback method
+  # and uses the hash passed into the failure_callback method.
   def self.failure_msg(data)
-   # TODO __file__ and __line__ won't work in Ruby 1.9.
-   # It provides a source_location method instead.
    expected = if data[:contract].to_s == ""
                 data[:contract].inspect
               else
                 data[:contract].to_s
               end
+
+    if RUBY_VERSION =~ /^1\.8/
+      position = data[:method].__file__ + ":" + data[:method].__line__.to_s
+    else
+      file, line = data[:method].source_location
+      position = file + ":" + line.to_s
+    end
+   
 %{Contract violation:
     Expected: #{expected},
     Actual: #{data[:arg].inspect}
     Value guarded in: #{data[:class]}::#{data[:method].name}
     With Contract: #{data[:contracts].map { |t| t.is_a?(Class) ? t.name : t.class.name }.join(", ") }
-    At: #{data[:method].__file__}:#{data[:method].__line__} }
+    At: #{position} }
   end
+
+  # Callback for when a contract fails. By default it raises
+  # an error and prints detailed info about the contract that
+  # failed. You can also monkeypatch this callback to do whatever
+  # you want...log the error, send you an email, print an error
+  # message, etc.
+  #
+  # Example of monkeypatching:
+  #
+  #   Contract.failure_callback(data)
+  #     puts "You had an error!"
+  #     puts failure_msg(data)
+  #     exit
+  #   end
   def self.failure_callback(data)
     raise failure_msg(data)
   end
 
+  # Callback for when a contract succeeds. Does nothing by default.
   def self.success_callback(data)
   end  
 
-  def self.validate_hash(arg, contract)
-    arg.keys.each do |k|
-      result, info = validate(arg[k], contract[k])
-      return [result, info] unless result
-    end
-  end
-
-  def self.validate_proc(arg, contract)
-    mkerror(contract[arg], arg, contract)
-  end
-
-  def self.validate_class(arg, contract)
-    valid = if contract.respond_to? :valid?
-              contract.valid? arg
-            else
-              contract == arg.class
-            end
-    mkerror(valid, arg, contract)
-  end
-
-  def self.validate_all(args, contracts, klass, method)
-    if args.size > contracts.size - 1
-      # *args
-      if contracts[-2].is_a? Args
-        while contracts.size < args.size + 1
-          contracts.insert(-2, contracts[-2].dup)
-        end
-      else
-        raise %{The number of arguments doesn't match the number of contracts.
-Did you forget to write a contract for the return value of the function?
-Or if you want a variable number of arguments using *args, use the Args contract.
-Args: #{args.inspect}
-Contracts: #{contracts.map { |t| t.is_a?(Class) ? t.name : t.class.name }.join(", ")}}
-      end
-    end
-
-    args.zip(contracts).each do |arg, contract|
-      validate(arg, contract, klass, method, contracts)
-    end
-  end
-
-  def self.validate(arg, contract, klass, method, contracts)
-    result, _ = valid?(arg, contract)
-    if result
-      success_callback({:arg => arg, :contract => contract, :class => klass, :method => method, :contracts => contracts})
-    else
-      failure_callback({:arg => arg, :contract => contract, :class => klass, :method => method, :contracts => contracts})
-    end
-  end
-
-  # arg to method -> contract it should satisfy -> (Boolean, metadata)
+  # Used to verify if an argument satisfies a contract.
+  #
+  # Takes: an argument and a contract.
+  #
+  # Returns: a tuple: [Boolean, metadata]. The boolean indicates
+  # whether the contract was valid or not. If it wasn't, metadata
+  # contains some useful information about the failure.
   def self.valid?(arg, contract)
     case contract
     when Class
@@ -111,7 +88,7 @@ Contracts: #{contracts.map { |t| t.is_a?(Class) ? t.name : t.class.name }.join("
       # e.g. { :a => Num, :b => String }
       return mkerror(false, arg, contract) unless arg.is_a?(Hash)
       validate_hash(arg, contract)
-    when Args
+    when Contracts::Args
       valid? arg, contract.contract
     else
       if contract.respond_to? :valid?
@@ -123,22 +100,78 @@ Contracts: #{contracts.map { |t| t.is_a?(Class) ? t.name : t.class.name }.join("
   end
 
   def call(this, *args, &blk)
-    Contract.validate_all(args, @contracts, @klass, @method)
+    _args = blk ? args + [blk] : args
+    if _args.size != @contracts.size - 1
+      # so it's not *args
+      if !@contracts[-2].is_a? Contracts::Args
+        raise %{The number of arguments doesn't match the number of contracts.
+Did you forget to write a contract for the return value of the function?
+Or if you want a variable number of arguments using *args, use the Args contract.
+Args: #{args.inspect}
+Contracts: #{@contracts.map { |t| t.is_a?(Class) ? t.name : t.class.name }.join(", ")}}
+      end
+    end    
+    Contract.validate_all(_args, @contracts[0, @contracts.size - 1], @klass, @method)
+
     result = @method.bind(this).call(*args, &blk)
+    
     if args.size == @contracts.size - 1
       Contract.validate(result, @contracts[-1], @klass, @method, @contracts)
     end
     result
   end
-end
 
-class Args < Contracts::CallableClass
-  attr_reader :contract
-  def initialize(contract)
-    @contract = contract
+  private
+
+  def self.mkerror(validates, arg, contract)
+    if validates
+      [true, {}]
+    else
+      [false, { :arg => arg, :contract => contract }]
+    end
   end
 
-  def to_s
-    "Args[#{@contract}]"
+  def self.validate_hash(arg, contract)
+    arg.keys.each do |k|
+      result, info = validate(arg[k], contract[k])
+      return [result, info] unless result
+    end
+  end
+
+  def self.validate_proc(arg, contract)
+    mkerror(contract[arg], arg, contract)
+  end
+
+  def self.validate_class(arg, contract)
+    valid = if contract.respond_to? :valid?
+              contract.valid? arg
+            else
+              contract == arg.class
+            end
+    mkerror(valid, arg, contract)
+  end
+
+  def self.validate_all(args, contracts, klass, method)
+    # we assume that any mismatch in # of args/contracts
+    # has been checked befoer this point.
+    if args.size != contracts.size
+      # assumed: contracts[-1].is_a? Args
+      while contracts.size < args.size
+        contracts << contracts[-1].dup
+      end
+    end
+
+    args.zip(contracts).each do |arg, contract|
+      validate(arg, contract, klass, method, contracts)
+    end
+  end
+
+  def self.validate(arg, contract, klass, method, contracts)
+    result, _ = valid?(arg, contract)
+    if result
+      success_callback({:arg => arg, :contract => contract, :class => klass, :method => method, :contracts => contracts})
+    else
+      failure_callback({:arg => arg, :contract => contract, :class => klass, :method => method, :contracts => contracts})
+    end
   end
 end

data/lib/test.rb

@@ -24,8 +24,6 @@ class Object
     func.call
   end
 
-  # thinks there are too many args, throws error
-  # sidenote: there should be a check to make sure the # of args and contracts match up.
   Contract Args[Num], Num
   def sum(*vals)
     vals.inject(0) do |acc, v|
@@ -38,4 +36,4 @@ run {
   puts "hi!"
 }
 
-puts add(1, 2)
+puts sum(1, 2, 3, 4)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: contracts
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 25
   prerelease: false
   segments: 
   - 0
   - 0
-  - 2
-  version: 0.0.2
+  - 3
+  version: 0.0.3
 platform: ruby
 authors: 
 - Aditya Bhargava