roxy 0.2.1

data/CHANGELOG

@@ -0,0 +1,3 @@
+0.1.0
+
+* Initial release.

data/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2008 Ryan Daigle
+ 
+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.textile

@@ -0,0 +1,51 @@
+h1. Roxy (A ruby proxy library)
+
+h2. Summary
+
+Roxy is a basic proxy library that lets you quickly create proxies between your ruby objects.  Its syntax
+is loosely based on "Association Extensions in ActiveRecord":http://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html
+as that is a well-known use of proxies.
+
+Please see the "CHANGELOG":http://github.com/yfactorial/utility_scopes/tree/master/CHANGELOG for contribution details. 
+
+Roxy has the following dependencies:
+
+* rspec >= 1.1.4 (for specs only, not runtime)
+
+h2. Installation
+
+To install the roxy gem run the following:
+
+  sudo gem install yfactorial-roxy --source http://gems.github.com
+  
+And to enable the scopes in your project just require the @roxy@ library and give your object some moxie:
+
+  require 'roxy'
+  class Person
+    include Roxy::Moxie
+    ...
+  end
+  
+h2. Usage
+
+See the announcement post for detailed usage examples: "http://ryandaigle.com/articles/2008/11/10/implement-ruby-proxy-objects-with-roxy":http://ryandaigle.com/articles/2008/11/10/implement-ruby-proxy-objects-with-roxy
+
+Here's a basic example:
+
+<pre><code>
+  require 'roxy'
+  class Person
+    include Roxy::Moxie    
+    
+    attr_accessor :first, :last, :parents 
+       
+    proxy :parents do
+      def divorced?
+        proxy_target.size > 1 and proxy_target.collect { |parent| parent.last }.uniq.size > 1
+      end
+    end
+  end
+
+  # Can then invoke your proxy methods directly on parents
+  person.parents.divorced?
+</code></pre>

data/Rakefile

@@ -0,0 +1,23 @@
+require 'rubygems'
+require 'rake'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+
+desc 'Run the specs'
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_opts = ['--colour --format progress --loadby mtime --reverse']
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end
+ 
+desc 'Generate RDoc documentation.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_files.include('README.textile', 'LICENSE', 'Rakefile').
+    include('lib/**/*.rb')
+  
+  rdoc.main = "README.textile"
+  rdoc.title = "roxy documentation"
+  
+  rdoc.rdoc_dir = 'doc' # rdoc output folder
+  rdoc.options << '--inline-source' << '--charset=UTF-8'
+  rdoc.options << '--webcvs=http://github.com/yfactorial/roxy/tree/master/'
+end

data/init.rb

@@ -0,0 +1 @@
+require 'roxy'

data/lib/roxy.rb

@@ -0,0 +1,2 @@
+require 'roxy/moxie'
+require 'roxy/proxy'

data/lib/roxy/moxie.rb

@@ -0,0 +1,42 @@
+module Roxy
+  module Moxie
+    
+    def self.included(within)
+      within.class_eval { extend ClassMethods }
+    end
+    
+    module ClassMethods
+      
+      # Set up this class to proxy on the given name
+      def proxy(name, options = {}, &block)
+        
+        # Make sure args are OK
+        original_method = method_defined?(name) ? instance_method(name) : nil
+        raise "Cannot proxy an existing method, \"#{name}\", and also have a :to option.  Please use one or the other." if
+          original_method and options[:to]  
+        
+        # If we're proxying an existing method, we need to store
+        # the original method and move it out of the way so
+        # we can take over
+        if original_method        
+          new_method = "proxied_#{name}"
+          alias_method new_method, "#{name}"
+          options[:to] = original_method
+        end
+        
+        # Thanks to Jerry for this simplification of my original class_eval approach
+        # http://ryandaigle.com/articles/2008/11/10/implement-ruby-proxy-objects-with-roxy/comments/8059#comment-8059
+        if !original_method or original_method.arity == 0
+          define_method name do
+            (@proxy_for ||= {})[name] ||= Proxy.new(self, options, nil, &block)
+          end
+        else
+          define_method name do |*args|
+            Proxy.new(self, options, args, &block)
+          end
+        end      
+      end
+      
+    end
+  end
+end

