contracts-lite 0.14.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5a0087eb9cbfbfbac59abc12f636caccf3699b81
+  data.tar.gz: eb6161c0401a24b4a37ac8fff330de398198fd74
+SHA512:
+  metadata.gz: 681aa159502c17ae1dccc23060193b73cd70f81034a724398003edf886156ecd7c5e23199c53a1a5c1f90a0cd03257ace3de9733058c76c616d2e0af2356fb27
+  data.tar.gz: 170938443f38a9cbc575e1ae4261dc6365d44c7615108fc5cd25195af0554e8f4afc82395f04bdd17e9f0f4eff859d0a262a57a00c527f5ee01843ecb350cbc7

data/CHANGELOG.markdown

@@ -0,0 +1,80 @@
+## v0.15.0
+
+## v0.14.0
+- Enhancement: Add StrictHash contract - [Fyodor](https://github.com/cbrwizard) [#236](https://github.com/egonSchiele/contracts.ruby/pull/236)
+- Bugfix: dont fail if something other than a hash is passed to a KeywordArgs - [Dan Padilha](https://github.com/dpad) [#234](https://github.com/egonSchiele/contracts.ruby/pull/234)
+- LICENSE ADDED: Simplified BSD (same as what is specified in the readme) - [Charles Dale](https://github.com/chuckd) [#233](https://github.com/egonSchiele/contracts.ruby/pull/233)
+- Bugfix: fix constant looking when including a module that includes contracts (requires removing the check to see if contracts is already included) - [Aditya Bhargava](https://github.com/egonSchiele) [#232](https://github.com/egonSchiele/contracts.ruby/pull/232)
+- Bugfix for err case when KeywordArgs and Proc are used together - [Aditya Bhargava](https://github.com/egonSchiele) [#230](https://github.com/egonSchiele/contracts.ruby/pull/230)
+- Enhancement: Add DescendantOf contract - [Miguel Palhas](https://github.com/naps62) [#227](https://github.com/egonSchiele/contracts.ruby/pull/227)
+
+## v0.13.0
+
+- Enhancement: Add support for Ruby 2.3 - [Oleksii Fedorov](https://github.com/waterlink) [#216](https://github.com/egonSchiele/contracts.ruby/pull/216)
+- Enhancement: Added Int, Nat and NatPos builtin contracts - [Simon George](https://github.com/sfcgeorge) [#212](https://github.com/egonSchiele/contracts.ruby/pull/212)
+- Bugfix: Allow contracts on singleton of subclass - [Oleksii Federov](https://github.com/waterlink) [#211](https://github.com/egonSchiele/contracts.ruby/pull/211)
+
+## v0.12.0
+
+- Feature: add `Regexp` validator - [Gert Goet](https://github.com/eval) [#196](https://github.com/egonSchiele/contracts.ruby/pull/196)
+- Docs: bootstrap cucumber/aruba/relish setup - [Oleksii Fedorov](https://github.com/waterlink) [#195](https://github.com/egonSchiele/contracts.ruby/pull/195)
+- Bugfix: allow to `extend` module, that has `Contracts` or `Contracts::Core` included without harming current module/class `Contracts` functionality, see: [#176](https://github.com/egonSchiele/contracts.ruby/issues/176) - [Oleksii Fedorov](https://github.com/waterlink) [#198](https://github.com/egonSchiele/contracts.ruby/pull/198)
+- Enhancement: add `include Contracts::Builtin` to allow users to use builtin contracts without `Contracts::` prefix together with `include Contracts::Core` - [PikachuEXE](https://github.com/PikachuEXE) [#199](https://github.com/egonSchiele/contracts.ruby/pull/199)
+
+## v0.11.0
+
+- Enhancement: add `include Contracts::Core` that doesn't pollute the namespace as much as `include Contracts` - [Oleksii Federov](https://github.com/waterlink) [#185](https://github.com/egonSchiele/contracts.ruby/pull/185)
+- Bugfix: fail if a non-hash is provided to a `HashOf` contract - [Abe Voelker](https://github.com/abevoelker) [#190](https://github.com/egonSchiele/contracts.ruby/pull/190)
+- Bugfix: bugfix for using varargs and `Maybe[Proc]` together - [Adit Bhargava](https://github.com/egonSchiele) [#188](https://github.com/egonSchiele/contracts.ruby/pull/188)
+- Bugfix: make KeywordArgs fail if unexpected keys are passed in - [Abe Voelker](https://github.com/abevoelker) [#187](https://github.com/egonSchiele/contracts.ruby/pull/187)
+- Feature: range contract added - [Oleksii Fedorov](https://github.com/waterlink) [#184](https://github.com/egonSchiele/contracts.ruby/pull/184)
+- Feature: enum contract added - [Dennis Günnewig](https://github.com/dg-ratiodata) [#181](https://github.com/egonSchiele/contracts.ruby/pull/181)
+
+## v0.10.1
+
+- Enhancement: make `@pattern_match` instance variable not render ruby warning. Required to use new aruba versions in rspec tests - [Dennis Günnewig](https://github.com/dg-ratiodata) [#179](https://github.com/egonSchiele/contracts.ruby/pull/179)
+
+## v0.10
+
+- Bugfix: make `Maybe[Proc]` work correctly - [Simon George](https://github.com/sfcgeorge) [#142](https://github.com/egonSchiele/contracts.ruby/pull/142)
+- Bugfix: make `Func` contract verified when used as return contract - [Rob Rosenbaum](https://github.com/robnormal) [#145](https://github.com/egonSchiele/contracts.ruby/pull/145)
+- Bugfix: make `Pos`, `Neg` and `Nat` contracts handle non-numeric values correctly - [Matt Griffin](https://github.com/betamatt) and [Gavin Sinclair](https://github.com/gsinclair) [#147](https://github.com/egonSchiele/contracts.ruby/pull/147) [#173](https://github.com/egonSchiele/contracts.ruby/pull/173)
+- Enhancement: reduce user class pollution through introduction of contracts engine - [Oleksii Fedorov](https://github.com/waterlink) [#141](https://github.com/egonSchiele/contracts.ruby/pull/141)
+- Feature: add builtin `KeywordArgs` and `Optional` contracts for keyword arguments handling - [Oleksii Fedorov](https://github.com/waterlink) [#151](https://github.com/egonSchiele/contracts.ruby/pull/151)
+- Feature: recognize module as a class contract - [Oleksii Fedorov](https://github.com/waterlink) [#153](https://github.com/egonSchiele/contracts.ruby/pull/153)
+- Feature: custom validators with `Contract.override_validator` - [Oleksii Fedorov](https://github.com/waterlink) [#159](https://github.com/egonSchiele/contracts.ruby/pull/159)
+- Feature: add builtin `RangeOf[...]` contract - [Gavin Sinclair](https://github.com/gsinclair) [#171](https://github.com/egonSchiele/contracts.ruby/pull/171)
+
+## v0.9
+
+- MAJOR fix in pattern-matching: If the return contract for a pattern-matched function fails, it should NOT try the next pattern-match function. Pattern-matching is only for params, not return values.
+- raise an error if multiple defns have the same contract for pattern matching.
+
+- New syntax for functions with no input params (the old style still works)
+  Old way:
+  ```ruby
+  Contract nil => 1
+  def one
+  ```
+  New way:
+  ```
+  Contract 1
+  def one
+  ```
+
+- Prettier HashOf contract can now be written like this: `HashOf[Num => String]`
+- Add `SetOf` contract
+- various small fixes
+
+## v0.8
+
+- code refactored (very slight loss of performance, big increase in readability)
+- fail when defining a contract on a module without `include Contracts::Modules`
+- fixed several bugs in argument parsing, functions with complex params get contracts applied correctly now.
+- added rubocop to ci.
+- if a contract is set on a protected method, it should not become public.
+- fixed pattern matching when the multiple definitions of functions have different arities.
+- couple of new built-in contracts: Nat, Eq.
+- changed `Invariant` to `invariant`: `invariant(:day) { 1 <= day && day <= 31 }`
+- prettier error messages (`Contracts::Num` is now just `Num`, for example)
+- support for yard-contracts

data/Gemfile

@@ -0,0 +1,16 @@
+source "http://rubygems.org"
+
+gemspec
+
+group :test do
+  gem "rspec"
+  gem "rubocop", "~> 0.29.1", :platform => [:ruby_20, :ruby_21, :ruby_22, :ruby_23]
+end
+
+group :development do
+  gem "relish"
+  gem "method_profiler"
+  gem "ruby-prof"
+  gem "rake"
+  gem "byebug"
+end

data/LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2012-2016 Aditya Bhargava
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,102 @@
+# contracts.ruby [![Build Status](https://travis-ci.org/ddd-ruby/contracts.ruby.png?branch=master)](https://travis-ci.org/ddd-ruby/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.
+
+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'
+
+class Example
+  include Contracts::Core
+  include Contracts::Builtin
+
+  Contract Num => Num
+  def double(x)
+    x * 2
+  end
+end
+
+puts Example.new.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:
+
+```
+ParamContractError: Contract violation for argument 1 of 1:
+        Expected: Num,
+        Actual: "oops"
+        Value guarded in: Example::double
+        With Contract: Num => Num
+        At: main.rb:8
+        ...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).
+
+## Development
+
+To get started do the following:
+
+1. Install required gems for development
+
+  `bundle install`
+
+2. Run our test suite
+
+  `bundle exec rake`
+
+## 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.9.2`, `1.9.3`, `2.0.0`, `2.1`, `2.2`, and `jruby` (1.9 mode).
+
+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-2015 [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,747 @@
+# 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 Contracts::Num, Contracts::Num => Contracts::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'
+
+class Math
+  include Contracts::Core
+
+  Contract Contracts::Num, Contracts::Num => Contracts::Num
+  def self.add(a, b)
+    a + b
+  end
+end
+
+puts Math.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.
+
+## 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::Builtin` module in your class/module.
+
+contracts.ruby comes with a lot of built-in contracts, including the following:
+
+* Basic types
+  * [`Num`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/Num) – checks that the argument is `Numeric`
+  * [`Pos`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/Pos) – checks that the argument is a positive number
+  * [`Neg`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/Neg) – checks that the argument is a negative number
+  * [`Int`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/Int) – checks that the argument is an integer
+  * [`Nat`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/Nat) – checks that the argument is a natural number (>= 0)
+  * [`NatPos`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/NatPos) – checks that the argument is a positive natural number (> 0)
+  * [`Bool`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/Bool) – checks that the argument is `true` or `false`
+  * [`Any`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/Any) – Passes for any argument. Use when the argument has no constraints.
+  * [`None`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/None) – Fails for any argument. Use when the method takes no arguments.
+
+* Logical combinations
+  * [`Maybe`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/Maybe) – specifies that a value _may be_ nil, e.g. `Maybe[String]` (equivalent to `Or[String,nil]`)
+  * [`Or`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/Or) – passes if any of the given contracts pass, e.g. `Or[Fixnum, Float]`
+  * [`Xor`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/Xor) – passes if exactly one of the given contracts pass, e.g. `Xor[Fixnum, Float]`
+  * [`And`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/And) – passes if all contracts pass, e.g. `And[Nat, -> (n) { n.even? }]`
+  * [`Not`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/Not) – passes if all contracts fail for the given argument, e.g. `Not[nil]`
+
+* Collections
+  * [`ArrayOf`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/ArrayOf) – checks that the argument is an array, and all elements pass the given contract, e.g. `ArrayOf[Num]`
+  * [`SetOf`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/SetOf) – checks that the argument is a set, and all elements pass the given contract, e.g. `SetOf[Num]`
+  * [`HashOf`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/HashOf) – checks that the argument is a hash, and all keys and values pass the given contract, e.g. `HashOf[Symbol => String]` or `HashOf[Symbol,String]`
+  * [`StrictHash`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/StrictHash) – checks that the argument is a hash, and every key passed is present in the given contract, e.g. `StrictHash[{ :description => String, :number => Fixnum }]`
+  * [`RangeOf`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/RangeOf) – checks that the argument is a range whose elements (#first and #last) pass the given contract, e.g. `RangeOf[Date]`
+  * [`Enum`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/Enum) – checks that the argument is part of a given collection of objects, e.g. `Enum[:a, :b, :c]`
+
+* Keyword arguments
+  * [`KeywordArgs`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/KeywordArgs) – checks that the argument is an options hash, and all required keyword arguments are present, and all values pass their respective contracts, e.g. `KeywordArgs[:number => Num, :description => Optional[String]]`
+  * [`Optional`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/Optional) – checks that the keyword argument is either not present or pass the given contract, can not be used outside of `KeywordArgs` contract, e.g. `Optional[Num]`
+
+* Duck typing
+  * [`RespondTo`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/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/Builtin/Send) – checks that all named methods return a truthy value, e.g. `Send[:valid?]`
+
+* Miscellaneous
+  * [`Exactly`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/Exactly) – checks that the argument has the given type, not accepting sub-classes, e.g. `Exactly[Numeric]`.
+  * [`Eq`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/Eq) – checks that the argument is precisely equal to the given value, e.g. `Eq[String]` matches the class `String` and not a string instance.
+  * [`Func`](http://www.rubydoc.info/gems/contracts/Contracts/Builtin/Func) – specifies the contract for a proc/lambda e.g. `Contract ArrayOf[Num], Func[Num => Num] => ArrayOf[Num]`. See section "Contracts On Functions".
+
+To see all the built-in contracts and their full descriptions, check out the [RDoc](http://rubydoc.info/gems/contracts/Contracts/Builtin).
+
+It is recommended to use shortcut for referring builtin contracts:
+
+```ruby
+# define shortcut somewhere at the top level of your codebase:
+C = Contracts
+
+# and use it:
+Contract C::Maybe[C::Num], String => C::Num
+```
+
+Shortcut name should not be necessary `C`, can be anything that you are comfort
+with while typing and anything that does not conflict with libraries you use.
+
+All examples after this point assume you have chosen a shortcut as `C::`.
+
+If you are sure, that builtin contracts will not nameclash with your own code
+and libraries you may use, then you can include all builtin contracts in your
+class/module:
+
+```ruby
+class Example
+  include Contracts::Core
+  include Contracts::Builtin
+
+  Contract Maybe[Num], Or[Float, String] => Bool
+  def complicated_algorithm(a, b)
+    # ...
+  end
+end
+```
+
+## 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 C::Or[Fixnum, Float] => C::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 C::Or.new(Fixnum, Float) => C::Or.new(Fixnum, Float)
+```
+
+All the built-in contracts have overridden the square brackets (`[]`) to give the same functionality. So you could write
+
+```ruby
+Contract C::Or[Fixnum, Float] => C::Or[Fixnum, Float]
+```
+
+or
+
+```ruby
+Contract C::Or.new(Fixnum, Float) => C::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 C::ArrayOf[C::Num] => C::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 C::Args[C::Num] => C::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 [C::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 => C::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`. If you need this check though, use `StrictHash` instead.
+
+Peruse this contract on the keys and values of a Hash.
+
+```ruby
+Contract C::HashOf[Symbol, C::Num] => C::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 Strings
+
+When you want a contract to match not just any string (i.e. `Contract String => nil`), you can use regular expressions:
+```ruby
+Contract /World|Mars/i => nil
+def greet(name)
+  puts "Hello #{name}!"
+end
+```
+
+Using logical combinations you can combine existing definitions, instead of writing 1 big regular expression:
+```ruby
+Contract C::And[default_mail_regexp, /#{AppConfig.domain}\z/] => nil
+def send_admin_invite(email)
+```
+
+### Contracts On Keyword Arguments
+
+ruby 2.0+, but can be used for normal hashes too, when keyword arguments are
+not available
+
+Lets say you are writing a simple function and require a bunch of keyword arguments:
+
+```ruby
+def connect(host, port:, user:, password:)
+```
+
+You can of course put `Hash` contract on it:
+
+```ruby
+Contract String, { :port => C::Num, :user => String, :password => String } => Connection
+def connect(host, port:, user:, password:)
+```
+
+But this will not quite work if you want to have a default values:
+
+```ruby
+Contract String, { :port => C::Num, :user => String, :password => String } => Connection
+def connect(host, port: 5000, user:, password:)
+  # ...
+end
+
+# No value is passed for port
+connect("example.org", user: "me", password: "none")
+```
+
+Results in:
+
+```
+ContractError: Contract violation for argument 2 of 2:
+        Expected: {:port=>Num, :user=>String, :password=>String},
+        Actual: {:user=>"me", :password=>"none"}
+        Value guarded in: Object::connect
+        With Contract: String, Hash => Connection
+        At: (irb):12
+```
+
+This can be fixed with contract `{ :port => C::Maybe[C::Num], ... }`, but that will
+allow `nil` to be passed in, which is not the original intent.
+
+So that is where `KeywordArgs` and `Optional` contracts jump in:
+
+```ruby
+Contract String, C::KeywordArgs[ :port => C::Optional[C::Num], :user => String, :password => String ] => Connection
+def connect(host, port: 5000, user:, password:)
+```
+
+It looks just like the hash contract, but wrapped in `KeywordArgs` contract. Notice the usage of `Optional` contract - this way you specify that `:port` argument is optional. And it will not fail, when you omit this argument, but it will fail when you pass in `nil`.
+
+### Contracts On Functions
+
+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 C::ArrayOf[C::Any], Proc => C::ArrayOf[C::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 its 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 C::ArrayOf[C::Num], C::Func[C::Num => C::Num] => C::ArrayOf[C::Num]
+def map(arr, func)
+  ret = []
+  arr.each do |x|
+    ret << func[x]
+  end
+  ret
+end
+```
+
+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.
+```
+
+The above examples showed a method accepting a `Proc` as the last argument, but the same contract works on methods that accept a block:
+
+```ruby
+def map(arr, &block)
+```
+
+NOTE: This is not valid:
+
+```ruby
+Contract C::ArrayOf[C::Num], C::Func => C::ArrayOf[C::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:
+
+```ruby
+Contract C::Num => [C::Num, C::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 => C::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 } => C::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 C::Or[Fixnum, Float] => C::Num
+def double(x)
+  2 * x
+end
+```
+
+Without `CallableClass`, we would have to use `.new` instead:
+
+```ruby
+Contract C::Or.new(Fixnum, Float) => C::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).
+
+## Providing your own custom validators
+
+This can be done with `Contract.override_validator`:
+
+```ruby
+# Make contracts accept all RSpec doubles
+Contract.override_validator(:class) do |contract|
+  lambda do |arg|
+    arg.is_a?(RSpec::Mocks::Double) ||
+      arg.is_a?(contract)
+  end
+end
+```
+
+The block you provide should always return lambda accepting one argument - validated argument. Block itself accepts contract as an argument.
+
+Possible validator overrides:
+
+- `override_validator(MyCustomContract)` - allows to add some special behaviour for custom contracts,
+- `override_validator(Proc)` - e.g. `lambda { true }`,
+- `override_validator(Array)` - e.g. `[C::Num, String]`,
+- `override_validator(Hash)` - e.g. `{ :a => C::Num, :b => String }`,
+- `override_validator(Range)` - e.g. `(1..10)`,
+- `override_validator(Regexp)` - e.g. `/foo/`,
+- `override_validator(Contracts::Args)` - e.g. `C::Args[C::Num]`,
+- `override_validator(Contracts::Func)` - e.g. `C::Func[C::Num => C::Num]`,
+- `override_validator(:valid)` - allows to override how contracts that respond to `:valid?` are handled,
+- `override_validator(:class)` - allows to override how class/module contract constants are handled,
+- `override_validator(:default)` - otherwise, raw value contracts.
+
+Default validators can be found here: [lib/contracts/validators.rb](https://github.com/egonSchiele/contracts.ruby/blob/master/lib/contracts/validators.rb).
+
+## Disabling contracts
+
+If you want to disable contracts, set the `NO_CONTRACTS` environment variable. This will disable contracts and you won't have a performance hit. Pattern matching will still work if you disable contracts in this way! With NO_CONTRACTS only pattern-matching contracts are defined.
+
+## Method overloading
+
+You can use contracts for method overloading! This is commonly called "pattern matching" in functional programming languages.
+
+For example, here's a factorial function without method overloading:
+
+```ruby
+Contract C::Num => C::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 C::Num => C::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.
+
+This allows you write methods more declaratively, rather than using conditional branching. This feature is not only useful for recursion; you can use it to keep parallel use cases separate:
+
+```ruby
+Contract lambda{|n| n < 12 } => Ticket
+def get_ticket(age)
+  ChildTicket.new(age: age)
+end
+
+Contract lambda{|n| n >= 12 } => Ticket
+def get_ticket(age)
+  AdultTicket.new(age: age)
+end
+
+```
+
+Note that the second `get_ticket` contract above could have been simplified to:
+
+```ruby
+Contract C::Num => Ticket
+```
+
+This is because the first contract eliminated the possibility of `age` being less than 12. However, the simpler contract is less explicit; you may want to "spell out" the age condition for clarity, especially if the method is overloaded with many contracts.
+
+## Contracts in modules
+
+Usage is the same as contracts in classes:
+
+```ruby
+module M
+  include Contracts::Core
+
+  Contract String => String
+  def self.parse
+    # do some hard parsing
+  end
+end
+```
+
+## 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::Core
+  include Contracts::Invariants
+
+  invariant(:day) { 1 <= day && day <= 31 }
+  invariant(:month) { 1 <= month && month <= 12 }
+
+  Contract C::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.
+
+## Using contracts within your own code
+
+contracts.ruby is obviously designed to check method parameters and return values. But if you want to check whether some other data obeys a contract, you can use `Contract.valid?(value, contract)`. For instance:
+
+```ruby
+data = parse(user_input)
+unless Contract.valid?(data, HashOf[String,Nat])
+  raise UserInputError.new(user_input)
+end
+```
+
+## 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
+
+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!