functional-ruby 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c56d810dbee5d5fb2e4b26daef765a75700d3e4f
-  data.tar.gz: e3e27de5c017c07eef5c9d78c590e73251fa98a9
+  metadata.gz: 45800b8ffb755a47bf66e40dc7a7832d2577f174
+  data.tar.gz: 0becaff048134f9616f871e6ae2f1b42a50fea66
 SHA512:
-  metadata.gz: 84ba63762cb021ceb483e8f175a23c9ea11c12b5fa66764662670b9a688d4d2a0f15bb7baed3b8e2b2207a5b37613b62dc1c90c647bbb68176c0208b41c7cf8e
-  data.tar.gz: 7411ea271610c82bbf180e28797ab0e0a0795200d7c77f252e435e098acfe7224236fd59700b72fad726d4a03d43fd1829277f75b14dd8f7f8afd615a44410e0
+  metadata.gz: 68918e9ef2c30806b416512d687bdf4c4d9fb27ef3c6d869cd78f43435e1411de2b443f29c760dd67cc39a2a0e5cf639502054b0924c5413246955b360f567ee
+  data.tar.gz: 7765dd90d059280a7018a12103b2a3961636fd31325c7ee3ffd2c22944bfca0181226596794dc8cb7850506e7075cb28541992b17a8209bcbcc6540296cbdf9b

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+### Upcoming Release v1.2.0 (TBD)
+
+* `Record` classes can be declared with a type/protocol specification for type safety.
+
 ## Current Release v1.1.0 (August 12, 2014)
 
 * A simple implementation of [tuple](http://en.wikipedia.org/wiki/Tuple), an

data/README.md

@@ -1,15 +1,16 @@
 # Functional Ruby
-[![Gem Version](https://badge.fury.io/rb/functional-ruby.svg)](http://badge.fury.io/rb/functional-ruby) [![Build Status](https://secure.travis-ci.org/jdantonio/functional-ruby.png)](https://travis-ci.org/jdantonio/functional-ruby?branch=master) [![Coverage Status](https://coveralls.io/repos/jdantonio/functional-ruby/badge.png)](https://coveralls.io/r/jdantonio/functional-ruby) [![Code Climate](https://codeclimate.com/github/jdantonio/functional-ruby.png)](https://codeclimate.com/github/jdantonio/functional-ruby) [![Inline docs](http://inch-ci.org/github/jdantonio/functional-ruby.png)](http://inch-ci.org/github/jdantonio/functional-ruby) [![Dependency Status](https://gemnasium.com/jdantonio/functional-ruby.png)](https://gemnasium.com/jdantonio/functional-ruby) [![License](http://img.shields.io/license/MIT.png?color=green)](http://opensource.org/licenses/MIT)
+[![Gem Version](https://badge.fury.io/rb/functional-ruby.svg)](http://badge.fury.io/rb/functional-ruby)
+[![Travis CI Build Status](https://secure.travis-ci.org/jdantonio/functional-ruby.png)](https://travis-ci.org/jdantonio/functional-ruby?branch=master)
+[![AppVeyor Build status](https://ci.appveyor.com/api/projects/status/8xfy4a8lmc26112e/branch/master?svg=true)](https://ci.appveyor.com/project/jdantonio/functional-ruby/branch/master)
+[![Coverage Status](https://coveralls.io/repos/jdantonio/functional-ruby/badge.png)](https://coveralls.io/r/jdantonio/functional-ruby)
+[![Code Climate](https://codeclimate.com/github/jdantonio/functional-ruby.png)](https://codeclimate.com/github/jdantonio/functional-ruby)
+[![Inline docs](http://inch-ci.org/github/jdantonio/functional-ruby.png)](http://inch-ci.org/github/jdantonio/functional-ruby)
+[![Dependency Status](https://gemnasium.com/jdantonio/functional-ruby.png)](https://gemnasium.com/jdantonio/functional-ruby)
+[![License](http://img.shields.io/license/MIT.png?color=green)](http://opensource.org/licenses/MIT)
 
 **A gem for adding functional programming tools to Ruby. Inspired by [Erlang](http://www.erlang.org/),
 [Clojure](http://clojure.org/), and [Functional Java](http://functionaljava.org/).**
 
-*NOTE: Version 1.0 is a complete rewrite. Previous versions lacked a unified
-focus. Version 1.0 is a cohesive set of utilities inspired by other languages
-but designed to work together in ways idiomatic to Ruby.*
-
-Please see the [changelog](https://github.com/jdantonio/functional-ruby/blob/master/CHANGELOG.md) for more information.
-
 ## Introduction
 
 Two things I love are [Ruby](http://www.ruby-lang.org/en/) and
@@ -36,7 +37,7 @@ Our goal is to implement various functional programming patterns in Ruby. Specif
 
 ## Features
 
-Complete API documentation can be found at [Rubydoc.info](http://rubydoc.info/github/jdantonio/functional-ruby/master/frames).
+The primary site for documentation is the automatically generated [API documentation](http://jdantonio.github.io/functional-ruby/).
 
 * Protocol specifications inspired by Clojure [protocol](http://clojure.org/protocols),
   Erlang [behavior](http://www.erlang.org/doc/design_principles/des_princ.html#id60128),
@@ -49,6 +50,7 @@ Complete API documentation can be found at [Rubydoc.info](http://rubydoc.info/gi
 * Thread safe, immutable `Either` and `Option` classes based on [Functional Java](http://functionaljava.org/) and [Haskell](https://hackage.haskell.org/package/base-4.2.0.1/docs/Data-Either.html).
 * [Memoization](http://en.wikipedia.org/wiki/Memoization) of class methods based on Clojure [memoize](http://clojuredocs.org/clojure_core/clojure.core/memoize).
 * Lazy execution with a `Delay` class based on Clojure [delay](http://clojuredocs.org/clojure_core/clojure.core/delay).
+* `ValueStruct`, a simple, thread safe, immutable variation of Ruby's [OpenStruct](http://ruby-doc.org/stdlib-2.0/libdoc/ostruct/rdoc/OpenStruct.html) class.
 * Thread safe data structures, such as `FinalStruct` and `FinalVar`, which can be written to at most once
   before becoming immutable. Based on [Java's `final` keyword](http://en.wikipedia.org/wiki/Final_(Java)).
 
@@ -116,7 +118,7 @@ and other options:
 class Foo
   include Functional::PatternMatching
   include Functional::Protocol
-  include Functional::TypeChecking
+  include Functional::TypeCheck
 
   def greet
     return 'Hello, World!'
@@ -127,12 +129,12 @@ class Foo
   end
 
   defn(:greet, _) { |name|
-    "Pleased to meet you, #{name.fulle_name}!"
-  }.when {|name| Type?(CustomerModel, ClientModel) }
+    "Pleased to meet you, #{name.full_name}!"
+  }.when {|name| Type?(name, CustomerModel, ClientModel) }
 
   defn(:greet, _) { |name|
     "Hello, #{name.first} #{name.last}!"
-  }.when {|name| Satisfy?(:Name) }
+  }.when {|name| Satisfy?(name, :Name) }
 
   defn(:greet, :doctor, _) { |name|
     "Hello, Dr. #{name}!"

data/doc/memo.md

@@ -0,0 +1,192 @@
+# memoize
+
+###    Rationale
+
+   Many computational operations take a significant amount of time and/or use
+   an inordinate amount of resources. If subsequent calls to that function with
+   the same parameters are guaranteed to return the same result, caching the
+   result can lead to significant performance improvements. The process of
+   caching such calls is called
+   [memoization](http://en.wikipedia.org/wiki/Memoization).
+
+###    Declaration
+
+   Using memoization requires two simple steps: including the
+   `Functional::Memo` module within a class or module and calling the `memoize`
+   function to enable memoization on one or more methods.
+
+   ```ruby
+   Module EvenNumbers
+     include Functional::Memoize
+
+     self.first(n)
+       (2..n).select{|i| i % 2 == 0 }
+     end
+
+     memoize :first
+   end
+   ```
+
+   When a function is memoized an internal cache is created that maps arguments
+   to return values. When the function is called the arguments are checked
+   against the cache. If the args are found the method is not called and the
+   cached result is returned instead.
+
+###    Ramifications
+
+   Memoizing long-running methods can lead to significant performance
+   advantages. But there is a trade-off. Memoization may greatly increase the
+   memory footprint of the application. The memo cache itself takes memory. The
+   more arg/result pairs stored in the cache, the more memory is consumed.
+
+#####    Cache Size Options
+
+   To help control the size of the cache, a limit can be placed on the number
+   of items retained in the cache. The `:at_most` option, when given, indicates
+   the maximum size of the cache. Once the maximum cache size is reached, calls
+   to to the method with uncached args will still result in the method being
+   called, but the results will not be cached.
+
+   ```ruby
+   Module EvenNumbers
+     include Functional::Memoize
+
+     self.first(n)
+       (2..n).select{|i| i % 2 == 0 }
+     end
+
+     memoize :first, at_most: 1000
+   end
+   ```
+
+   There is no way to predict in advance what the proper cache size is, or if
+   it should be restricted at all. Only performance testing under realistic
+   conditions or profiling of a running system can provide guidance.
+
+###    Restrictions
+
+   Not all methods are good candidates for memoization.Only methods that are
+   [idempotent](http://en.wikipedia.org/wiki/Idempotence), [referentially
+   transparent](http://en.wikipedia.org/wiki/Referential_transparency_(computer_science)),
+   and free of [side effects](http://en.wikipedia.org/wiki/Side_effect_(computer_science))
+   can be effectively memoized. If a method creates side effects, such as
+   writing to a log, only the first call to the method will create those side
+   effects. Subsequent calls will return the cached value without calling the
+   method.
+
+   Similarly, methods which change internal state will only update the state on
+   the initial call. Later calls will not result in state changes, they will
+   only return the original result. Subsequently, instance methods cannot be
+   memoized. Objects are, by definition, stateful. Method calls exist for the
+   purpose of changing or using the internal state of the object. Such methods
+   cannot be effectively memoized; it would require the internal state of the
+   object to be cached and checked as well.
+
+   Block parameters pose a similar problem. Block parameters are inherently
+   stateful (they are closures which capture the enclosing context). And there
+   is no way to check the state of the block along with the args to determine
+   if the cached value should be used. Subsequently, and method call which
+   includes a block will result in the cache being completely skipped. The base
+   method will be called and the result will not be cached. This behavior will
+   occur even when the given method was not programmed to accept a block
+   parameter. Ruby will capture any block passed to any method and make it
+   available to the method even when not documented as a formal parameter or
+   used in the method. This has the interesting side effect of allowing the
+   memo cache to be skipped on any method call, simply be passing a block
+   parameter.
+
+   ```ruby
+   EvenNumbers.first(100)         causes the result to be cached
+   EvenNumbers.first(100)         retrieves the previous result from the cache
+   EvenNumbers.first(100){ nil }  skips the memo cache and calls the method again
+   ```
+
+###   Complete Example
+
+   The following example is borrowed from the book [Functional Thinking](http://shop.oreilly.com/product/0636920029687.do)
+   by Neal Ford. In his book he shows an example of memoization in Groovy by
+   summing factors of a given number. This is a great example because it
+   exhibits all the criteria that make a method a good memoization candidate:
+
+   * Idempotence
+   * Referential transparency
+   * Stateless
+   * Free of side effect
+   * Computationally expensive (for large numbers)
+
+   The following code implements Ford's algorithms in Ruby, then memoizes two
+   key methods. The Ruby code:
+
+   ```ruby
+   require 'functional'
+
+   class Factors
+     include Functional::Memo
+
+     def self.sum_of(number)
+       of(number).reduce(:+)
+     end
+
+     def self.of(number)
+       (1..number).select {|i| factor?(number, i)}
+     end
+
+     def self.factor?(number, potential)
+       number % potential == 0
+     end
+
+     def self.perfect?(number)
+       sum_of(number) == 2 * number
+     end
+
+     def self.abundant?(number)
+       sum_of(number) > 2 * number
+     end
+
+     def self.deficient?(number)
+       sum_of(number) < 2 * number
+     end
+
+     memoize(:sum_of)
+     memoize(:of)
+   end
+   ```
+
+   This code was tested in IRB using MRI 2.1.2 on a MacBook Pro. The `sum_of`
+   method was called three times against the number 10,000,000 and the
+   benchmark results of each run were captured. The test code:
+
+   ```ruby
+   require 'benchmark'
+
+   3.times do
+     stats = Benchmark.measure do
+       Factors.sum_of(10_000_000)
+     end
+     puts stats
+   end
+   ```
+
+   The results of the benchmarking are very revealing. The first run took over
+   a second to calculate the results. The two subsequent runs, which retrieved
+   the previous result from the memo cache, were nearly instantaneous:
+
+   ```
+   1.080000   0.000000   1.080000 (  1.077524)
+   0.000000   0.000000   0.000000 (  0.000033)
+   0.000000   0.000000   0.000000 (  0.000008)
+   ```
+
+   The same code run on the same computer using JRuby 1.7.12 exhibited similar
+   results:
+
+   ```
+   1.800000   0.030000   1.830000 (  1.494000)
+   0.000000   0.000000   0.000000 (  0.000000)
+   0.000000   0.000000   0.000000 (  0.000000)
+   ```
+
+###    Inspiration
+
+   * [Memoization](http://en.wikipedia.org/wiki/Memoization) at Wikipedia
+   * Clojure [memoize](http://clojuredocs.org/clojure_core/clojure.core/memoize) function

data/doc/pattern_matching.md

@@ -0,0 +1,481 @@
+###    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
+
+###    Usage
+
+   First, familiarize yourself with Erlang [pattern matching](http://learnyousomeerlang.com/syntax-in-functionspattern-matching).
+   This gem may not make much sense if you don't understand how Erlang dispatches functions.
+
+   In the Ruby class file where you want to use pattern matching, require the *functional-ruby* gem:
+
+   ```ruby
+   require 'functional'
+   ```
+
+   Then include `Functional::PatternMatching` in your class:
+
+   ```ruby
+   require 'functional'
+
+   class Foo
+     include Functional::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 Functional::PatternMatching
+
+     defn(:hello) {
+       puts "Hello, World!"
+     }
+   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.greet(:male)   => "Hello, sir!"
+   foo.greet(: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!"
+   ```
+
+   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!"
+   ```
+
+   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:
+
+   ```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 Functional::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:
+
+   ```ruby
+   require 'functional/pattern_matching'
+
+   class Foo
+     include Functional::PatternMatching
+
+     defn(:greet, _) do |name|
+       "Hello, {name}!"
+     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 Functional::PatternMatching
+
+     defn(:greet, _) do |name|
+       "Hello, {name}!"
+     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 Functional::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 Functional::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 Functional::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
+
+   ```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
+   ```
+
+#####    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.
+   ```
+
+   ```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 }
+
+   defn(:wrong_age, _) {
+     true
+   }
+   ```
+
+###    Inspiration
+
+   Pattern matching has its roots in logic programming languages such as
+   [Prolog](http://en.wikipedia.org/wiki/Prolog). Pattern matching is a core
+   feature of the [Erlang](http://www.erlang.org/) programming language. A few
+   helpful resources are:
+
+   * Erlang [modules](http://erlang.org/doc/reference_manual/modules.html)
+   * Erlang [pattern matching](http://erlang.org/doc/reference_manual/patterns.html)