data/lib/roxy/proxy.rb

@@ -0,0 +1,42 @@
+module Roxy
+
+  # The very simple proxy class that provides a basic pass-through
+  # mechanism between the proxy owner and the proxy target.
+  class Proxy
+    
+    alias :proxy_instance_eval :instance_eval
+    alias :proxy_extend :extend
+    
+    # Make sure the proxy is as dumb as it can be.
+    # Blatanly taken from Jim Wierich's BlankSlate post:
+    # http://onestepback.org/index.cgi/Tech/Ruby/BlankSlate.rdoc
+    instance_methods.each { |m| undef_method m unless m =~ /(^__|^proxy_)/ }
+    
+    def initialize(owner, options, args, &block)
+      @owner = owner
+      @target = options[:to]
+      @args = args
+      
+      # Adorn with user-provided proxy methods
+      [options[:extend]].flatten.each { |ext| proxy_extend(ext) } if options[:extend]
+      proxy_instance_eval &block if block_given?      
+    end
+      
+    def proxy_owner; @owner; end
+    def proxy_target
+      if @target.is_a?(Proc)
+        @target.call(@owner)
+      elsif @target.is_a?(UnboundMethod)
+        bound_method = @target.bind(proxy_owner)
+        bound_method.arity == 0 ? bound_method.call : bound_method.call(*@args)
+      else
+        @target
+      end
+    end
+  
+    # Delegate all method calls we don't know about to target object
+    def method_missing(sym, *args, &block)
+      proxy_target.__send__(sym, *args, &block)
+    end
+  end
+end

data/spec/abstract_spec.rb

@@ -0,0 +1,9 @@
+require File.join(File.dirname(__FILE__), *%w[spec_helper])
+
+$:.unshift "#{File.dirname(__FILE__)}/../lib"
+require 'roxy'
+
+# Load a test class
+def uses_fixture(fixture_name)
+  require File.join(File.dirname(__FILE__), 'fixtures', fixture_name.to_s)
+end

data/spec/family_person_spec.rb

@@ -0,0 +1,77 @@
+require File.join(File.dirname(__FILE__), *%w[abstract_spec])
+
+describe "Whole family example" do
+
+  before do
+    uses_fixture(:family_person)
+    @ryan = FamilyPerson.new('Ryan', 'Daigle')
+    @ryan_parents = [FamilyPerson.new('Dad', 'Daigle'), FamilyPerson.new('Mom', 'Daigle')]
+    @ryan.parents = @ryan_parents
+    @ryan_children = [FamilyPerson.new('Child1', 'Daigle'), FamilyPerson.new('Child2', 'Daigle')]
+    @ryan.children = @ryan_children
+  end
+  
+  it "should know a person's parents (proxy should not overwrite target method)" do
+    @ryan.parents.should == @ryan_parents
+  end
+  
+  it "should know if a person's parents are divorced" do
+    @ryan.parents.divorced?.should be_false
+  end
+  
+  it "should know how to print out parents names' to a string when not divorced" do
+    @ryan.parents.to_s.should == "Mr. and Mrs. Daigle"
+  end
+  
+  it "should know how to get a person's step-children" do
+    @ryan.children.step.should be_empty
+  end
+end
+
+describe "Divorced family example" do
+
+  before do
+    uses_fixture(:family_person)
+    @ryan = FamilyPerson.new('Ryan', 'Daigle')
+    @ryan_parents = [FamilyPerson.new('Dad', 'Daigle'), FamilyPerson.new('Mom', 'NotDaigle')]
+    @ryan.parents = @ryan_parents
+    @ryan_children = [FamilyPerson.new('Child1', 'Daigle'), FamilyPerson.new('Child2', 'NotDaigle')]
+    @ryan.children = @ryan_children
+  end
+  
+  it "should know if a person's parents are divorced" do
+     @ryan.parents.divorced?.should be_true
+  end
+  
+  it "should know how to print out parents names' to a string when divorced" do
+    @ryan.parents.to_s.should == "Dad Daigle and Mom NotDaigle"
+  end
+  
+  it "should know how to get a person's step-children" do
+    @ryan.children.step.should == [@ryan_children.last]
+  end
+end
+
+describe "Ancestors example" do
+  
+  before do
+    uses_fixture(:family_person)
+    @ryan = FamilyPerson.new('Ryan', 'Daigle')
+  end
+  
+  it "should proxy through the ancestors method and retain arguments" do
+    @ryan.ancestors(true).sort.should == ['rancestor1', 'rancestor3', 'rancestor2', 'rancestor4'].sort
+  end
+  
+  it "should call proxied ancestor methods and retain arguments" do
+    @ryan.ancestors(true).men.sort.should == ['rancestor1', 'rancestor3'].sort
+    @ryan.ancestors(true).women.sort.should == ['rancestor2', 'rancestor4'].sort
+    @ryan.ancestors(false).men.sort.should == ['ancestor1', 'ancestor3'].sort
+    @ryan.ancestors(false).women.sort.should == ['ancestor2', 'ancestor4'].sort
+  end
+  
+  it "should call proxied ancestor methods and retain default arguments" do
+    @ryan.ancestors.men.sort.should == ['ancestor1', 'ancestor3'].sort
+    @ryan.ancestors.women.sort.should == ['ancestor2', 'ancestor4'].sort
+  end
+end

