wwood-reach 0.1 → 0.1.1

data/README.rdoc

@@ -0,0 +1,45 @@
+Copyright (C) 2008      Ben J Woodcroft <donttrustben somewhere near gmail.com>
+
+= Reach
+
+Reach is a small Ruby liby that extends Array so they are more transparent
+to methods. For instance, a ReachableArray of Book objects can not only take normal Array methods such as
+collect and sum, but also methods that operate Book objects, such as author and title. 
+
+== Example
+
+Say I have an regular ActiveRecord driven database, that has Bookshelf, Book, and Author objects. Bookshelves have many books, and books have many authors.
+
+Say I want all the books.
+
+  % Book.all
+
+Then I want all the bookshelves from those books. A common way to do this is to use the collect method of arrays:
+
+  % Book.all.collect{|book| book.bookshelf} => array of bookshelves.
+
+From personal experience, running a single method on each array element and collecting the results is quite common, especially in Rails. The idea, then, is to make the arrays not just responsive to the methods that apply to the Array itself, but to methods that apply to the members of that array. That is, make the array reachable (caution: made up word). In the case above we want to run the 'bookshelf' method on each of the book objects in the array.
+
+To make an array reachable, convert it into a ReachableArray object, by calling the reach method of Array, which is added by the inclusion of the reach library. 
+
+  % require 'reach'
+  % Book.all.reach => ReachableArray of books
+
+Now getting the corresponding array of bookshelves requires less typing:
+
+  % require 'reach'
+  % Book.all.reach.bookshelf => ReachableArray of Bookshelf objects
+
+Notice that a ReachableArray is returned, not an Array. This means you can chain reaches together:
+
+  % require 'reach'
+  % Author.all.reach.book.bookshelf => ReachableArray of Bookshelf objects
+
+Removing reachability from the array, or retracting, is equally as simple - just use the retract method:
+
+  % require 'reach'
+  % Book.all.reach.bookshelf.retract => Array of Bookshelf objects
+
+== Caution
+
+When operating on a ReachableArray, methods that operate on the Array itself take precedence over methods that apply to array members.

data/lib/reach.rb

@@ -2,7 +2,7 @@
 #
 #   This program is free software.
 #   You can distribute/modify this program under the terms of
-#   the GNU Lesser General Public License version 3.
+#   the GNU General Public License version 3.
 
 # The point of this is that the 
 # Bookshelf.all.reach.books.each do {|book| puts book.name}
@@ -30,9 +30,8 @@ class ReachingArray
     @retract = retract
   end
   
-  # When a method is called on an array and that method
-  # isn't defined for an array, then run 
-  # 
+  # The method could be missing from the array, the members, or both.
+  # Try to pass the method to each, in that order, accepting the first taker
   def method_missing(method, *args, &block)
     if @retract.respond_to?(method)
       # If this is an array method, just use that
@@ -50,8 +49,13 @@ class ReachingArray
     end
   end
   
-  # Mainly for testing
+  # Equality test - equality of the underlying retract
+  # arrays is all that matter
   def ==(another)
     @retract <=> another.retract
   end
+  
+  def to_s
+    @retract.to_s
+  end
 end

data/reach.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name     = "reach"
-  s.version  = "0.1"
+  s.version  = "0.1.1"
   s.date     = "2008-09-05"
   s.summary  = "Extend the Ruby Array class for less loops and blocks"
   s.email    = "donttrustben somewhere near gmail.com"
@@ -8,6 +8,7 @@ Gem::Specification.new do |s|
   s.description = "Extend the Ruby Array class for less loops and blocks."
   s.authors  = ["Ben J Woodcroft"]
   s.files    = ["reach.gemspec", 
+		"README.rdoc", 
 		"lib/reach.rb"]
   s.test_files = ["test/test_reach.rb"]
 end

data/test/test_reach.rb

@@ -55,4 +55,8 @@ class ReachTest < Test::Unit::TestCase
   def test_block_accepted
     assert_equal %w(d e f), @one_level.reach.succ.collect{|c| c.succ.succ}
   end
+  
+  def test_to_s
+    assert_equal [1,2].to_s, [1,2].reach.to_s
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: wwood-reach
 version: !ruby/object:Gem::Version 
-  version: "0.1"
+  version: 0.1.1
 platform: ruby
 authors: 
 - Ben J Woodcroft
@@ -23,6 +23,7 @@ extra_rdoc_files: []
 
 files: 
 - reach.gemspec
+- README.rdoc
 - lib/reach.rb
 has_rdoc: false
 homepage: http://github.com/wwood/reach