reachable 0.3.0

data/CHANGES

@@ -0,0 +1,6 @@
+Version 0.2.1
+* Added recursion, so that arrays within reachable arrays are treated as 
+   reachable arrays themselves
+Version 0.3.0
+* Changed the name of the gem to reachable, to avoid naming
+   conflict with the reach rubygem.

data/Gemfile

@@ -0,0 +1,11 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "bundler", "> 1.0.0"
+  gem "jeweler", "> 1.6.0"
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Ben J Woodcroft
+
+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.

data/README.md

@@ -0,0 +1,70 @@
+Copyright (C) 2008-2012      Ben J Woodcroft <donttrustben somewhere near gmail.com>
+
+This software is BETA! Use at your own risk.
+
+[![Build Status](https://secure.travis-ci.org/wwood/bioruby-krona.png)](http://travis-ci.org/wwood/reachable)
+
+# Reachable
+
+Reachable is a small Ruby liby that extends the Array class so that Arrays 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 classes. Bookshelves have many books, and books have many authors.
+
+Say I want all the books.
+
+```ruby
+Book.all
+```
+
+Then I want to find all the bookshelves from those that contain those books.
+
+```ruby
+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. 
+
+```ruby
+require 'reachable'
+Book.all.reach #=> ReachableArray of books
+```
+
+Now getting the corresponding array of bookshelves requires less typing:
+
+```
+require 'reachable'
+Book.all.reach.bookshelf #=> ReachableArray of Bookshelf objects
+```
+
+Notice that a ReachableArray is returned by the bookshelf method, not an Array. This means you can chain reaches together:
+
+```ruby
+require 'reachable'
+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:
+
+```ruby
+require 'reachable'
+Book.all.reach.bookshelf.retract #=> Array of Bookshelf objects
+```
+
+### Slap
+
+Like reach, the slap method is another method added to the Array class to make it mroe transparent. The difference is that reach looks to see if the given method operates on the Array class, and if not then applies it to each member of that array. The slap method bypasses the first step, and just applies the given method to each member. For instance
+
+```ruby
+require 'reachable'
+[[1,2,3],[4]].slap.length.retract #=> [1,3] 
+```
+
+## Caution
+
+When operating on a ReachableArray, methods that operate on the Array itself take precedence over methods that apply to array members.

data/Rakefile

@@ -0,0 +1,47 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "reachable"
+  gem.homepage = "http://github.com/wwood/reachable"
+  gem.license = "MIT"
+  gem.summary = %Q{Reachable is a small Ruby liby that extends the Array class so that Arrays are more transparent
+to methods.}
+  gem.description = %Q{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. }
+  gem.email = "gmail.com after donttrustben"
+  gem.authors = ["Ben J Woodcroft"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+task :default => :test
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "reach #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.3.0

data/lib/reachable.rb

@@ -0,0 +1,113 @@
+#   Copyright (c) 2008 Ben Woodcroft <donttrustben somewhere near gmail.com>
+#
+#   This program is free software.
+#   You can distribute/modify this program under the terms of
+#   the GNU General Public License version 3.
+
+# The point of this is that the 
+# Bookshelf.all.reach.books.each do {|book| puts book.name}
+# instead of
+# Bookshelf.all.each do |bookshelf|
+# bookshelf.books.each do |book|
+# puts book.name
+# end
+# end
+
+# Bookshelf.all.reach is a ReachableArray
+# the books is an array (bookshelves) of arrays (books)
+class Array
+  def reach
+    ReachingArray.new(self)
+  end
+  
+  def slap
+    SlappingArray.new(self)
+  end
+end
+
+class ReachingArray
+  # The array that this reaching array is extending. This might
+  # be a real Array, or a ReachingArray
+  attr_accessor :retract
+  
+  def initialize(retract)
+    @retract = retract
+  end
+  
+  # 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
+      r = @retract.send(method, *args, &block)
+      return r
+    else
+      # If this is an object-specific method, run an each on it.
+      # A simple each won't work because that doesn't modify the
+      # array elements in place as we want, so have to use collect
+      # instead.
+      @retract = @retract.collect do |o|
+        unless o.kind_of?(Array)
+          o.send(method, *args, &block)
+        else
+          # Update in 0.2.1: If the element of the array is an array
+          # itself, then operate on it as a ReachingArray as well.
+          o.reach.send(method, *args, &block).retract
+        end
+      end
+      return self
+    end
+  end
+  
+  # Equality test - equality of the underlying retract
+  # arrays is all that matter
+  def ==(another)
+    @retract <=> another.retract
+  end
+  
+  def to_s
+    method_missing(:to_s)
+  end
+  
+  def slap
+    retract.slap
+  end
+end
+
+class SlappingArray
+  # The array that this reaching array is extending. This might
+  # be a real Array, or a ReachingArray
+  attr_accessor :retract
+  
+  def initialize(retract)
+    @retract = retract
+  end
+  
+  # Try to pass the method to each of the array members 
+  def method_missing(method, *args, &block)
+    @retract = @retract.collect do |o|
+      unless o.kind_of?(Array)
+        o.send(method, *args, &block)
+      else
+        # Update in 0.2.1: If the element of the array is an array
+        # itself, then operate on it as a ReachingArray as well.
+        o.slap.send(method, *args, &block).retract
+      end
+    end
+    return self
+  end
+  
+  # Equality test - equality of the underlying retract
+  # arrays is all that matter
+  def ==(another)
+    @retract <=> another.retract
+  end
+  
+  def to_s
+    method_missing(:to_s)
+  end
+  
+  def reach
+    retract.reach
+  end
+end

data/rdoc.sh

@@ -0,0 +1 @@
+rdoc --main README.rdoc --inline *.rdoc lib/*

data/reachable.gemspec

@@ -0,0 +1,52 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "reachable"
+  s.version = "0.3.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Ben J Woodcroft"]
+  s.date = "2012-08-13"
+  s.description = "For instance, a ReachableArray of Book objects can not only take normal Array methods such as\ncollect and sum, but also methods that operate Book objects, such as author and title. "
+  s.email = "gmail.com after donttrustben"
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.md"
+  ]
+  s.files = [
+    "CHANGES",
+    "Gemfile",
+    "LICENSE.txt",
+    "README.md",
+    "Rakefile",
+    "VERSION",
+    "lib/reachable.rb",
+    "rdoc.sh",
+    "reachable.gemspec",
+    "test/test_reach.rb"
+  ]
+  s.homepage = "http://github.com/wwood/reachable"
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.17"
+  s.summary = "Reachable is a small Ruby liby that extends the Array class so that Arrays are more transparent to methods."
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<bundler>, ["> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["> 1.6.0"])
+    else
+      s.add_dependency(%q<bundler>, ["> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["> 1.6.0"])
+    end
+  else
+    s.add_dependency(%q<bundler>, ["> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["> 1.6.0"])
+  end
+end
+

data/test/test_reach.rb

@@ -0,0 +1,92 @@
+#   Copyright (c) 2008 Ben Woodcroft <donttrustben somewhere near gmail.com>
+#
+#   This program is free software.
+#   You can distribute/modify this program under the terms of
+#   the GNU Lesser General Public License version 3.
+
+
+$:.unshift File.join(File.dirname(__FILE__),'..','lib')
+
+require 'test/unit'
+require 'reachable'
+
+class ReachTest < Test::Unit::TestCase
+  def setup
+    @one_level = %w(a b c)
+    @two_level = [[1,2,3],[5]]
+  end
+  
+  def test_normality
+    # Test arrays seem normal - this is kinda pointless I would say
+    index = 0
+    @one_level.each { |n|
+      assert_equal @one_level[index], n
+      index += 1
+    }
+  end
+  
+  def test_simple_method
+    out = @one_level.reach.succ!
+    assert_kind_of ReachingArray, out
+    assert_equal ReachingArray.new(%w(b c d)), out
+  end
+  
+  def test_scoping_one
+    assert_equal ReachingArray.new(%w(c d e)), @one_level.reach.succ!.succ!
+  end
+  
+  def test_collect
+    assert_equal %w(b c d), @one_level.reach.collect{|c| c.succ}
+  end
+
+  # Catches if the array elements are not modified within the reach
+  def test_double_scope
+    # make sure my assumptions are correct about the
+    # classes being tested
+    assert 1.respond_to?(:zero?)
+    assert_equal false, '1'.respond_to?(:zero?)
+    
+    # make sure that the array elements are being reversed
+    str = ['0','2','3']
+    assert_equal [0,2,3], str.reach.to_i.retract
+    assert_equal [true, false, false], str.reach.to_i.zero?.retract
+  end
+  
+  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
+  
+  def test_recursive
+    assert_equal [1,[2,3],[[5]]],
+      ['1',['2','3'],[['5']]].reach.to_i.retract
+  end
+end
+
+class SlapTest < Test::Unit::TestCase
+  def setup
+    @one_level = %w(a b c)
+    @two_level = [[1,2,3],[5]]
+  end
+  
+  def test_simple
+    assert_kind_of SlappingArray, @two_level.slap
+    
+    assert_equal [['1','2','3'],['5']], @two_level.slap.to_s.retract
+  end
+  
+  def test_mutate
+    assert_kind_of ReachingArray, @two_level.slap.reach
+    assert_equal [[1,2,3],[5]], @two_level.slap.reach.retract
+  end
+  
+  def test_array_method_fail
+    assert_raise NoMethodError do 
+      @one_level.slap.join(' ')
+    end
+  end
+  
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: reachable
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+  prerelease: 
+platform: ruby
+authors:
+- Ben J Woodcroft
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-08-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: &75534190 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>'
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: *75534190
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: &75533890 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>'
+      - !ruby/object:Gem::Version
+        version: 1.6.0
+  type: :development
+  prerelease: false
+  version_requirements: *75533890
+description: ! '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. '
+email: gmail.com after donttrustben
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.txt
+- README.md
+files:
+- CHANGES
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- VERSION
+- lib/reachable.rb
+- rdoc.sh
+- reachable.gemspec
+- test/test_reach.rb
+homepage: http://github.com/wwood/reachable
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -120248467
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.17
+signing_key: 
+specification_version: 3
+summary: Reachable is a small Ruby liby that extends the Array class so that Arrays
+  are more transparent to methods.
+test_files: []