data/spec/fixtures/family_person.rb

@@ -0,0 +1,51 @@
+class FamilyPerson
+  
+  include Roxy::Moxie
+  
+  attr_accessor :first, :last, :parents, :children
+  
+  # Add ability to ask the parents collection if they are divorced
+  # (As defined by not having the same last name).  Also print
+  # them out as a string taking this into account
+  proxy :parents do
+    
+    def divorced?
+      proxy_target.size > 1 and proxy_target.collect { |parent| parent.last }.uniq.size > 1
+    end
+    
+    def to_s
+      if divorced?
+        proxy_target.collect { |parent| parent.to_s }.join(' and ')
+      else
+        "Mr. and Mrs. #{proxy_target[0].last}"
+      end
+    end
+  end
+  
+  # Add ability to ask the children collection for the list of
+  # step-children
+  proxy :children do
+    def step
+      proxy_target.select { |child| proxy_owner.last != child.last }
+    end    
+  end
+  
+  def initialize(first, last)
+    @first, @last = first, last
+  end
+  
+  def ancestors(reload = false)
+    1.upto(4).to_a.collect { |i| "#{reload ? 'r' : ''}ancestor#{i}" }      
+  end
+  
+  proxy :ancestors do
+    def men
+      proxy_target.select { |a| a.include?('1') || a.include?('3') }
+    end
+    def women
+      proxy_target - men
+    end
+  end
+  
+  def to_s; "#{first} #{last}"; end
+end

data/spec/fixtures/person.rb

@@ -0,0 +1,46 @@
+class Person
+  
+  include Roxy::Moxie
+  
+  proxy :children, :to => ['child1', 'child2'] do
+    def cost
+      100 * proxy_target.size
+    end
+  end
+  
+  def parents
+    ['parent1', 'parent2']
+  end
+  
+  proxy :parents do
+    def divorced?
+      proxy_target.size < 2
+    end
+  end
+  
+  module NeighborGeographics
+    def nearby?; true; end
+  end
+  
+  module NeighborDemographics
+    def caucasian?; false; end
+  end
+  
+  proxy :neighbors, :to => ['neighbor1', 'neighbor2'], :extend => [NeighborGeographics, NeighborDemographics]
+  
+  def ancestors(maternal = true, paternal = true)
+    paternal_ancestors = ['p_ancestor1', 'p_ancestor2']
+    maternal_ancestors = ['m_ancestor1', 'm_ancestor2']
+    (maternal ? maternal_ancestors : []) + (paternal ? paternal_ancestors : [])
+  end
+  
+  proxy :ancestors do
+    def men
+      proxy_target.select { |ancestor| ancestor[-1, 1] == '1' }
+    end
+    
+    def women
+      proxy_target.select { |ancestor| ancestor[-1, 1] == '2' }
+    end
+  end
+end

data/spec/proxy_spec.rb

