contracts 0.7 → 0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 065efb039a13c2917e10fc96dd77dd2fe858bc08
-  data.tar.gz: 98f3253cc22a5da08f4d3414361db7218c438107
+  metadata.gz: 124deda42f022fb31b53dc3389bd51ff85860d30
+  data.tar.gz: 8ea3f78006952432311338880c563cdbdf327f33
 SHA512:
-  metadata.gz: b8486b6e85a38517371403aa4cb7b3e6795ee01a2170e663eab8ff772507971a8e7bfa050b3b98dabb8fc60772153f544a14e9e419025a7c899ebda682b82338
-  data.tar.gz: 44cfdb1101dbe48269e88c5758196e2bc11ce2238f70a791c0f62aa36d0754994dd00f49f4c8e0d98cca43a4b254a085cc83af3673964b6e31198ba66c14527e
+  metadata.gz: 644753384168c11234cd6a77b6d64384cc0f6fca93f3614e4d71ae3629ec7d05d85b02bfbd0150b3db21f94e04fe980f784d0e4decee0e5dcfd912f66526b2fb
+  data.tar.gz: 8a92fd259e98d4320fe5a4a52cc0d2d6cd01e7362b0fc6ed809001ef4e4618a7d1fab4513b2cb2db5946028fdf7a1c745e13491bf9d1e4e897f2dfe39446aafe

data/Gemfile

@@ -4,6 +4,7 @@ gemspec
 
 group :test do
   gem "rspec"
+  gem "rubocop", "~> 0.29", :platform => [:ruby_20, :ruby_21]
 end
 
 group :development do

data/Gemfile.lock

@@ -1,15 +1,22 @@
 PATH
   remote: .
   specs:
-    contracts (0.6)
+    contracts (0.7)
 
 GEM
   remote: http://rubygems.org/
   specs:
+    ast (2.0.0)
+    astrolabe (1.3.0)
+      parser (>= 2.2.0.pre.3, < 3.0)
     diff-lcs (1.2.5)
     hirb (0.7.2)
     method_profiler (2.0.1)
       hirb (>= 0.6.0)
+    parser (2.2.0.3)
+      ast (>= 1.1, < 3.0)
+    powerpack (0.1.0)
+    rainbow (2.0.0)
     rspec (3.1.0)
       rspec-core (~> 3.1.0)
       rspec-expectations (~> 3.1.0)
@@ -22,7 +29,14 @@ GEM
     rspec-mocks (3.1.3)
       rspec-support (~> 3.1.0)
     rspec-support (3.1.2)
+    rubocop (0.29.1)
+      astrolabe (~> 1.3)
+      parser (>= 2.2.0.1, < 3.0)
+      powerpack (~> 0.1)
+      rainbow (>= 1.99.1, < 3.0)
+      ruby-progressbar (~> 1.4)
     ruby-prof (0.15.2)
+    ruby-progressbar (1.7.5)
 
 PLATFORMS
   ruby
@@ -31,4 +45,5 @@ DEPENDENCIES
   contracts!
   method_profiler
   rspec
+  rubocop (~> 0.29)
   ruby-prof

data/README.md

