contracts 0.4 → 0.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 77eb6f2fcb9b44586ae85de49add3fff7e1ece96
+  data.tar.gz: 43d47be3ae6f1b13b997dde2ba6701b5578f84a8
+SHA512:
+  metadata.gz: adaf871d3c827fcfad8b1ea3731d34ddc5023ab4d952a668c797e89bff7c798c1464db1acf80ae1eb446867ba817e56fc3be0c9401dd3e35d6aedea54db69c52
+  data.tar.gz: 297cc7359bf60acac92450b4f2c1a96bae8e845dedf3f088b01f86e7271f2d312d4449d2c908a5ebacadd46f1f9f2031a4ee5eccd8b35bf35d3420d5b95a821c

data/Gemfile

@@ -0,0 +1,12 @@
+source "http://rubygems.org"
+
+gemspec
+
+group :test do
+  gem "rspec"
+end
+
+group :development do
+  gem "method_profiler"
+  gem "ruby-prof"
+end

data/Gemfile.lock

@@ -0,0 +1,34 @@
+PATH
+  remote: .
+  specs:
+    contracts (0.4)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.2.5)
+    hirb (0.7.2)
+    method_profiler (2.0.1)
+      hirb (>= 0.6.0)
+    rspec (3.1.0)
+      rspec-core (~> 3.1.0)
+      rspec-expectations (~> 3.1.0)
+      rspec-mocks (~> 3.1.0)
+    rspec-core (3.1.7)
+      rspec-support (~> 3.1.0)
+    rspec-expectations (3.1.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.1.0)
+    rspec-mocks (3.1.3)
+      rspec-support (~> 3.1.0)
+    rspec-support (3.1.2)
+    ruby-prof (0.15.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  contracts!
+  method_profiler
+  rspec
+  ruby-prof

data/README.md

@@ -0,0 +1,75 @@
+# contracts.ruby
+
+[![Build Status](https://travis-ci.org/egonSchiele/contracts.ruby.png?branch=master)](https://travis-ci.org/egonSchiele/contracts.ruby)
+
+Contracts let you clearly – even beautifully – express how your code behaves, and free you from writing tons of boilerplate, defensive code.
+
+You can think of contracts as `assert` on steroids.
+
+## Installation
+
+    gem install contracts
+
+## Hello World
+
+A contract is one line of code that you write above a method definition. It validates the arguments to the method, and validates the return value of the method.
+
+Here is a simple contract:
+
+```ruby
+  Contract Num => Num
+  def double(x)
+```
+
+This says that double expects a number and returns a number. Here's the full code:
+
+```ruby
+require 'contracts'
+include Contracts
+
+Contract Num => Num
+def double(x)
+  x * 2
+end
+
+puts double("oops")
+```
+
+Save this in a file and run it. Notice we are calling `double` with `"oops"`, which is not a number. The contract fails with a detailed error message:
+
+    ./contracts.rb:34:in `failure_callback': Contract violation: (RuntimeError)
+        Expected: Contracts::Num,
+        Actual: "oops"
+        Value guarded in: Object::double
+        With Contract: Contracts::Num, Contracts::Num
+        At: main.rb:6
+        ...stack trace...
+
+Instead of throwing an exception, you could log it, print a clean error message for your user...whatever you want. contracts.ruby is here to help you handle bugs better, not to get in your way.
+
+## Tutorial
+
+Check out [this awesome tutorial](http://egonschiele.github.com/contracts.ruby).
+
+## Use Cases
+
+Check out [this screencast](https://vimeo.com/85883356).
+
+## Performance
+
+Using contracts.ruby results in very little slowdown. Check out [this blog post](http://adit.io/posts/2013-03-04-How-I-Made-My-Ruby-Project-10x-Faster.html#seconds-6) for more info.
+
+**Q.** What Rubies can I use this with?
+
+**A.** It's been tested with `1.8.7`, `1.9.2`, `1.9.3`, `2.0.0`, `2.1`, `2.2`, and `jruby` (both 1.8 and 1.9 modes).
+
+If you're using the library, please [let me know](https://github.com/egonSchiele) what project you're using it on :)
+
+## Credits
+
+Inspired by [contracts.coffee](http://disnetdev.com/contracts.coffee/).
+
+Copyright 2012 [Aditya Bhargava](http://adit.io).
+Major improvements by [Alexey Fedorov](https://github.com/waterlink).
+
+BSD Licensed.

data/TODO.markdown

@@ -0,0 +1,6 @@
+- maybe make some screencasts
+
+- you can now do something like Haskell's quickcheck. Every contract has a method 'test_data' or something. You can use that data to automatically check methods with contracts to make sure they are correct.
+  - http://www.cse.chalmers.se/~rjmh/QuickCheck/manual.html
+  - for stuff like the Not contract, should I make a standard set of classes to check those functions with? Would that be useful at all?
+  - also write specs for this stuff

data/TUTORIAL.md

@@ -0,0 +1,485 @@
+# The contracts.ruby tutorial
+
+## Introduction
+
+contracts.ruby brings code contracts to the Ruby language. Code contracts allow you make some assertions about your code, and then checks them to make sure they hold. This lets you
+
+- catch bugs faster
+- make it very easy to catch certain types of bugs
+- make sure that the user gets proper messaging when a bug occurs.
+
+## Installation
+
+    gem install contracts
+
+## Basics
+
+A simple example:
+
+```ruby
+Contract Num, Num => Num
+def add(a, b)
+  a + b
+end
+```
+
+Here, the contract is `Contract Num, Num => Num`. This says that the `add` function takes two numbers and returns a number.
+
+Copy this code into a file and run it:
+
+```ruby
+require 'contracts'
+include Contracts
+
+Contract Num, Num => Num
+def add(a, b)
+  a + b
+end
+
+puts add(1, "foo")
+```
+
+You'll see a detailed error message like so:
+
+    ./contracts.rb:60:in `failure_callback': Contract violation: (RuntimeError)
+        Expected: Contracts::Num,
+        Actual: "foo"
+        Value guarded in: Object::add
+        With Contract: Contracts::Num, Contracts::Num
+        At: foo.rb:6
+
+That tells you that your contract was violated! `add` expected a `Num`, and got a string (`"foo"`) instead.
+By default, an exception is thrown when a contract fails. This can be changed to do whatever you want. More on this later.
+
+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 put `include Contracts` at the top of your file, but beware that they will pollute your namespace with new class names.
+
+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).
+
+## More Examples
+
+### Hello, World
+
+```ruby
+Contract String => nil
+def hello(name)
+  puts "hello, #{name}!"
+end
+```
+
+You always need to specify a contract for the return value. In this example, `hello` doesn't return anything, so the contract is `nil`. Now you know that you can use a constant like `nil` as the end of a contract. Valid values for a contract are:
+
+- the name of a class (like `String` or `Fixnum`)
+- a constant (like `nil` or `1`)
+- a `Proc` that takes a value and returns true or false to indicate whether the contract passed or not
+- a class that responds to the `valid?` class method (more on this later)
+- an instance of a class that responds to the `valid?` method (more on this later)
+
+### A Double Function
+
+```ruby
+Contract Or[Fixnum, Float] => Or[Fixnum, Float]
+def double(x)
+  2 * x
+end
+```
+
+Sometimes you want to be able to choose between a few contracts. `Or` takes a variable number of contracts and checks the argument against all of them. If it passes for any of the contracts, then the `Or` contract passes.
+This introduces some new syntax. One of the valid values for a contract is an instance of a class that responds to the `valid?` method. This is what `Or[Fixnum, Float]` is. The longer way to write it would have been:
+
+```ruby
+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
+
+```ruby
+Contract Or[Fixnum, Float] => Or[Fixnum, Float]
+```
+
+or
+
+```ruby
+Contract Or.new(Fixnum, Float) => Or.new(Fixnum, Float)
+```
+
+whichever you prefer. They both mean the same thing here: make a new instance of `Or` with `Fixnum` and `Float`. Use that instance to validate the argument.
+
+### A Product Function
+
+```ruby
+Contract ArrayOf[Num] => Num
+def product(vals)
+  total = 1
+  vals.each do |val|
+    total *= val
+  end
+  total
+end
+```
+
+This contract uses the `ArrayOf` contract. Here's how `ArrayOf` works: it takes a contract. It expects the argument to be a list. Then it checks every value in that list to see if it satisfies that contract.
+
+```ruby
+# passes
+product([1, 2, 3, 4])
+
+# fails
+product([1, 2, 3, "foo"])
+```
+
+### Another Product Function
+
+```ruby
+Contract Args[Num] => Num
+def product(*vals)
+  total = 1
+  vals.each do |val|
+    total *= val
+  end
+  total
+end
+```
+
+This function uses varargs (`*args`) instead of an array. To make a contract on varargs, use the `Args` contract. It takes one contract as an argument and uses it to validate every element passed in through `*args`. So for example,
+
+`Args[Num]` means they should all be numbers.
+
+`Args[Or[Num, String]]` means they should all be numbers or strings.
+
+`Args[Any]` means all arguments are allowed (`Any` is a contract that passes for any argument).
+
+### Contracts On Arrays
+
+If an array is one of the arguments and you know how many elements it's going to have, you can put a contract on it:
+
+```ruby
+# a function that takes an array of two elements...a person's age and a person's name.
+Contract [Num, String] => nil
+def person(data)
+  p data
+end
+```
+
+If you don't know how many elements it's going to have, use `ArrayOf`.
+
+### Contracts On Hashes
+
+Here's a contract that requires a Hash. We can put contracts on each of the keys:
+
+```ruby
+# note the parentheses around the hash; without those you would get a syntax error
+Contract ({ :age => Num, :name => String }) => nil
+def person(data)
+  p data
+end
+```
+
+Then if someone tries to call the function with bad data, it will fail:
+
+```ruby
+# error: age can't be nil!
+person({:name => "Adit", :age => nil})
+```
+
+You don't need to put a contract on every key. So this call would succeed:
+
+```ruby
+person({:name => "Adit", :age => 42, :foo => "bar"})
+```
+
+even though we don't specify a type for `:foo`.
+
+Peruse this contract on the keys and values of a Hash.
+
+```ruby
+Contract HashOf[Symbol, Num] => Num
+def give_largest_value(hsh)
+  hsh.values.max
+end
+```
+Which you use like so:
+```ruby
+# succeeds
+give_largest_value(a: 1, b: 2, c: 3) # returns 3
+
+# fails
+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.
+
+Here's a `map` function that requires an array of numbers, and a function that takes a number and returns a number:
+
+```ruby
+Contract ArrayOf[Num], Func[Num => Num] => ArrayOf[Num]
+def map(arr, func)
+  ret = []
+  arr.each do |x|
+    ret << func[x]
+  end
+  ret
+end
+```
+
+This will add the contract `Num => Num` on `func`. Try it 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.
+```
+
+### Returning Multiple Values
+Treat the return value as an array. For example, here's a function that returns two numbers:
+
+```ruby
+Contract Num => [Num, Num]
+def mult(x)
+  return x, x+1
+end
+```
+
+## Synonyms For Contracts
+
+If you use a contract a lot, it's a good idea to give it a meaningful synonym that tells the reader more about what your code returns. For example, suppose you have many functions that return a `Hash` or `nil`. If a `Hash` is returned, it contains information about a person. Your contact might look like this:
+
+```ruby
+Contract String => Or[Hash, nil]
+def some_func(str)
+```
+
+You can make your contract more meaningful with a synonym:
+
+```ruby
+# the synonym
+Person = Or[Hash, nil]
+
+# use the synonym here
+Contract String => Person
+def some_func(str)
+```
+
+Now you can use `Person` wherever you would have used `Or[Hash, nil]`. Your code is now cleaner and more clearly says what the function is doing.
+
+## Defining Your Own Contracts
+
+Contracts are very easy to define. To re-iterate, there are 5 kinds of contracts:
+
+- the name of a class (like `String` or `Fixnum`)
+- a constant (like `nil` or `1`)
+- a `Proc` that takes a value and returns true or false to indicate whether the contract passed or not
+- a class that responds to the `valid?` class method (more on this later)
+- an instance of a class that responds to the `valid?` method (more on this later)
+
+The first two don't need any extra work to define: you can just use any constant or class name in your contract and it should just work. Here are examples for the rest:
+
+### A Proc
+
+```ruby
+Contract lambda { |x| x.is_a? Numeric } => Num
+def double(x)
+```
+
+The lambda takes one parameter: the argument that is getting passed to the function. It checks to see if it's a `Numeric`. If it is, it returns true. Otherwise it returns false.
+It's not good practice to write a lambda right in your contract...if you find yourself doing it often, write it as a class instead:
+
+### A Class With `valid?` As a Class Method
+
+Here's how the `Num` class is defined. It does exactly what the `lambda` did in the previous example:
+
+```ruby
+class Num
+  def self.valid? val
+    val.is_a? Numeric
+  end
+end
+```
+
+The `valid?` class method takes one parameter: the argument that is getting passed to the function. It returns true or false.
+
+### A Class With `valid?` As an Instance Method
+
+Here's how the `Or` class is defined:
+
+```ruby
+class Or < CallableClass
+  def initialize(*vals)
+    @vals = vals
+  end
+
+  def valid?(val)
+    @vals.any? do |contract|
+      res, _ = Contract.valid?(val, contract)
+      res
+    end
+  end
+end
+```
+
+The `Or` contract takes a sequence of contracts, and passes if any of them pass. It uses `Contract.valid?` to validate the value against the contracts.
+
+This class inherits from `CallableClass`, which allows us to use `[]` when using the class:
+
+```ruby
+Contract Or[Fixnum, Float] => Num
+def double(x)
+  2 * x
+end
+```
+
+Without `CallableClass`, we would have to use `.new` instead:
+
+```ruby
+Contract Or.new(Fixnum, Float) => Num
+def double(x)
+# etc
+```
+
+You can use `CallableClass` in your own contracts to make them callable using `[]`.
+
+## Customizing Error Messages
+
+When a contract fails, part of the error message prints the contract:
+
+    ...
+    Expected: Contracts::Num,
+    ...
+
+You can customize this message by overriding the `to_s` method on your class or proc. For example, suppose we overrode `Num`'s `to_s` method:
+
+```ruby
+def Num.to_s
+  "a number please"
+end
+```
+
+Now the error says:
+
+    ...
+    Expected: a number please,
+    ...
+
+## Failure Callbacks
+
+Supposing you don't want contract failures to become exceptions. You run a popular website, and when there's a contract exception you would rather log it and continue than throw an exception and break your site.
+
+contracts.ruby provides a failure callback that gets called when a contract fails. For example, here we log every failure instead of raising an error:
+
+```ruby
+Contract.override_failure_callback do |data|
+  puts "You had an error"
+  puts failure_msg(data)
+end
+```
+
+`failure_msg` is a function that prints out information about the failure. Your failure callback gets a hash with the following values:
+
+    {
+      :arg => the argument to the method,
+      :contract => the contract that got violated,
+      :class => the method's class,
+      :method => the method,
+      :contracts => the contract object
+    }
+
+If your failure callback returns `false`, the method that the contract is guarding will not be called (the default behaviour).
+
+## Disabling contracts
+
+If you want to disable contracts, set the `NO_CONTRACTS` environment variable. This will disable contracts completely and you won't have a performance hit.
+
+## Method overloading
+
+You can use contracts for method overloading! For example, here's a factorial function without method overloading:
+
+```ruby
+Contract Num => Num
+def fact x
+  if x == 1
+    x
+  else
+    x * fact(x - 1)
+  end
+end
+```
+
+Here it is again, re-written with method overloading:
+
+```ruby
+Contract 1 => 1
+def fact x
+  x
+end
+
+Contract Num => Num
+def fact x
+  x * fact(x - 1)
+end
+```
+
+For an argument, each function will be tried in order. The first function that doesn't raise a `ContractError` will be used. So in this case, if x == 1, the first function will be used. For all other values, the second function will be used.
+
+## Invariants
+
+Invariants are conditions on objects that should always hold. If after any method call on given object, any of the Invariants fails, then Invariant violation error will be generated.
+
+**NOTE**: Only methods with contracts will be affected.
+
+A simple example:
+
+```ruby
+class MyBirthday < Struct.new(:day, :month)
+  include Contracts
+  include Contracts:Invariants
+
+  Invariant(:day) { 1 <= day && day <= 31 }
+  Invariant(:month) { 1 <= month && month <= 12 }
+
+  Contract None => Fixnum
+  def silly_next_day!
+    self.day += 1
+  end
+end
+
+birthday = MyBirthday.new(31, 12)
+birthday.silly_next_day!
+```
+
+If you run it, last line will generate invariant violation:
+
+```ruby
+./invariant.rb:38:in `failure_callback': Invariant violation: (RuntimeError)
+   Expected: day condition to be true
+   Actual: false
+   Value guarded in: MyBirthday::silly_next_day!
+   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.
+
+## Misc
+
+Please submit any bugs [here](https://github.com/egonSchiele/contracts.ruby/issues) and I'll try to get them resolved ASAP!
+
+See any mistakes in this tutorial? I try to make it bug-free, but they can creep in. [File an issue](https://github.com/egonSchiele/contracts.ruby/issues).
+
+If you're using the library, please [let me know](https://github.com/egonSchiele) what project you're using it on :)
+
+See the [wiki](https://github.com/egonSchiele/contracts.ruby/wiki) for more info.
+
+Happy Coding!