@@ -0,0 +1,28 @@
+require File.join(File.dirname(__FILE__), *%w[abstract_spec])
+
+describe "Proxy" do
+  
+  before(:each) do
+    @owner = "String owner"
+    @target = "String target"
+    @lambda_target = lambda { @target }
+  end
+
+  it "should properly evaluate a block-based target" do
+    proxy = Roxy::Proxy.new(@owner, {:to => @lambda_target}, nil)
+    proxy.should == @target
+  end
+  
+  it "should properly adorn the proxy with proxy methods" do
+    proxy = Roxy::Proxy.new(@owner, {:to => @target}, nil) do
+      def poop; 'poop'; end
+    end
+    proxy.poop.should == 'poop'
+  end
+  
+  it "should make the proxy owner accessible to the target block" do
+    proxy = Roxy::Proxy.new(@owner, {:to => proc { |owner| owner }}, nil)
+    proxy.should == @owner
+  end
+    
+end

data/spec/roxy_spec.rb

@@ -0,0 +1,57 @@
+require File.join(File.dirname(__FILE__), *%w[abstract_spec])
+
+describe "Roxy" do
+
+  before do
+    uses_fixture(:person)
+    @person = Person.new
+  end
+
+  it "should return the target when the proxy name is called" do
+    @person.children.should == ['child1', 'child2']
+  end
+  
+  it "should return the evaluated target if the target is an existing method" do
+    @person.parents.should == ['parent1', 'parent2']
+  end
+  
+  it "should return the evaluated target if the target is a proc" do
+    @person.neighbors.should == ['neighbor1', 'neighbor2']
+  end
+  
+  it "should pass method invocations through to the target" do
+    @person.children.size.should == 2
+  end
+  
+  it "should intercept block-based proxy methods" do
+    @person.children.cost.should == 200
+    @person.parents.divorced?.should be_false
+  end
+  
+  it "should intercept :extend based proxy methods" do
+    @person.neighbors.nearby?.should be_true
+    @person.neighbors.caucasian?.should be_false
+  end
+  
+  it "should be able to pass arguments through the proxy" do
+    @person.ancestors(true, false).should == ['m_ancestor1', 'm_ancestor2']
+    @person.ancestors(false, true).should == ['p_ancestor1', 'p_ancestor2']
+    @person.ancestors(true, true).should == ['m_ancestor1', 'm_ancestor2'] + ['p_ancestor1', 'p_ancestor2']    
+  end
+  
+  it "should be able to retain default argument values" do
+    @person.ancestors.should == ['m_ancestor1', 'm_ancestor2'] + ['p_ancestor1', 'p_ancestor2'] 
+  end
+  
+  it "should be able to call a proxy method through a method with arguments" do
+    @person.ancestors(true, false).men.should == ['m_ancestor1']
+    @person.ancestors(true, false).women.should == ['m_ancestor2']
+    @person.ancestors(false, true).men.should == ['p_ancestor1']
+    @person.ancestors(false, true).women.should == ['p_ancestor2']
+    @person.ancestors(true, true).men.sort.should == ['p_ancestor1', 'm_ancestor1'].sort
+  end
+  
+  it "should retain default argument values when calling a proxied method with arguments" do
+    @person.ancestors.women.sort.should == ['p_ancestor2', 'm_ancestor2'].sort
+  end
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification 
+name: roxy
+version: !ruby/object:Gem::Version 
+  hash: 21
+  prerelease: false
+  segments: 
+  - 0
+  - 2
+  - 1
+  version: 0.2.1
+platform: ruby
+authors: 
+- Ryan Daigle
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-11-22 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+description: A Ruby library for quickly creating proxy objects.
+email: ryan@yfactorial.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.textile
+- Rakefile
+- LICENSE
+- CHANGELOG
+files: 
+- README.textile
+- Rakefile
+- LICENSE
+- CHANGELOG
+- init.rb
+- lib/roxy.rb
+- lib/roxy/moxie.rb
+- lib/roxy/proxy.rb
+- spec/abstract_spec.rb
+- spec/proxy_spec.rb
+- spec/roxy_spec.rb
+- spec/family_person_spec.rb
+- spec/fixtures/person.rb
+- spec/fixtures/family_person.rb
+has_rdoc: true
+homepage: http://github.com/yfactorial/roxy
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.textile
+- --inline-source
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A Ruby library for quickly creating proxy objects.
+test_files: []
+