@@ -1,6 +1,4 @@
-# contracts.ruby
-
-[![Build Status](https://travis-ci.org/egonSchiele/contracts.ruby.png?branch=master)](https://travis-ci.org/egonSchiele/contracts.ruby)
+# contracts.ruby [![Build Status](https://travis-ci.org/egonSchiele/contracts.ruby.png?branch=master)](https://travis-ci.org/egonSchiele/contracts.ruby) [![Join the chat at https://gitter.im/egonSchiele/contracts.ruby](https://img.shields.io/badge/gitter-join%20chat-brightgreen.svg)](https://gitter.im/egonSchiele/contracts.ruby)
 
 Contracts let you clearly – even beautifully – express how your code behaves, and free you from writing tons of boilerplate, defensive code.
 
@@ -65,11 +63,21 @@ Using contracts.ruby results in very little slowdown. Check out [this blog post]
 
 If you're using the library, please [let me know](https://github.com/egonSchiele) what project you're using it on :)
 
+## Testimonials
+
+> Contracts literally saves us hours of pain at Snowplow every day
+
+Alexander Dean, creator of [Snowplow](https://github.com/snowplow/snowplow)
+
+> Contracts caught a bug that saved us several hundred dollars. It took less than 30 seconds to add the contract.
+
+Michael Tomer
+
 ## Credits
 
 Inspired by [contracts.coffee](http://disnetdev.com/contracts.coffee/).
 
-Copyright 2012 [Aditya Bhargava](http://adit.io).
+Copyright 2012-2015 [Aditya Bhargava](http://adit.io).
 Major improvements by [Alexey Fedorov](https://github.com/waterlink).
 
 BSD Licensed.

data/TUTORIAL.md

@@ -59,17 +59,33 @@ You can also see the contract for a function with the `functype` method:
     functype(:add)
     => "add :: Num, Num => Num"
 
-This can be useful if you're in a repl and want to figure out how a function should be used.
-
-## Builtin Contracts
-
-`Num` is one of the builtin contracts that contracts.ruby comes with. The builtin contracts are in the `Contracts` namespace. The easiest way to use them is to include the `Contracts` module in your class/module.
-
-contracts.ruby comes with a lot of builtin contracts, including:
-
-    Num, Pos, Neg, Any, None, Or, Xor, And, Not, RespondTo, Send, Exactly, ArrayOf, HashOf, Bool, Maybe
-
-To see all the builtin contracts and what they do, check out the [rdoc](http://rubydoc.info/gems/contracts/Contracts).
+This can be useful if you're in a REPL and want to figure out how a function should be used.
+
+## Built-in Contracts
+
+`Num` is one of the built-in contracts that contracts.ruby comes with. The built-in contracts are in the `Contracts` namespace. The easiest way to use them is to include the `Contracts` module in your class/module.
+
+contracts.ruby comes with a lot of built-in contracts, including the following:
+
+* [`Num`](http://www.rubydoc.info/gems/contracts/Contracts/Num) – checks that the argument is `Numeric`
+* [`Pos`](http://www.rubydoc.info/gems/contracts/Contracts/Pos) – checks that the argument is a positive number
+* [`Neg`](http://www.rubydoc.info/gems/contracts/Contracts/Neg) – checks that the argument is a negative number
+* [`Nat`](http://www.rubydoc.info/gems/contracts/Contracts/Nat) – checks that the argument is a natural number
+* [`Bool`](http://www.rubydoc.info/gems/contracts/Contracts/Bool) – checks that the argument is `true` or `false`
+* [`Any`](http://www.rubydoc.info/gems/contracts/Contracts/Any) – Passes for any argument. Use when the argument has no constraints.
+* [`None`](http://www.rubydoc.info/gems/contracts/Contracts/None) – Fails for any argument. Use when the method takes no arguments.
+* [`Or`](http://www.rubydoc.info/gems/contracts/Contracts/Or) – passes if any of the given contracts pass, e.g. `Or[Fixnum, Float]`
+* [`Xor`](http://www.rubydoc.info/gems/contracts/Contracts/Xor) – passes if exactly one of the given contracts pass, e.g. `Xor[Fixnum, Float]`
+* [`And`](http://www.rubydoc.info/gems/contracts/Contracts/And) – passes if all contracts pass, e.g. `And[Fixnum, Float]`
+* [`Not`](http://www.rubydoc.info/gems/contracts/Contracts/Not) – passes if all contracts fail for the given argument, e.g. `Not[nil]`
+* [`ArrayOf`](http://www.rubydoc.info/gems/contracts/Contracts/ArrayOf) – checks that the argument is an array, and all elements pass the given contract, e.g. `ArrayOf[Num]`
+* [`HashOf`](http://www.rubydoc.info/gems/contracts/Contracts/HashOf) – checks that the argument is a hash, and all keys and values pass the given contract, e.g. `HashOf[Symbol, String]`
+* [`Maybe`](http://www.rubydoc.info/gems/contracts/Contracts/Maybe) – passes if the argument is `nil`, or if the given contract passes
+* [`RespondTo`](http://www.rubydoc.info/gems/contracts/Contracts/RespondTo) – checks that the argument responds to all of the given methods, e.g. `RespondTo[:password, :credit_card]`
+* [`Send`](http://www.rubydoc.info/gems/contracts/Contracts/Send) – checks that all named methods return true, e.g. `Send[:valid?]`
+* [`Exactly`](http://www.rubydoc.info/gems/contracts/Contracts/Exactly) – checks that the argument has the given type, not accepting sub-classes, e.g. `Exactly[Numeric]`.
+
+To see all the built-in contracts and their full descriptions, check out the [RDoc](http://rubydoc.info/gems/contracts/Contracts).
 
 ## More Examples
 
@@ -106,7 +122,7 @@ This introduces some new syntax. One of the valid values for a contract is an in
 Contract Or.new(Fixnum, Float) => Or.new(Fixnum, Float)
 ```
 
-All the builtin contracts have overridden the square brackets (`[]`) to give the same functionality. So you could write
+All the built-in contracts have overridden the square brackets (`[]`) to give the same functionality. So you could write
 
 ```ruby
 Contract Or[Fixnum, Float] => Or[Fixnum, Float]
@@ -224,8 +240,26 @@ give_largest_value("a" => 1, 2 => 2, c: 3)
 
 ### Contracts On Functions
 
-If you're writing higher-order functions (functions that take functions as parameters) and want to write a contract for the passed-in function, you can!
-Use the `Func` contract. `Func` takes a contract as it's argument, and uses that contract on the function that you pass in.
+Lets say you are writing a simple map function:
+
+```ruby
+def map(arr, func)
+```
+
+`map` takes an array, and a function. Suppose you want to add a contract to this function. You could try this:
+
+```ruby
+Contract ArrayOf[Any], Proc => ArrayOf[Any]
+def map(arr, func)
+```
+
+This says that the second argument should be a `Proc`. You can call the function like so:
+
+```ruby
+p map([1, 2, 3], lambda { |x| x + 1 }) # works
+```
+
+But suppose you want to have a contract on the Proc too! Suppose you want to make sure that the Proc returns a number. Use the `Func` contract. `Func` takes a contract as it's argument, and uses that contract on the function that you pass in.
 
 Here's a `map` function that requires an array of numbers, and a function that takes a number and returns a number:
 
@@ -240,13 +274,24 @@ def map(arr, func)
 end
 ```
 
-This will add the contract `Num => Num` on `func`. Try it with these two examples:
+Earlier, we used `Proc`, which just says "make sure the second variable is a Proc". Now we are using `Func[Num => Num]`, which says "make sure the second variable is a Proc that takes a number and returns a number". Better!
+
+Try this map function with these two examples:
 
 ```ruby
 p map([1, 2, 3], lambda { |x| x + 1 }) # works
 p map([1, 2, 3], lambda { |x| "oops" }) # fails, the lambda returns a string.
 ```
 
+NOTE: This is not valid:
+
+```ruby
+Contract ArrayOf[Num], Func => ArrayOf[Num]
+def map(arr, &func)
+```
+
+Here I am using `Func` without specifying a contract, like `Func[Num => Num]`. That's not a legal contract. If you just want to validate that the second argument is a proc, use `Proc`.
+
 ### Returning Multiple Values
 Treat the return value as an array. For example, here's a function that returns two numbers:
 
@@ -491,8 +536,8 @@ class MyBirthday < Struct.new(:day, :month)
   include Contracts
   include Contracts::Invariants
 
-  Invariant(:day) { 1 <= day && day <= 31 }
-  Invariant(:month) { 1 <= month && month <= 12 }
+  invariant(:day) { 1 <= day && day <= 31 }
+  invariant(:month) { 1 <= month && month <= 12 }
 
   Contract None => Fixnum
   def silly_next_day!
@@ -514,7 +559,11 @@ If you run it, last line will generate invariant violation:
    At: main.rb:9
 ```
 
-Which means, that after `#silly_next_day!` all checks specified in `Invariant` statement will be verified, and if at least one fail, then Invariant violation error will be raised.
+Which means, that after `#silly_next_day!` all checks specified in `invariant` statement will be verified, and if at least one fail, then invariant violation error will be raised.
+
+## Auto-generate documentation using contracts
+
+If you are generating documentation for your code with [YARD](http://yardoc.org/), check out [yard-contracts](https://github.com/sfcgeorge/yard-contracts). It will automatically annotate your functions with contracts information. Instead of documenting each parameter for a function yourself, you can just add a contract and yard-contracts will generate the documentation for you!
 
 ## Misc
 

data/benchmarks/bench.rb

@@ -1,8 +1,8 @@
-require './lib/contracts'
-require 'benchmark'
-require 'rubygems'
-require 'method_profiler'
-require 'ruby-prof'
+require "./lib/contracts"
+require "benchmark"
+require "rubygems"
+require "method_profiler"
+require "ruby-prof"
 
 include Contracts
 
@@ -16,22 +16,22 @@ def contracts_add a, b
 end
 
 def explicit_add a, b
-  raise unless a.is_a?(Numeric)
-  raise unless b.is_a?(Numeric)
+  fail unless a.is_a?(Numeric)
+  fail unless b.is_a?(Numeric)
   c = a + b
-  raise unless c.is_a?(Numeric)
+  fail unless c.is_a?(Numeric)
   c
 end
 
 def benchmark
   Benchmark.bm 30 do |x|
-    x.report 'testing add' do
-      1000000.times do |_|
+    x.report "testing add" do
+      1_000_000.times do |_|
         add(rand(1000), rand(1000))
       end
     end
-    x.report 'testing contracts add' do
-      1000000.times do |_|
+    x.report "testing contracts add" do
+      1_000_000.times do |_|
         contracts_add(rand(1000), rand(1000))
       end
     end
@@ -46,20 +46,20 @@ def profile
   profilers << MethodProfiler.observe(Contracts::Decorator)
   profilers << MethodProfiler.observe(Contracts::Support)
   profilers << MethodProfiler.observe(UnboundMethod)
-  10000.times do |_|
+  10_000.times do |_|
     contracts_add(rand(1000), rand(1000))
   end
   profilers.each { |p| puts p.report }
 end
 
 def ruby_prof
-RubyProf.start
-    100000.times do |_|
-      contracts_add(rand(1000), rand(1000))
-    end
-result = RubyProf.stop
-printer = RubyProf::FlatPrinter.new(result)
-printer.print(STDOUT)
+  RubyProf.start
+  100_000.times do |_|
+    contracts_add(rand(1000), rand(1000))
+  end
+  result = RubyProf.stop
+  printer = RubyProf::FlatPrinter.new(result)
+  printer.print(STDOUT)
 end
 
 benchmark

data/benchmarks/invariants.rb

@@ -1,24 +1,34 @@
-require './lib/contracts'
-require 'benchmark'
-require 'rubygems'
-require 'method_profiler'
-require 'ruby-prof'
+require "./lib/contracts"
+require "benchmark"
+require "rubygems"
+require "method_profiler"
+require "ruby-prof"
 
-class Obj < Struct.new(:value)
+class Obj
   include Contracts
 
+  attr_accessor :value
+  def initialize value
+    @value = value
+  end
+
   Contract Num, Num => Num
   def contracts_add a, b
     a + b
   end
 end
 
-class ObjWithInvariants < Struct.new(:value)
+class ObjWithInvariants
   include Contracts
   include Contracts::Invariants
 
-  Invariant(:value_not_nil) { value != nil }
-  Invariant(:value_not_string) { !value.is_a?(String) }
+  invariant(:value_not_nil) { value != nil }
+  invariant(:value_not_string) { !value.is_a?(String) }
+
+  attr_accessor :value
+  def initialize value
+    @value = value
+  end
 
   Contract Num, Num => Num
   def contracts_add a, b
@@ -31,16 +41,16 @@ def benchmark
   obj_with_invariants = ObjWithInvariants.new(3)
 
   Benchmark.bm 30 do |x|
-    x.report 'testing contracts add' do
-      1000000.times do |_|
+    x.report "testing contracts add" do
+      1_000_000.times do |_|
         obj.contracts_add(rand(1000), rand(1000))
       end
     end
-    x.report 'testing contracts add with invariants' do
-      1000000.times do |_|
+    x.report "testing contracts add with invariants" do
+      1_000_000.times do |_|
         obj_with_invariants.contracts_add(rand(1000), rand(1000))
       end
-    end  
+    end
   end
 end
 
@@ -55,19 +65,19 @@ def profile
   profilers << MethodProfiler.observe(Contracts::Invariants::InvariantExtension)
   profilers << MethodProfiler.observe(UnboundMethod)
 
-  10000.times do |_|
+  10_000.times do |_|
     obj_with_invariants.contracts_add(rand(1000), rand(1000))
-  end  
+  end
 
   profilers.each { |p| puts p.report }
 end
 
 def ruby_prof
-  RubyProf.start  
+  RubyProf.start
 
   obj_with_invariants = ObjWithInvariants.new(3)
 
-  100000.times do |_|
+  100_000.times do |_|
     obj_with_invariants.contracts_add(rand(1000), rand(1000))
   end
 

data/benchmarks/io.rb

@@ -0,0 +1,62 @@
+require "./lib/contracts"
+require "benchmark"
+require "rubygems"
+require "method_profiler"
+require "ruby-prof"
+require "open-uri"
+
+include Contracts
+
+def download url
+  open("https://www.#{url}/").read
+end
+
+Contract String => String
+def contracts_download url
+  open("https://www.#{url}").read
+end
+
+@urls = %w{facebook.com google.com bing.com}
+
+def benchmark
+  Benchmark.bm 30 do |x|
+    x.report "testing download" do
+      100.times do |_|
+        download(@urls.sample)
+      end
+    end
+    x.report "testing contracts download" do
+      100.times do |_|
+        contracts_download(@urls.sample)
+      end
+    end
+  end
+end
+
+def profile
+  profilers = []
+  profilers << MethodProfiler.observe(Contract)
+  profilers << MethodProfiler.observe(Object)
+  profilers << MethodProfiler.observe(Contracts::MethodDecorators)
+  profilers << MethodProfiler.observe(Contracts::Decorator)
+  profilers << MethodProfiler.observe(Contracts::Support)
+  profilers << MethodProfiler.observe(UnboundMethod)
+  10.times do |_|
+    contracts_download(@urls.sample)
+  end
+  profilers.each { |p| puts p.report }
+end
+
+def ruby_prof
+  RubyProf.start
+  10.times do |_|
+    contracts_download(@urls.sample)
+  end
+  result = RubyProf.stop
+  printer = RubyProf::FlatPrinter.new(result)
+  printer.print(STDOUT)
+end
+
+benchmark
+profile
+ruby_prof if ENV["FULL_BENCH"] # takes some time