forwarder 0.1.0

data/LICENSE

@@ -0,0 +1,10 @@
+The MIT License (MIT)
+
+Copyright (c) 2012 Robert Dober
+
+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,93 @@
+# Forwarder #
+
+Delegation made readable.
+
+## Rational ##
+
+It seems that Ruby's built in ```Forwardable``` module does a decent job
+to provide for delegation. However its syntax is more than terse, it is, IMHO,
+unreadable. At a certain moment it came to me that relearning the correct
+application of ```def_delegator```, frequent usage non withstanding is *not*
+what I want to use my time for.
+
+From that desire ```Forwarder``` was created. As ```Forwardable``` it is not
+intruisive but once a module is extended with it the following methods spring
+into live: ```forward```, ```forward_all``` and ```forward_to_self```. The
+first two replace and enhance the functionality of ```def_delegator``` and
+```def_delegators```, while the third is a kind of a ```alias_method``` on
+steroids.
+
+## Examples ##
+
+* forward
+
+Forwards to a target. The target must be specified by the ```:to``` keyword 
+parameter and can be either a ```Symbol``` (or ```String```), thus representing 
+an instance method or an instance variable, a lambda that will be evaluated 
+in the instance's context. If an arbitrary object shall be the receiver of the
+message, than the ```:to``` keyword can be replaced by the ```:to_object```
+keyword parameter. 
+
+       class Employee
+         extend Forwarder
+         forward :complaints, to: :boss
+       end
+
+This design, implementing some wishful thinking that will probably not pass
+acceptance tests, will forward the ```complaints``` message, sent to an instance
+of ```Employee```, to the object returned by this very instance's ```boss``` method.
+
+The following adjustment was made, in desperate hope to fix the *bug*:
+
+      class Employee
+        extend Forwarder
+        forward :complaints, to: :boss, as: :suggestions
+      end
+
+This behavior being clearly preferable to the one implemented before because the
+receiver of ```complaints``` is still forwarding the call to the result of the
+call of its ```boss``` method, but to the ```suggestion``` method.
+
+Finally, however, the implementation looked like this
+
+      class Boss
+        extend Forwarder
+        forward_all :complaints, :problems, :tasks, to: first_employee
+      end
+
+However this did not work as no ```first_employee``` was defined. This seems
+simple enough a task, so that a method for this seems too much code bloat, here
+are two possible implementations with ```Forwarder```
+
+      class Boss
+        extend Forwarder
+        forward :first_employee, to: :@employees, as: :[], with: 0
+        forward_all :complaints, :problems, :tasks, to: :first_employee
+      end
+
+As a side note, I do not enourage the exposure of instance variables as in the
+example above, but I do not like to impose. As ```Forwardable``` can delegate to
+instance variables I decided to provide the same functionality with
+```Forwarder```.
+      
+Or alternatively
+
+      class Boss
+        extend Forwarder
+        forward :first_employee, to: :@employees, as: :first
+        forward_all :complaints, :problems, :tasks, to: first_employee
+      end
+
+
+The above, however is a little bit verbose, we can shorten it with the `:to_chain`
+parameter
+
+      class Boss
+        extend Forwarder
+        forward_all :complaints, :problems, :tasks, to_chain: [:@employees, :first]
+      end
+
+## License ##
+
+This software is licensed under the MIT license, which shall be attached to any deliverable of
+this software (LICENSE) or can be found here http://www.opensource.org/licenses/MIT 

data/lib/forwarder/helpers.rb

@@ -0,0 +1,10 @@
+class Proc
+  class << self
+    def identity
+      new{ |x| x }
+    end
+    def sum
+      new{ |a,b| a+b }
+    end
+  end # class << self
+end # class Proc

data/lib/forwarder/meta.rb

