functional-ruby 0.7.7 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 29b9fc51a00acbd56545dc7f78fa1987fb254e47
-  data.tar.gz: f34dbe382c08f6d38c4047ddbae22f4eadfd50ae
+  metadata.gz: fe9f8b8bb0900055e86688c7995156bb89b5c0af
+  data.tar.gz: 794627125c2647c8e813b873c69f9be62bf3f206
 SHA512:
-  metadata.gz: b740d81ce57e2e0e6136081b8a40819197979d6e4bff1caa87670e0a1491f7681b9cfa201323cf8d9418bf63277fa43443722b80df474fedc0481e38e012a3a5
-  data.tar.gz: f94b25d9b50e5f66131bbff66134da8e6a9af06a381a82c553d3139fc09aa15030465d0edd236b7ba68cd42be1acc6096764f3b7cd64617fcf528b1c2899048a
+  metadata.gz: b2e54bc22942b8e2be11ca19fe1c0bd393a1a868bff7f2717d5830efea7e048b53f574763352b778170fe6e46d76d7e42bd566200843595a97142a35572a7941
+  data.tar.gz: 21c78e069e28438cc55dcdd3f0a2dc0892a5f36236337cd42a28dc8597d04b33f9565a3a46b03ce8c405b3b7b80ade995e2cd4f24c01642335382eaaaf917fc6

data/README.md

