forwarder 0.1.0 → 0.1.1

data/README.md

@@ -17,16 +17,36 @@ 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.
 
+## Parameters ##
+
+The first parameter, (or paramters in the case of `forward_all`) is (are)
+a symbol(s) or string(s) indicating the message to be forwarded. That is
+a message of which the receiver is an instance of the module in which
+`forward` was called.
+
+Ater this we have a hash style parameter which needs a *target* specification,
+indicated by `:to`, `:to_chain` or `:to_object`. It can contain an optional
+`:as` parameter translating the method name and an equally optional `:with`
+paramter allowing us to provide paramters to the forwarded message.
+I refer to the `:as` parameter as the *translation* and the `:with` parameter
+as the *parametrization*.
+
+This might be confusing at first, but the follwing examples shall demonstrate
+how simple things really are.
+
+
 ## Examples ##
 
-* forward
+### The forward Method ###
+
+#### Target specified with :to ####
 
-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. 
+The `:to` keyword parameter and can be either a `Symbol` (or `String`), thus representing 
+an instance method or an instance variable of the receiver. It can also be a lambda that 
+will be evaluated in the receiver's context. If an arbitrary object shall be the receiver of the
+message, than the `:to` keyword can be replaced by the `:to_object`, and if the target of
+the message shall bet the result of chained method calls on the receiver `:to_chain` is
+at your service.
 
        class Employee
          extend Forwarder
@@ -37,7 +57,9 @@ 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*:
+As feared the implementation did not live up to the expectations (hence the desperate
+need of foraml specifications) and the following adjustment was made, in some desperate 
+hope to fix the *bug*:
 
       class Employee
         extend Forwarder
@@ -46,18 +68,25 @@ The following adjustment was made, in desperate hope to fix the *bug*:
 
 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.
+call of its ```boss``` method, but to it's `suggestions` method. (Well that is
+not precise wording, but we shall make an abstraction about how the object returned
+by `boss` handles the `suggestions` message.)
 
 Finally, however, the implementation looked like this
 
       class Boss
         extend Forwarder
-        forward_all :complaints, :problems, :tasks, to: first_employee
+        forward :complaints, to: first_employee
+        forward :problems, to: first_employee
+        forward :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```
+However this did not work as no `first_employee` was defined yet. This seems
+a task so simple that a method for this seems almost too much code. 
+Forwarder let us allow an implementation on itself.
+The other thing that catches (or should, at least) the reader's eye is the terrible code repetition.
+To get rid of it, we will indulge us by looking ahead to the `forward_all` method, which of course
+is just short for three `forward` calls with each of its positional parameters.
 
       class Boss
         extend Forwarder
@@ -65,12 +94,23 @@ are two possible implementations with ```Forwarder```
         forward_all :complaints, :problems, :tasks, to: :first_employee
       end
 
+Here we see the first use case of a *parametrization*, paired with a *translation*.
+Please note that the first does not necessarily imply the second, the following example
+might be reasonable code.
+
+      class Train
+        extend Forwarder
+        forward :signal, to: :@signaller, with: {strength: 10, tone: 42}
+      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```.
+examples above, but it still might make your code shorter, which is an asset
+of its own of course. Furthermore it allows a faster transation from `Forwardable`
+if it is used to delegate to instance variables.
       
-Or alternatively
+The above `Boss` case was badely written of course as `Array#first` gives us the
+perfect opportunity to get rid of the `with:` parameter, which is somehow a little
+bit of a code smell, I admit. Let us do better:
 
       class Boss
         extend Forwarder
@@ -79,14 +119,55 @@ Or alternatively
       end
 
 
-The above, however is a little bit verbose, we can shorten it with the `:to_chain`
-parameter
+### forward_all ###
+
+`forward_all` allows us to forward more then one message to a target. It is a shortcut
+for calling `forward` to each of its method parameters. As one can see in the next
+example it supports all kinds of target parameters, :to, :to_chain, but also :to_object
+
+#### Target :to_chain ####
+
+The example above is still too verbose. For what we know there is no need to define a
+delagation for the `first_employee` method. And this is the use case where `:to_chain`
+seems the right tool to use, let us see it's application at work:
 
       class Boss
         extend Forwarder
         forward_all :complaints, :problems, :tasks, to_chain: [:@employees, :first]
       end
 
+Now we forward, almost anonymously to `@employeees.first` without defining a method, or
+forwarder to bridge this gap.
+
+As you might guess, the `complaints` message is sent to the result of sending `first`
+to the `@employees` instance variable. As (no pun intended) with the `to:` version
+of `forward`, one can change the message name with the `as:` parameter, aka *translation*.
+
+It is uncommon, but not impossible to use a *translation* in `forward_all`
+
+      class Boss
+        extend Forwarder
+        forward_all :complaints, :problems, :tasks, 
+                    to_chain: [:@employees, :first],
+                    as: :request
+      end
+
+Here we go, seems quite a realistic model to me.
+
+
+## Performance ##
+
+If you are concerned about performance, but you should not yet, I have good news for you. Using
+`Forwarder` will be a performance hit. Now why should that be good news? Well it is good news
+for two reasons. Firstly by using `Forwarder` the performance hit notwithstanding you show that
+you are not concerned by premature optimization but much more with clean, concise and readnale
+design. Secondly if you run into performance issues and profiling shows that a forward target
+is hit frequently, chances are that you found one of your performance bottlenecks. Just implement
+the forward manually as a method and you shoud see quite some improvement. Now I am sure
+you'd wish that all your performance issues are *that* *easy* to fix.
+
+As I said: *Two* pieces of Good News!
+
 ## License ##
 
 This software is licensed under the MIT license, which shall be attached to any deliverable of

data/lib/forwarder.rb

@@ -1,8 +1,10 @@
 require 'forwardable'
 
+require 'forwarder/VERSION'
 require 'forwarder/meta'
 module Forwarder
 
+  # delegates (forwards) a message to an object (indicated by :to)
   def forward message, opts={}, &blk
     opts = parse_opts opts, blk
 #    p opts: opts
@@ -24,11 +26,15 @@ module Forwarder
 
   private
 
+  # Triggered by the presence of :to_object in forward's parameters
   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
 
+  # Handles the cases, where Forwardable can be used behind the scenes
+  # as a matter of fact :to was indicating a method or instance variable
+  # and :as was passed in (or defaults to the original message).
   def forward_with_forwardable message, opts
     to = opts.fetch :to
     extend Forwardable
@@ -36,6 +42,7 @@ module Forwarder
     def_delegator to, as, message
   end
 
+  # Triggered by the presence of :to_chain in forward's parameters
   def forward_with_chain message, opts
     return false unless opts[:to_chain]
     forwarding_with message, opts

data/lib/forwarder/VERSION.rb

@@ -0,0 +1,3 @@
+module Forwarder
+  VERSION = "0.1.1"
+end # module Forwarder

metadata

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