# 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::SplatArgs[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 `SplatArgs` contract. It takes one contract as an argument and uses it to validate every element passed in through `*args`. So for example, `SplatArgs[Num]` means they should all be numbers. `SplatArgs[Or[Num, String]]` means they should all be numbers or strings. `SplatArgs[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::SplatArgs)` - e.g. `C::SplatArgs[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!