@@ -1,70 +1,29 @@
-# 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) [![Dependency Status](https://gemnasium.com/jdantonio/functional-ruby.png)](https://gemnasium.com/jdantonio/functional-ruby)
+# Functional Ruby
+[![Gem Version](https://badge.fury.io/rb/functional-ruby.png)](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)
 
-A gem for adding Erlang, Clojure, and Go inspired functional programming tools to Ruby.
+**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: As of version 0.7.0 the concurrency tools from this gem have been moved to the
-[concurrent-ruby](https://github.com/jdantonio/concurrent-ruby) gem.*
-
-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/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)
+*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.*
 
 ## Introduction
 
 Two things I love are [Ruby](http://www.ruby-lang.org/en/) and
 [functional](https://en.wikipedia.org/wiki/Functional_programming)
 [programming](http://c2.com/cgi/wiki?FunctionalProgramming).
-Sadly, the former is generally not associated with the latter. Unfortunately,
-too many people are blinded by their belief that Ruby is an object-oriented
-language. I reject this assertion. Ruby is certainly object-based, since
-everything is an object, but entire large-scale programs can be built without ever
-defining a single class. But Ruby's features that support functional programming
-don't stop there.
-
-Ask ten different programmers to define the term "functional programming" and
-you will likely get ten different answers. One characteristic that will certainly
-be on all their lists is support for
-[higher](http://en.wikipedia.org/wiki/Higher-order_function)
-[order](http://learnyouahaskell.com/higher-order-functions)
-[functions](http://learnyousomeerlang.com/higher-order-functions). Put simply, a
-higher order function is any function that can take one or more functions as
-parameters and/or return a function as a result. Many functional languages,
-such as Erlang, Haskell, and Closure, support higher order functions. Higher order
-functions are a remarkable tool that can completely change the was software is
-designed. Most classicaly object-oriented languages do not support higher
-order functions. Unfortunately, Ruby does not directly support higher order
-functions. Thanksfully, Ruby *does* give us blocks, `proc`s, and `lambda`s.
-Though not strictly higher order functions, in most cases they are functionally
-equivalent.
-
 If you combine Ruby's ability to create functions sans-classes with the power
-of blocks/`proc`s/`lambda`s, Ruby code can follow just about every modern functional
-programming design paradigm. Hence, I consider Ruby to be a *multi-paradigm* language.
-Add to this Ruby's vast metaprogramming capabilities and Ruby is easily one of the
-most powerful languages in common use today.
-
-This gem is my small and humble attempt to help Ruby reach its full potential as
-a highly performant, functional programming language. Virtually every function in
-this library takes a block parameter. Some allow a block plus one or more `proc`
-arguments. Most operate *on* data structures rather than being buried *in* data
-structures. Finally, several of the tools in this library are Ruby implementations
-of some of my favorite features from other functional programming languages. Not
-every function is pure, but functions with side effects are easy to spot because
-they almost always have names that end in an exclamation point.
-
-My hope is that this gem will help Ruby programmers explore Ruby as a functional
-language and improve their code in ways our object oriented brethern never
-dreamed possible.
+of blocks, `proc`, and `lambda`, Ruby code can follow just about every modern functional
+programming design paradigm. Add to this Ruby's vast metaprogramming capabilities
+and Ruby is easily one of the most powerful languages in common use today.
 
 ### Goals
 
-My goal is to implement various functional programming patterns in Ruby. Specifically:
+Our goal is to implement various functional programming patterns in Ruby. Specifically:
 
+* Be an 'unopinionated' toolbox that provides useful utilities without debating which is better or why
+* Remain free of external gem dependencies
 * 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
@@ -73,27 +32,26 @@ My goal is to implement various functional programming patterns in Ruby. Specifi
 * Keep everything small
 * Be as fast as reasonably possible
 
-## Features (and Documentation)
-
-Several features from Erlang, Go, and Clojure have been implemented thus far:
-
-* Interface specifications with Erlang-style [Behavior](https://github.com/jdantonio/functional-ruby/blob/master/md/behavior.md)
-* A [Catalog](https://github.com/jdantonio/functional-ruby/blob/master/md/catalog.md) class for managing sets of key/value pairs in a manner similar to Erlang's [proplists](http://www.erlang.org/doc/man/proplists.html)
-* A toolkit of [collection](https://github.com/jdantonio/functional-ruby/blob/master/md/collection.md) utilities for operating on list-like data structures
-* A set of string [inflections](https://github.com/jdantonio/functional-ruby/blob/master/md/inflect.md) borrowed from [Active Support](http://guides.rubyonrails.org/active_support_core_extensions.html#inflections)
-* Function overloading with Erlang-style [Pattern Matching](https://github.com/jdantonio/functional-ruby/blob/master/md/pattern_matching.md)
-* Tools for introspecting the runtime [Platform](https://github.com/jdantonio/functional-ruby/blob/master/md/platform.md) for information about the operating system and Ruby version
-* [Search](https://github.com/jdantonio/functional-ruby/blob/master/md/search.md) and [sort](https://github.com/jdantonio/functional-ruby/blob/master/md/sort.md) algorithms like you remember from your algorithms class, but with a functional twist
-* Several useful functional [Utilities](https://github.com/jdantonio/functional-ruby/blob/master/md/utilities.md)
+## Features
 
-### Is it any good?
+Complete API documentation can be found at [Rubydoc.info](http://rubydoc.info/github/jdantonio/functional-ruby/master/frames).
 
-[Yes](http://news.ycombinator.com/item?id=3067434)
+* Protocol specifications inspired by Clojure [protocol](http://clojure.org/protocols),
+  Erlang [behavior](http://www.erlang.org/doc/design_principles/des_princ.html#id60128),
+  and Objective-C [protocol](https://developer.apple.com/library/ios/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/WorkingwithProtocols/WorkingwithProtocols.html)
+* Function overloading with Erlang-style [function](http://erlang.org/doc/reference_manual/functions.html)
+  [pattern matching](http://erlang.org/doc/reference_manual/patterns.html)
+* Simple, immutable data structures, such as *record* and *union*, inspired by
+  [Clojure](http://clojure.org/datatypes), [Erlang](http://www.erlang.org/doc/reference_manual/records.html),
+  and [others](http://en.wikipedia.org/wiki/Union_type)
+* `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)
 
-### Supported Ruby versions
+### Supported Ruby Versions
 
-MRI 1.9.2, 1.9.3, 2.0, 2.1, and JRuby (1.9 mode). 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.
+MRI 2.0 and higher, JRuby (1.9 mode), and Rubinius 2.x. This library is pure Ruby and has no gem dependencies.
+It should be fully compatible with any interpreter that is compliant with Ruby 2.0 or newer.
 
 ### Install
 
@@ -115,110 +73,92 @@ Once you've installed the gem you must `require` it in your project:
 require 'functional'
 ```
 
-### Examples
+## Examples
 
-For complete examples, see the specific documentation linked above. Below are a
-few examples to whet your appetite.
+Specifying a protocol:
 
-#### Pattern Matching (Erlang)
+```ruby
+Functional::SpecifyProtocol(:Name) do
+  attr_accessor :first
+  attr_accessor :middle
+  attr_accessor :last
+  attr_accessor :suffix
+end
+```
 
-Documentation: [Pattern Matching](https://github.com/jdantonio/functional-ruby/blob/master/md/pattern_matching.md)
+Pattern matching using protocols, type checking, and other options:
 
 ```ruby
-require 'functional/pattern_matching'
-
 class Foo
-  include PatternMatching
+  include Functional::PatternMatching
+  include Functional::Protocol
+  include Functional::TypeChecking
 
-  defn(:greet, :male) {
-    puts "Hello, sir!"
+  def greet
+    return 'Hello, World!'
+  end
+
+  defn(:greet, _) do |name|
+    "Hello, #{name}!"
+  end
+
+  defn(:greet, _) { |name|
+    "Pleased to meet you, #{name.fulle_name}!"
+  }.when {|name| Type?(CustomerModel, ClientModel) }
+
+  defn(:greet, _) { |name|
+    "Hello, #{name.first} #{name.last}!"
+  }.when {|name| Satisfy?(:Name) }
+
+  defn(:greet, :male, _) { |name|
+    "Hello, Mr. #{name}!"
   }
 
-  defn(:greet, :female) {
-    puts "Hello, ma'am!"
+  defn(:greet, :female, _) { |name|
+    "Hello, Ms. #{name}!"
   }
-end
 
-foo = Foo.new
-foo.greet(:male)   #=> "Hello, sir!"
-foo.greet(:female) #=> "Hello, ma'am!"
-```
+  defn(:greet, nil, _) { |name|
+    "Goodbye, #{name}!"
+  }
 
-#### Behavior (Erlang)
+  defn(:greet, _, _) { |_, name|
+    "Hello, #{name}!"
+  }
+end
+```
 
-Documentation: [Behavior](https://github.com/jdantonio/functional-ruby/blob/master/md/behavior.md)
+Memoization:
 
 ```ruby
-require 'functional/behavior'
-
-behaviour_info(:gen_foo, foo: 0, self_bar: 1)
+class Factors
+  include Functional::Memo
 
-class Foo
-  behavior(:gen_foo)
-
-  def foo
-    return 'foo/0'
+  def self.sum_of(number)
+    of(number).reduce(:+)
   end
 
-  def self.bar(one, &block)
-    return 'bar/1'
+  def self.of(number)
+    (1..number).select {|i| factor?(number, i)}
   end
-end
 
-foo = Foo.new
+  def self.factor?(number, potential)
+    number % potential == 0
+  end
 
-Foo.behaves_as? :gen_foo    #=> true
-foo.behaves_as?(:gen_foo)   #=> true
-foo.behaves_as?(:bogus)     #=> false
-'foo'.behaves_as? :gen_foo  #=> false
+  memoize(:sum_of)
+  memoize(:of)
+end
 ```
 
-#### Utilities
-
-Documentation: [Utilities](https://github.com/jdantonio/functional-ruby/blob/master/md/utilities.md)
-
-```ruby
-Infinity #=> Infinity
-NaN #=> NaN
-
-repl? #=> true when called under irb, pry, bundle console, or rails console
-
-safe(1, 2){|a, b| a + b} #=> 3
-safe{ eval 'puts "Hello World!"' } #=> SecurityError: Insecure operation
+## Contributing
 
-pp_s [1,2,3,4] #=> "[1, 2, 3, 4]\n" props to Rha7
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
 
-delta(-1, 1) #=> 2
-delta({count: -1}, {count: 1}){|item| item[:count]} #=> 2
-
-# And many more!
-```
+## License and Copyright
 
-## Copyright
-
-*Functional Ruby* is Copyright © 2013 [Jerry D'Antonio](https://twitter.com/jerrydantonio).
-It is free software and may be redistributed under the terms specified in the LICENSE file.
-
-## License
-
-Released under the MIT license.
-
-http://www.opensource.org/licenses/mit-license.php  
-
-> Permission is hereby granted, free of charge, to any person obtaining a copy  
-> of this software and associated documentation files (the "Software"), to deal  
-> in the Software without restriction, including without limitation the rights  
-> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell  
-> copies of the Software, and to permit persons to whom the Software is  
-> furnished to do so, subject to the following conditions:  
-> 
-> The above copyright notice and this permission notice shall be included in  
-> all copies or substantial portions of the Software.  
-> 
-> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  
-> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,  
-> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  
-> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  
-> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,  
-> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN  
-> THE SOFTWARE.  
+*Functional Ruby* is free software released under the [MIT License](http://www.opensource.org/licenses/MIT).

data/doc/memo.txt

@@ -0,0 +1,192 @@
+# @!macro [new] 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