@@ -0,0 +1,47 @@
+module Forwarder
+  module Meta extend self
+    ObjectContainer = Struct.new( :object )
+    def eval_body application, as, to, with
+      lambda do |*args, &blk|
+        arguments = ( [ with ].flatten + args ).compact
+#         rcv = __eval_receiver__( to )
+        rcv = Meta.eval_receiver to, self
+#        p as: as, to: to, rcv: rcv, args: arguments, app: application, self: self
+        rcv.send( as, *arguments, &(application||blk) )
+      end
+    end
+
+    def eval_chain names, context
+      names.inject context do | ctxt, name |
+        Meta.eval_symbolic_receiver name, ctxt
+      end
+    end
+
+    def eval_receiver name, context
+      case name
+      when Proc
+        context.instance_eval( &name )
+      when String, Symbol
+#        p name: name, context: context
+        Meta.eval_symbolic_receiver name, context
+      when ObjectContainer
+        name.object
+      when Array
+        Meta.eval_chain name, context
+      end
+    end
+    def eval_receiver_body
+      lambda do | name |
+      end
+    end
+
+    def eval_symbolic_receiver name, context
+      case "#{name}"
+      when /\A@/
+        context.instance_variable_get name
+      else
+        context.send name
+      end
+    end
+  end # module Meta
+end # module Forwarder

data/lib/forwarder.rb

@@ -0,0 +1,90 @@
+require 'forwardable'
+
+require 'forwarder/meta'
+module Forwarder
+
+  def forward message, opts={}, &blk
+    opts = parse_opts opts, blk
+#    p opts: opts
+    forward_without_parsing message, opts
+  end
+
+  def forward_all *messages, &blk
+    opts = messages.pop
+    raise ArgumentError, "need a Hash as last arg" unless Hash === opts
+    opts = parse_opts opts, blk
+    messages.each do | msg |
+      forward_without_parsing msg, opts
+    end
+  end
+
+  def forward_to_self message, opts={}
+    forwarding_with message, opts.merge( to: lambda{ |*args| self } )
+  end
+
+  private
+
+  def forwarding_to_object message, opts
+    target = opts[ :to_object ]
+    forwarding_with message, opts.merge( to: Meta::ObjectContainer.new(target), with: opts.fetch( :with, [] ) )
+  end
+
+  def forward_with_forwardable message, opts
+    to = opts.fetch :to
+    extend Forwardable
+    as = opts.fetch( :as, message )
+    def_delegator to, as, message
+  end
+
+  def forward_with_chain message, opts
+    return false unless opts[:to_chain]
+    forwarding_with message, opts
+  end
+  # Transform blk into a normal parameter call the metaprogramming
+  # stuff if needed and return nil iff we can do it with Forwardable
+  def forward_with_meta message, opts
+#    p [:forward_with_meta, opts]
+    if opts[:applying] || opts[:with]
+      forwarding_with message, opts
+      true
+    elsif opts[:to_object]
+      forwarding_to_object message, opts
+      true
+    end
+  end
+
+  # Whenever the forward(s) cannot be implemented by def_delegator(s) eventually
+  # this method is called
+  def forwarding_with message, opts
+#    p opts
+    application, as, to, with = opts.values_at( :applying, :as, :to, :with )
+    as ||= message
+
+   # define_method( :__eval_receiver__, &Meta.eval_receiver_body )
+    define_method( message, &Meta.eval_body( application, as, to, with ) )
+  end
+
+  def forward_without_parsing message, opts
+#    p [:forward_without_parsing, opts]
+    return if forward_with_meta message, opts
+    return if forward_with_chain message, opts
+    forward_with_forwardable message, opts
+  end
+
+  def parse_opts opts, blk
+    params = opts.values_at :to_chain, :to, :to_object
+    params.compact.tap do | pms |
+      if pms.size != 1
+        raise ArgumentError, 
+          "must passin exactly one of these kwd arguments: :to, :to_object or :to_chain, but found #{pms.join(", ")}"
+      end
+    end
+    opts.update applying: blk if blk
+    if params.first
+      opts.merge to: params.first
+    else
+      opts
+    end
+  end
+    
+end # class Module

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification 
+name: forwarder
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Robert Dober
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-01-22 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: |-
+  Ruby's core Forwardable gets the job done(barely) and produces most unreadable code.
+      This is a nonintrusive (as is Forwardable) module that allos to delegate methods to instance variables,
+      objects returned by instance_methods, other methods of the same receiver (method_alias on steroids)
+      and some more sophisticated use cases
+email: robert.dober@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/forwarder/meta.rb
+- lib/forwarder/helpers.rb
+- lib/forwarder.rb
+- LICENSE
+- README.md
+has_rdoc: true
+homepage: https://github.com/RobertDober/Forwarder
+licenses: 
+- - MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 57
+      segments: 
+      - 1
+      - 8
+      - 7
+      version: 1.8.7
+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: Making Delegation finally readable
+test_files: []
+