functional-ruby 0.5.0 → 0.6.0

data/README.md

@@ -1,79 +1,77 @@
-# Functional Ruby [![Build Status](https://secure.travis-ci.org/jdantonio/functional-ruby.png)](http://travis-ci.org/jdantonio/functional-ruby?branch=master) [![Dependency Status](https://gemnasium.com/jdantonio/functional-ruby.png)](https://gemnasium.com/jdantonio/functional-ruby)
+# Functional Ruby [![Build Status](https://secure.travis-ci.org/jdantonio/functional-ruby.png)](https://travis-ci.org/jdantonio/functional-ruby?branch=master) [![Dependency Status](https://gemnasium.com/jdantonio/functional-ruby.png)](https://gemnasium.com/jdantonio/functional-ruby)
 
-A gem for adding Erlang and Clojure inspired functional programming tools to Ruby.
+A gem for adding Erlang, Clojure, and Go inspired concurrency and functional programming tools to Ruby.
 
 The project is hosted on the following sites:
 
 * [RubyGems project page](https://rubygems.org/gems/functional-ruby)
 * [Source code on GitHub](https://github.com/jdantonio/functional-ruby)
+* [YARD documentation on RubyDoc.info](http://rubydoc.info/github/jdantonio/functional-ruby/master/frames)
 * [Continuous integration on Travis-CI](https://travis-ci.org/jdantonio/functional-ruby)
 * [Dependency tracking on Gemnasium](https://gemnasium.com/jdantonio/functional-ruby)
 * [Follow me on Twitter](https://twitter.com/jerrydantonio)
 
 ## Introduction
 
-[Ruby](http://www.ruby-lang.org/en/) is my favorite programming by far. As much as I love
-Ruby I've always been a little disappointed that Ruby doesn't support function overloading.
-Function overloading tends to reduce branching and keep function signatures simpler.
-No sweat, I learned to do without. Then I started programming in [Erlang](http://www.erlang.org/)...
-
-I've really started to enjoy working in Erlang. Erlang is good at all the things Ruby is bad
-at and vice versa. Together, Ruby and Erlang make me happy. My favorite Erlang feature is,
-without question, [pattern matching](http://learnyousomeerlang.com/syntax-in-functions#pattern-matching).
-Pattern matching is like function overloading cranked to 11. So one day I was musing on Twitter
-that I'd like to see Erlang-stype pattern matching in Ruby and one of my friends responded "Build it!"
-So I did. And here it is.
-
-For fun I threw in Erlang's sparsely documented [-behaviour](http://www.erlang.org/doc/design_principles/gen_server_concepts.html)
-functionality plus a few other functions and constants I find useful. Eventually I realized I was
-building something much more than just Erlang's pattern matching. I was creating a broader library
-for helping programmers write Ruby code in a functional style. So I changed the name of the gem
-and kept on trucking.
+Three things I love are [Ruby](http://www.ruby-lang.org/en/),
+[functional](https://en.wikipedia.org/wiki/Functional_programming)
+[programming](http://c2.com/cgi/wiki?FunctionalProgramming) and
+[concurrency](http://www.amazon.com/s/ref=nb_sb_noss_1?url=search-alias%3Dstripbooks&field-keywords=concurrent%20programming).
+Sadly, the first is generally not associated with the other two. First, I reject the
+assertion that Ruby is an object-oriented language. It's certainly object-based, since
+everything is an object, but entire large-scale programs can be built without ever
+defining a single class. Ruby is a true multi-paradigm language and easily supports
+many advanced functional techniques. As to concurrency, Ruby's bad reputation is
+well earned, but recent versions of Ruby have made significan improvements in that
+area. Ruby 2.0 is now a [relevant](https://blog.heroku.com/archives/2013/6/17/ruby-2-default-new-aps)
+platform for concurrent applications.
+
+This gem is my small and humble attempt to help Ruby reach its full potential as
+a highly performant, functional, concurrent programming language.
 
 ### Goals
 
-* Stay true to the spirit of Erlang pattern matching, if not the semantics
+My history with high-performance, highly-concurrent programming goes back to my days with C/C++.
+I have the same scars as everyone else doing that kind of work with those languages.
+I'm fascinated by modern concurrency patterns like [Actors](http://en.wikipedia.org/wiki/Actor_model),
+[Agents](http://doc.akka.io/docs/akka/snapshot/java/agents.html), and
+[Promises](http://promises-aplus.github.io/promises-spec/). I'm equally fascinated by languages
+with strong concurrency support like [Erlang](http://www.erlang.org/doc/getting_started/conc_prog.html),
+[Go](http://golang.org/doc/articles/concurrency_patterns.html), and
+[Clojure](http://clojure.org/concurrent_programming) (I program with Erlang at work).
+My goal is to implement those patterns in Ruby. Specifically:
+
+* Stay true to the spirit of the languages providing inspiration
+* But implement in a way that makes sense for Ruby
 * Keep the semantics as idiomatic Ruby as possible
 * Support features that make sense in Ruby
-* Exclude features that only make sense in Erlang
-* Avoid using *method_missing*
+* Exclude features that don't make sense in Ruby
 * Keep everything small
 * Be as fast as reasonably possible
 
-### Features
-
-* Pattern matching for instance methods.
-* Pattern matching for object constructors.
-* Parameter count matching
-* Matching against primitive values
-* Matching by class/datatype
-* Matching against specific key/vaue pairs in hashes
-* Matching against the presence of keys within hashes
-* Implicit hash for last parameter
-* Variable-length parameter lists
-* Guard clauses
-* Recursive calls to other pattern matches
-* Recursive calls to superclass pattern matches
-* Recursive calls to superclass methods
-* Dispatching to superclass methods when no match is found
-* Reasonable error messages when no match is found
-
-### For good -behavior(timeoff).
-
-One of Ruby's greatest strengths is [duck typing](http://rubylearning.com/satishtalim/duck_typing.html).
-Usually this is awesome and I'm happy to not have to deal with static typing and the compiler. Usually.
-The problem with duck typing is that is is impossible in Ruby to enforce an interface definition.
-I would never advocate turning Ruby into the cesspool complex object creation that Java has
-unfortunately become, but occasionally it would be nice to make sure a class implements a set of
-required methods. Enter Erlang's [-behavior](http://metajack.im/2008/10/29/custom-behaviors-in-erlang/)
-keyword. Basically, you define a `behavior_info` then drop a `behavior` call within a class.
-Forget to implement a required method and Ruby will let you know. See the examples below for details.
-
-## Supported Ruby versions
-
-MRI 1.9.x and above. Anything else and your mileage may vary.
-
-## Install
+## Features (and Documentation)
+
+Several features from Erlang, Co, Clojure, and JavaScript have been implemented this far:
+
+* Function overloading with Erlang-style [Pattern Matching](https://github.com/jdantonio/functional-ruby/blob/master/md/pattern_matching.md)
+* Interface specifications with Erlang-style [Behavior](https://github.com/jdantonio/functional-ruby/blob/master/md/behavior.md)
+* Chained asynchronous operations inspried by JavaScript [Promises](https://github.com/jdantonio/functional-ruby/blob/master/md/promise.md)
+* Additional Clojure, Go, and Erlang inspired [Concurrency](https://github.com/jdantonio/functional-ruby/blob/master/md/concurrency.md)
+* Several useful functional [Utilities](https://github.com/jdantonio/functional-ruby/blob/master/md/utilities.md)
+
+### Is it any good?
+
+[Yes](http://news.ycombinator.com/item?id=3067434)
+
+### Supported Ruby versions
+
+MRI 1.9.2, 1.9.3, and 2.0. This library is pure Ruby and has no gem dependencies. It should be
+fully compatible with any Ruby interpreter that is 1.9.x compliant. I simply don't know enough
+about JRuby, Rubinius, or the others to fully support them. I can promise good karma and
+attribution on this page to anyone wishing to take responsibility for verifying compaitibility
+with any Ruby other than MRI.
+
+### Install
 
 ```shell
 gem install functional-ruby
@@ -93,8 +91,10 @@ that not all users may want, several `require` options are available:
 ```ruby
 require 'functional/behavior'
 require 'functional/behaviour' # alternate spelling
+require 'functional/concurrency'
 require 'functional/pattern_matching'
-require 'functional/core'
+require 'functional/promise'
+require 'functional/utilities'
 ```
 
 If you want everything you can do that, too:
@@ -103,18 +103,14 @@ If you want everything you can do that, too:
 require 'functional/all'
 ```
 
-## PatternMatching
+## Examples
 
-First, familiarize yourself with Erlang [pattern matching](http://learnyousomeerlang.com/syntax-in-functions#pattern-matching).
-This gem may not make much sense if you don't understand how Erlang dispatches functions.
+For complete examples, see the specific documentation linked above. Below are a
+few examples to whet your appetite.
 
-In the Ruby class file where you want to use pattern matching, require the *functional-ruby* gem:
+### Pattern Matching (Erlang)
 
-```ruby
-require 'functional/pattern_matching'
-```
-
-Then include `PatternMatching` in your class:
+Documentation: [Pattern Matching](https://github.com/jdantonio/functional-ruby/blob/master/md/pattern_matching.md)
 
 ```ruby
 require 'functional/pattern_matching'
@@ -122,548 +118,144 @@ require 'functional/pattern_matching'
 class Foo
   include PatternMatching
 
-  ...
-
-end
-```
-
-You can then define functions with `defn` instead of the normal *def* statement.
-The syntax for `defn` is:
-
-```ruby
-defn(:symbol_name_of_function, zero, or, more, parameters) { |block, arguments|
-  # code to execute
-}
-```
-You can then call your new function just like any other:
-
-```ruby
-require 'functional/pattern_matching'
-
-class Foo
-  include PatternMatching
+  defn(:greet, :male) {
+    puts "Hello, sir!"
+  }
 
-  defn(:hello) {
-    puts "Hello, World!"
+  defn(:greet, :female) {
+    puts "Hello, ma'am!"
   }
 end
 
 foo = Foo.new
-foo.hello #=> "Hello, World!"
-```
-
-Patterns to match against are included in the parameter list:
-
-```ruby
-defn(:greet, :male) {
-  puts "Hello, sir!"
-}
-
-defn(:greet, :female) {
-  puts "Hello, ma'am!"
-}
-
-...
-
-foo.hello(:male)   #=> "Hello, sir!"
-foo.hello(:female) #=> "Hello, ma'am!"
-```
-
-If a particular method call can not be matched a *NoMethodError* is thrown with
-a reasonably helpful error message:
-
-```ruby
-foo.greet(:unknown) #=> NoMethodError: no method `greet` matching [:unknown] found for class Foo
-foo.greet           #=> NoMethodError: no method `greet` matching [] found for class Foo
-```
-
-Parameters that are expected to exist but that can take any value are considered
-*unbound* parameters. Unbound parameters are specified by the `_` underscore
-character or `UNBOUND`:
-
-```ruby
-defn(:greet, _) do |name|
-  "Hello, #{name}!"
-end
-
-defn(:greet, UNBOUND, UNBOUND) do |first, last|
-  "Hello, #{first} #{last}!"
-end
-
-...
-
-foo.greet('Jerry') #=> "Hello, Jerry!"
+foo.greet(:male)   #=> "Hello, sir!"
+foo.greet(:female) #=> "Hello, ma'am!"
 ```
 
-All unbound parameters will be passed to the block in the order they are specified in the definition:
-
-```ruby
-defn(:greet, _, _) do |first, last|
-  "Hello, #{first} #{last}!"
-end
-
-...
-
-foo.greet('Jerry', "D'Antonio") #=> "Hello, Jerry D'Antonio!"
-```
-
-If for some reason you don't care about one or more unbound parameters within
-the block you can use the `_` underscore character in the block parameters list
-as well:
-
-```ruby
-defn(:greet, _, _, _) do |first, _, last|
-  "Hello, #{first} #{last}!"
-end
-
-...
-
-foo.greet('Jerry', "I'm not going to tell you my middle name!", "D'Antonio") #=> "Hello, Jerry D'Antonio!"
-```
+### Behavior (Erlang)
 
-Hash parameters can match against specific keys and either bound or unbound parameters. This allows for
-function dispatch by hash parameters without having to dig through the hash:
+Documentation: [Behavior](https://github.com/jdantonio/functional-ruby/blob/master/md/behavior.md)
 
 ```ruby
-defn(:hashable, {foo: :bar}) { |opts|
-  :foo_bar
-}
-defn(:hashable, {foo: _}) { |f|
-  f
-}
-
-...
-
-foo.hashable({foo: :bar})      #=> :foo_bar
-foo.hashable({foo: :baz})      #=> :baz
-```
-
-The Ruby idiom of the final parameter being a hash is also supported:
-
-```ruby
-defn(:options, _) { |opts|
-  opts
-}
-
-...
-
-foo.options(bar: :baz, one: 1, many: 2)
-```
-
-As is the Ruby idiom of variable-length argument lists. The constant `ALL` as the last parameter
-will match one or more arguments and pass them to the block as an array:
-
-```ruby
-defn(:baz, Integer, ALL) { |int, args|
-  [int, args]
-}
-defn(:baz, ALL) { |args|
-  args
-}
-```
-
-Superclass polymorphism is supported as well. If an object cannot match a method
-signature it will defer to the parent class:
-
-```ruby
-class Bar
-  def greet
-    return 'Hello, World!'
-  end
-end
-
-class Foo < Bar
-  include PatternMatching
-
-  defn(:greet, _) do |name|
-    "Hello, #{name}!"
-  end
-end
-
-...
-
-foo.greet('Jerry') #=> "Hello, Jerry!"
-foo.greet          #=> "Hello, World!"
-```
-
-Guard clauses in Erlang are defined with `when` clauses between the parameter list and the function body.
-In Ruby, guard clauses are defined by chaining a call to `when` onto the the `defn` call and passing
-a block. If the guard clause evaluates to true then the function will match. If the guard evaluates
-to false the function will not match and pattern matching will continue:
-
-Erlang:
-
-```erlang
-old_enough(X) when X >= 16 -> true;
-old_enough(_) -> false.
-```
-
-Ruby:
-
-```ruby
-defn(:old_enough, _){ true }.when{|x| x >= 16 }
-defn(:old_enough, _){ false }
-```
-
-### Order Matters
-
-As with Erlang, the order of pattern matches is significant. Patterns will be matched
-*in the order declared* and the first match will be used. If a particular function call
-can be matched by more than one pattern, the *first matched pattern* will be used. It
-is the programmer's responsibility to ensure patterns are declared in the correct order.
-
-### Blocks and Procs and Lambdas, oh my!
-
-When using this gem it is critical to remember that `defn` takes a block and
-that blocks in Ruby have special rules. There are [plenty](https://www.google.com/search?q=ruby+block+proc+lambda)
-of good tutorials on the web explaining [blocks](http://www.robertsosinski.com/2008/12/21/understanding-ruby-blocks-procs-and-lambdas/)
-and [Procs](https://coderwall.com/p/_-_mha) and [lambdas](http://railsguru.org/2010/03/learn-ruby-procs-blocks-lambda/)
-in Ruby. Please read them. Please don't submit a bug report if you use a
-`return` statement within your `defn` and your code blows up with a
-[LocalJumpError](http://ruby-doc.org/core-2.0/LocalJumpError.html). 
-
-### Examples
-
-For more examples see the integration tests in *spec/integration_spec.rb*.
-
-#### Simple Functions
-
-This example is based on [Syntax in defnctions: Pattern Matching](http://learnyousomeerlang.com/syntax-in-defnctions) in [Learn You Some Erlang for Great Good!](http://learnyousomeerlang.com/).
-
-Erlang:
-
-```erlang
-greet(male, Name) ->
-  io:format("Hello, Mr. ~s!", [Name]);
-greet(female, Name) ->
-  io:format("Hello, Mrs. ~s!", [Name]);
-greet(_, Name) ->
-  io:format("Hello, ~s!", [Name]).
-```
-
-Ruby:
+require 'functional/behavior'
 
-```ruby
-require 'functional/pattern_matching'
+behaviour_info(:gen_foo, foo: 0, bar: 1)
 
 class Foo
-  include PatternMatching
+  behavior(:gen_foo)
 
-  defn(:greet, _) do |name|
-    "Hello, #{name}!"
+  def foo
+    return 'foo/0'
   end
 
-  defn(:greet, :male, _) { |name|
-    "Hello, Mr. #{name}!"
-  }
-  defn(:greet, :female, _) { |name|
-    "Hello, Ms. #{name}!"
-  }
-  defn(:greet, _, _) { |_, name|
-    "Hello, #{name}!"
-  }
-end
-```
-
-#### Simple Functions with Overloading
-
-This example is based on [Syntax in defnctions: Pattern Matching](http://learnyousomeerlang.com/syntax-in-defnctions) in [Learn You Some Erlang for Great Good!](http://learnyousomeerlang.com/).
-
-Erlang:
-
-```erlang
-greet(Name) ->
-  io:format("Hello, ~s!", [Name]).
-
-greet(male, Name) ->
-  io:format("Hello, Mr. ~s!", [Name]);
-greet(female, Name) ->
-  io:format("Hello, Mrs. ~s!", [Name]);
-greet(_, Name) ->
-  io:format("Hello, ~s!", [Name]).
-```
-
-Ruby:
-
-```ruby
-require 'functional/pattern_matching'
-
-class Foo
-  include PatternMatching
-
-  defn(:greet, _) do |name|
-    "Hello, #{name}!"
+  def bar(one, &block)
+    return 'bar/1'
   end
-
-  defn(:greet, :male, _) { |name|
-    "Hello, Mr. #{name}!"
-  }
-  defn(:greet, :female, _) { |name|
-    "Hello, Ms. #{name}!"
-  }
-  defn(:greet, nil, _) { |name|
-    "Goodbye, #{name}!"
-  }
-  defn(:greet, _, _) { |_, name|
-    "Hello, #{name}!"
-  }
-end
-```
-
-#### Constructor Overloading
-
-```ruby
-require 'functional/pattern_matching'
-
-class Foo
-  include PatternMatching
-
-  defn(:initialize) { @name = 'baz' }
-  defn(:initialize, _) {|name| @name = name.to_s }
 end
-```
-
-#### Matching by Class/Datatype
-
-```ruby
-require 'functional/pattern_matching'
-
-class Foo
-  include PatternMatching
-
-  defn(:concat, Integer, Integer) { |first, second|
-    first + second
-  }
-  defn(:concat, Integer, String) { |first, second|
-    "#{first} #{second}"
-  }
-  defn(:concat, String, String) { |first, second|
-    first + second
-  }
-  defn(:concat, Integer, _) { |first, second|
-    first + second.to_i
-  }
-end
-```
 
-#### Matching a Hash Parameter
-
-```ruby
-require 'functional/pattern_matching'
-
-class Foo
-  include PatternMatching
-  
-  defn(:hashable, {foo: :bar}) { |opts|
-    # matches any hash with key :foo and value :bar
-    :foo_bar
-  }
-  defn(:hashable, {foo: _, bar: _}) { |f, b|
-    # matches any hash with keys :foo and :bar
-    # passes the values associated with those keys to the block
-    [f, b]
-  }
-  defn(:hashable, {foo: _}) { |f|
-    # matches any hash with key :foo
-    # passes the value associated with that key to the block
-    # must appear AFTER the prior match or it will override that one
-    f
-  }
-  defn(:hashable, {}) { ||
-    # matches an empty hash
-    :empty
-  }
-  defn(:hashable, _) { |opts|
-    # matches any hash (or any other value)
-    opts
-  }
-end
-
-...
-
-foo.hashable({foo: :bar})      #=> :foo_bar
-foo.hashable({foo: :baz})      #=> :baz
-foo.hashable({foo: 1, bar: 2}) #=> [1, 2] 
-foo.hashable({foo: 1, baz: 2}) #=> 1
-foo.hashable({bar: :baz})      #=> {bar: :baz}
-foo.hashable({})               #=> :empty 
-```
-
-#### Variable Length Argument Lists with ALL
+foo = Foo.new
 
-```ruby
-defn(:all, :one, ALL) { |args|
-  args
-}
-defn(:all, :one, Integer, ALL) { |int, args|
-  [int, args]
-}
-defn(:all, 1, _, ALL) { |var, args|
-  [var, args]
-}
-defn(:all, ALL) { | args|
-  args
-}
-
-...
-
-foo.all(:one, 'a', 'bee', :see) #=> ['a', 'bee', :see]
-foo.all(:one, 1, 'bee', :see)   #=> [1, 'bee', :see]
-foo.all(1, 'a', 'bee', :see)    #=> ['a', ['bee', :see]]
-foo.all('a', 'bee', :see)       #=> ['a', 'bee', :see]
-foo.all()                       #=> NoMethodError: no method `all` matching [] found for class Foo
+foo.behaves_as? :gen_foo    #=> true
+foo.behaves_as?(:bogus)     #=> false
+'foo'.behaves_as? :gen_foo  #=> false
 ```
 
-#### Guard Clauses
-
-These examples are based on [Syntax in defnctions: Pattern Matching](http://learnyousomeerlang.com/syntax-in-defnctions)
-in [Learn You Some Erlang for Great Good!](http://learnyousomeerlang.com/).
-
-Erlang:
-
-```erlang
-old_enough(X) when X >= 16 -> true;
-old_enough(_) -> false.
-
-right_age(X) when X >= 16, X =< 104 ->
-  true;
-right_age(_) ->
-  false.
-
-wrong_age(X) when X < 16; X > 104 ->
-  true;
-wrong_age(_) ->
-  false.
-```
+### Goroutine (Go)
 
 ```ruby
-defn(:old_enough, _){ true }.when{|x| x >= 16 }
-defn(:old_enough, _){ false }
-
-defn(:right_age, _) {
-  true
-}.when{|x| x >= 16 && x <= 104 }
-
-defn(:right_age, _) {
-  false
-}
-
-defn(:wrong_age, _) {
-  false
-}.when{|x| x < 16 || x > 104 }
+require 'functional/concurrency'
 
-defn(:wrong_age, _) {
-  true
-}
+@expected = nil
+go(1, 2, 3){|a, b, c| @expected = [c, b, a] }
+sleep(0.1)
+@expected #=> [3, 2, 1]
 ```
 
-## Behavior
-
-The `behavior` functionality is not imported by default. It requires a separate `require` statement:
+### Agent (Clojure)
 
 ```ruby
-require 'behavior'
-
-# -or-
-
-require 'behaviour'
-```
+require 'functional/agent'
+# or
+require 'functional/concurrency'
 
-Next, declare a behavior using the `behavior_info` function (this function should sit outside
-of any module/class definition, but will probably work regardless). The first parameter to
-`behavior_info` (or `behaviour_info`) is a symbol name for the behavior. The remaining parameter
-is a hash of function names and their arity:
+score = agent(10)
+score.value #=> 10
 
-```ruby
-behaviour_info(:gen_foo, foo: 0, bar: 1, baz: 2)
-
-# -or (for the Java/C# crowd)
+score << proc{|current| current + 100 }
+sleep(0.1)
+score.value #=> 110
 
-interface(:gen_foo, foo: 0, bar: 1, baz: 2)
+score << proc{|current| current * 2 }
+sleep(0.1)
+deref score #=> 220
 
+score << proc{|current| current - 50 }
+sleep(0.1)
+score.value #=> 170
 ```
 
-Each function name can be listed only once and the arity must follow the rules of the
-[Method#arity](http://ruby-doc.org/core-1.9.3/Method.html#method-i-arity) function.
-Though not explicitly documented, block arguments do not count toward a method's arity.
-methods defined using this gem's `defn` function will always have an arity of -1,
-regardless of how many overloads are defined.
-
-To enforce a behavior on a class simply call the `behavior` function within the class,
-passing the name of the desired behavior:
+### Future (Clojure)
 
 ```ruby
-class Foo
-  behavior(:gen_foo)
-  ...
-end
-
-# or use the idiomatic Erlang spelling
-class Bar
-  behaviour(:gen_foo)
-  ...
-end
+require 'functional/future'
+# or
+require 'functional/concurrency'
 
-# or use the idiomatic Rails syntax
-class Baz
-  behaves_as :gen_foo
-  ...
-end
+count = future{ sleep(1); 10 }
+count.state #=> :pending
+# do stuff...
+count.value #=> 10 (after blocking)
+deref count #=> 10
 ```
 
-Make sure you the implement the required methods in your class. If you don't, Ruby will
-raise an exception when you try to create an object from the class:
+### Promise (JavaScript)
 
-```ruby
-Baz.new #=> ArgumentError: undefined callback functions in Baz (behavior 'gen_foo')
-```
-
-As an added bonus, Ruby [Object](http://ruby-doc.org/core-1.9.3/Object.html) will be
-monkey-patched with a `behaves_as?` predicate method.
-
-A complete example:
+* [Promises/A](http://wiki.commonjs.org/wiki/Promises/A)
+* [Promises/A+](http://promises-aplus.github.io/promises-spec/)
 
 ```ruby
-behaviour_info(:gen_foo, foo: 0, bar: 1, baz: 2, boom: -1, bam: :any)
-
-class Foo
-  behavior(:gen_foo)
-
-  def foo
-    return 'foo/0'
-  end
-
-  def bar(one, &block)
-    return 'bar/1'
-  end
-
-  def baz(one, two)
-    return 'baz/2'
-  end
+require 'functional/promise'
+# or
+require 'functional/concurrency'
 
-  def boom(*args)
-    return 'boom/-1'
-  end
-
-  def bam
-    return 'bam!'
-  end
-end
-
-foo = Foo.new
-
-foo.behaves_as? :gen_foo    #=> true
-foo.behaves_as?(:bogus)     #=> false
-'foo'.behaves_as? :gen_foo  #=> false
+p = promise("Jerry", "D'Antonio"){|a, b| "#{a} #{b}" }.
+    then{|result| "Hello #{result}." }.
+    rescue(StandardError){|ex| puts "Boom!" }.
+    then{|result| "#{result} Would you like to play a game?"}
+sleep(1)
+p.value #=> "Hello Jerry D'Antonio. Would you like to play a game?" 
 ```
 
-## Utility Functions
-
-Convenience functions are not imported by default. It require a separate `require` statement:
+### Thread Pools
 
 ```ruby
-require 'functional/core'
-```
+require 'functional/fixed_thread_pool'
+require 'functional/cached_thread_pool'
+# or
+require 'functional/concurrency'
+
+pool = Functional::FixedThreadPool.new(10)
+@expected = 0
+pool.post{ sleep(0.5); @expected += 100 }
+pool.post{ sleep(0.5); @expected += 100 }
+pool.post{ sleep(0.5); @expected += 100 }
+@expected #=> nil
+sleep(1)
+@expected #=> 300
+
+pool = Functional::CachedThreadPool.new
+@expected = 0
+pool << proc{ sleep(0.5); @expected += 10 }
+pool << proc{ sleep(0.5); @expected += 10 }
+pool << proc{ sleep(0.5); @expected += 10 }
+@expected #=> 0
+sleep(1)
+@expected #=> 30
+```
+
+### Utilities
+
+Documentation: [Utilities](https://github.com/jdantonio/functional-ruby/blob/master/md/utilities.md)
 
 ```ruby
 Infinity #=> Infinity
@@ -678,9 +270,9 @@ pp_s [1,2,3,4] #=> "[1, 2, 3, 4]\n" props to Rha7
 
 delta(-1, 1) #=> 2
 delta({count: -1}, {count: 1}){|item| item[:count]} #=> 2
-```
 
-This gives you access to a few constants and functions:
+# And many more!
+```
 
 ## Copyright