active_helper 0.1.0

data/README.textile

@@ -0,0 +1,188 @@
+h1. ActiveHelper
+
+_Finally - helpers with proper encapsulation, delegation, interfaces and inheritance!_
+
+
+h2. Introduction
+
+Helpers suck. They've always sucked, and they will suck on if we keep them in modules.
+
+ActiveHelper is an attempt to pack helpers into *classes*. This brings us a few benefits
+
+* *inheritance* helpers can be derived other helpers
+* *delegation* helpers are no longer mixed into a target- the targets @use@ the helper, where the new 
+methods are _delegated_ to the helper instances
+* *proper encapsulation* helpers don't rely blindly on instance variables - a helper defines its @needs@, the target has to provide readers
+* *interfaces* a helper clearly @provides@ methods and might @use@ additional helpers 
+
+Note that ActiveHelper is a generic helper framework. Not coupled to anything like Rails or Merb. Not providing any concrete helpers. Feel free to use clean helpers in _any_ framework (including Rails and friends)!
+
+h2. Example
+
+Let's use the bloody MVC-View example as we find in Rails or Merb (Sinatra, too?).
+
+We have a view which needs additional methods in order to render bullshit.
+
+
+h3. Using helpers
+
+The view wants to render tags using the TagHelper.
+
+<pre>
+class View
+  include ActiveHelper
+end
+
+> view.use TagHelper
+</pre>
+
+To pull-in ("import") a helper we invoke @use@ on the target instance.
+
+
+h3. Interfaces
+
+The exemplary _#tag_ method took me days to implement. 
+
+<pre>
+class TagHelper < ActiveHelper::Base
+  provides :tag
+  
+  def tag(name, attributes="")
+    "<#{name} #{attributes}>"
+  end
+end
+</pre>
+
+The helper defines a part of its interface (what goes out) as it @provides@ methods.
+
+<pre>
+> view.tag(:form)       # => "<form>"
+</pre>
+
+
+h3. Inheritance
+
+The real power of OOP is inheritance, so why should we throw away that in favor of modules?
+
+<pre>
+class FormHelper < TagHelper
+  provides :form_tag
+  
+  def form_tag(destination)
+    tag(:form, "action=#{destination}") # inherited from TagHelper.
+  end
+end
+</pre>
+
+That's _a bit_ cleaner than blindly including 30 helper modules in another helper in another helper, isn't it?
+
+<pre>
+> view.use FormHelper
+> view.tag(:form)               # => "<form>"
+> view.form('apotomo.de')       # => "<form action=apotomo.de>"
+</pre>
+
+Obviously the view can invoke stuff from the _FormHelper_ itself and inherited methods that were exposed with @provides@.
+
+h3. Delegation as Multiple Inheritance
+
+What if the _#form_tag_ method needs to access another helper? In Rails, this would simply be
+
+<pre>
+  def form_tag(destination)
+    destination = url_for(destination)
+    tag(:form, "action=#{destination}")
+  end
+</pre>
+
+The _#url_for_ methods comes from, na, do you know it? Me neither! It's mixed-in somewhere in the depths of the helper modules.
+
+In ActiveHelper this is slightly different.
+
+<pre>
+class FormHelper < TagHelper
+  provides :form_tag
+  uses UrlHelper
+  
+  def form_tag(destination)
+    destination = url_for(destination)  # in UrlHelper.
+    tag(:form, "action=#{destination}")
+  end
+end
+</pre>
+
+Hmm, our _FormHelper_ is already derived from _ActiveHelper_, how do we import additional methods?
+
+Easy as well, the helper class @uses@ it.
+
+So we have to know _#url_for_ is located in the _UrlHelper_ and we even have to declare our helper @uses@ another one.
+That's a good thing for a) *code tidiness*, b) *good architecture* and c) *debugging*.
+
+How would the _UrlHelper_ look like?
+
+
+h3. Delegation as Interface
+
+A traditional url helper would roughly look like this:
+
+<pre>
+  def url_for(url)
+    protocol = @https_request? ? 'https' : 'http'
+    "#{protocol}://#{url}"
+  end
+</pre>
+
+Next chance, who or what did create _@https_request?_ and where does it live? That's _ugly_, boys!
+
+Our helper bets on declaring its interface, again! This time we define what goes in (a "dependency").
+
+<pre>
+class UrlHelper < ActiveHelper::Base
+  provides  :url_for
+  needs     :https_request?
+  
+  def url_for(url)
+    protocol = https_request? ? 'https' : 'http'
+    "#{protocol}://#{url}"
+  end
+end
+</pre>
+
+It defines what it @needs@ and that's all for it. Any call to _#https_request?_ (that's a _method_) is strictly delegated back to the view instance, which has to care about satisfying dependencies.
+
+Here's what happens in productive mode.
+
+<pre>
+> view.form('apotomo.de')
+# => 11:in `url_for': undefined method `https_request?' for #<View:0xb749d4fc> (NoMethodError)
+</pre>
+
+That's conclusive, the view is insufficiently geared.
+
+<pre>
+class View
+  include ActiveHelper
+  
+  def https_request?; false; end
+end
+</pre>
+
+Now, does it work?
+
+<pre>
+> view.form_tag('go.and.use/active_helper')
+# => <form action=http://go.and.use/active_helper>
+</pre>
+
+Yeah.
+
+h2. Concepts
+* Helpers are instances, when accessing a raw @@ivar@ it refers to their own instance variables
+* Dependencies between different helpers and between the target (e.g. a _View_ instance) are modelled with OOP strategies: Inheritance and the declarative @#needs@.
+* Naturally helpers can @use@ other helpers on instance level, a helper class @uses@ supporting helpers.
+
+h2. License
+
+Copyright (c) 2010, Nick Sutterer 
+
+Released under the MIT License.

data/Rakefile

@@ -0,0 +1,62 @@
+# encoding: utf-8
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require File.join(File.dirname(__FILE__), 'lib', 'active_helper', 'version')
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the active_helper library.'
+Rake::TestTask.new(:test) do |test|
+  test.libs << ['lib', 'test']
+  test.pattern = 'test/*_test.rb'
+  test.verbose = true
+end
+
+
+# Gem managment tasks.
+#
+# == Bump gem version (any):
+#
+#   rake version:bump:major
+#   rake version:bump:minor
+#   rake version:bump:patch
+#
+# == Generate gemspec, build & install locally:
+#
+#   rake gemspec
+#   rake build
+#   sudo rake install
+#
+# == Git tag & push to origin/master
+#
+#   rake release
+#
+# == Release to Gemcutter.org:
+#
+#   rake gemcutter:release
+#
+begin
+  gem 'jeweler'
+  require 'jeweler'
+
+  Jeweler::Tasks.new do |spec|
+    spec.name         = "active_helper"
+    spec.version      = ::ActiveHelper::VERSION
+    spec.summary      = %{Finally - helpers with proper encapsulation, delegation, interfaces and inheritance!}
+    spec.description  = spec.summary
+    spec.homepage     = "http://github.com/apotonick/active_helper"
+    spec.authors      = ["Nick Sutterer"]
+    spec.email        = "apotonick@gmail.com"
+
+    spec.files = FileList["[A-Z]*", File.join(*%w[{lib,test} ** *]).to_s]
+
+    spec.add_dependency 'activesupport', '>= 2.3.0' # Dependencies and minimum versions?
+  end
+
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler - or one of its dependencies - is not available. " <<
+  "Install it with: sudo gem install jeweler -s http://gemcutter.org"
+end

data/lib/active_helper.rb

@@ -0,0 +1,35 @@
+require 'active_support'
+require 'forwardable'
+
+
+module ActiveHelper
+  module GenericMethods
+    def use_for(helper_class, target)
+      extend ::SingleForwardable
+      
+      helper_ivar_name  = ivar_name_for(helper_class)
+      helper_instance   = helper_class.new(target)
+      
+      instance_variable_set(helper_ivar_name, helper_instance) 
+      helper_class.helper_methods.each do |meth|
+        def_delegator helper_ivar_name, meth
+      end
+    end
+    
+    protected
+      # Unique ivar name for the helper class in the expanding target.
+      def ivar_name_for(object)
+        ('@__active_helper_'+("#{object.to_s}".underscore.gsub(/[\/<>@#:]/, ""))).to_sym
+      end
+  end
+  
+  
+  include GenericMethods
+  # Expands the target *instance* with the provided methods from +helper_class+ by delegating 'em back to a private helper
+  # Expands only the helped instance itself, not the class.
+  def use (helper_class)
+    use_for(helper_class, self)
+  end
+end
+
+require 'active_helper/base'

data/lib/active_helper/base.rb

@@ -0,0 +1,54 @@
+module ActiveHelper
+  class Base
+    class_inheritable_array :helper_methods
+    self.helper_methods = []
+    
+    class_inheritable_array :parent_readers
+    self.parent_readers = []
+    
+    class_inheritable_array :class_helpers
+    self.class_helpers = []
+    
+    class << self
+      # Add public methods to the helper's interface. Only methods listed here will 
+      # be used to expand the target.
+      def provides(*methods)
+        helper_methods.push(*methods)
+      end
+      
+      def needs(*methods)
+        parent_readers.push(*methods).uniq!
+      end
+      
+      def uses(*classes)
+        class_helpers.push(*classes).uniq!
+      end
+    end
+    
+    
+    include GenericMethods
+    attr_reader :parent
+    
+    def initialize(parent=nil)
+      @parent = parent
+      extend SingleForwardable
+      add_parent_readers!
+      add_class_helpers!
+    end
+    
+    def use(helper_class)
+      use_for(helper_class, parent) # in GenericMethods.
+    end
+    
+    protected
+      # Delegates methods declared with #needs back to parent.
+      def add_parent_readers!
+        return if @parent.blank? or self.class.parent_readers.blank?
+        def_delegator(:@parent, self.class.parent_readers)
+      end
+      
+      def add_class_helpers!
+        self.class.class_helpers.each { |helper| use helper }
+      end
+  end
+end

data/lib/active_helper/version.rb

@@ -0,0 +1,5 @@
+# encoding: utf-8
+
+module ActiveHelper
+  VERSION = '0.1.0'.freeze
+end

data/test/active_helper_test.rb

@@ -0,0 +1,267 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+class ActiveHelperTest < Test::Unit::TestCase
+  def helper_mock(*args)
+    Class.new(::ActiveHelper::Base).new(*args)
+  end
+  
+  def helper_in(helper_class, target)
+    target.instance_variable_get(target.send(:ivar_name_for, helper_class))
+  end
+  
+  context "#initialize" do
+    setup do
+      @target = Object.new
+      @target.class.instance_eval { include ::ActiveHelper }
+      @helper_class = Class.new(::ActiveHelper::Base)
+      @greedy_class = @helper_class
+    end
+    
+    should "receive a parent per default" do
+      @helper = ::ActiveHelper::Base.new @target
+      assert_equal @helper.parent, @target
+    end
+    
+    should "also accept no parent" do
+      @helper = ::ActiveHelper::Base.new
+      assert_equal @helper.parent, nil
+    end
+    
+    
+    
+    context "declaring with #needs" do
+      setup do
+        @target.instance_eval { def bottle; "cheers!"; end }
+      end
+      
+      should_eventually "complain if parent doesn't provide accessors"
+      
+      should "delegate the method to the parent when called" do
+        @helper_class.instance_eval { needs :bottle }
+        @helper = @helper_class.new(@target)
+        @target.use @helper.class
+        
+        assert_equal "cheers!", @helper.bottle
+      end
+      
+      # DiningHelper.use GreedyHelper
+      #
+      # GreedyHelper
+      #   needs :bottle
+      #
+      # target
+      #   use DiningHelper
+      #   def bottle
+      should "always delegate to @target in helpers, for now" do
+        @greedy_class.instance_eval { needs :bottle }
+        
+        @dining = helper_mock(@target)
+        @dining.use @greedy_class
+        
+        assert_equal 'cheers!', helper_in(@greedy_class, @dining).bottle
+      end
+    end
+  end
+  
+  context "With #parent_readers and #uses," do
+    setup do
+      @target = Object.new
+      @target.class.instance_eval { include ::ActiveHelper }
+      @helper_class = Class.new(::ActiveHelper::Base)
+      @helper       = @helper_class.new
+    end
+    
+    context "#parent_reader" do
+      should "yield an empty array on a fresh instance" do
+        assert_equal [], @helper.parent_readers
+      end
+      
+      should "return the method names defined with #needs" do
+        @helper.class.instance_eval { needs :controller, :view }
+        assert_equal [:controller, :view], @helper.parent_readers
+      end
+      
+      context "with inheritance" do
+        setup do
+          @helper.class.instance_eval { needs :bottle, :glass }
+          @dining = Class.new(@helper.class).new
+        end
+        
+        should "return the inherited parent_readers names" do
+          assert_equal [:bottle, :glass], @dining.parent_readers
+        end
+        
+        should "return also the inherited parent_readers names" do
+          @dining.class.instance_eval { needs :fork }
+          assert_equal [:bottle, :glass, :fork], @dining.parent_readers
+        end
+        
+        should "return a unique'd parent_readers names list" do
+          @dining.class.instance_eval { needs :bottle }
+          assert_equal [:bottle, :glass], @dining.parent_readers
+        end
+      end
+    end
+    
+    
+  end
+  
+  context "#helper_methods and #provides" do
+    setup do
+      @helper = Class.new(::ActiveHelper::Base).new
+    end
+    
+    should "initialy yield an empty array" do
+      assert_equal [], @helper.class.helper_methods
+    end
+    
+    should "grow with calls to #provide" do
+      assert_equal [:sleep, :drink], @helper.class.provides(:sleep, :drink)
+      assert_equal [:sleep, :drink], @helper.class.helper_methods
+    end
+    
+    should "inherit provided methods from its ancestor classes" do
+      @helper.class.provides(:sleep, :drink)
+      @kid = Class.new(@helper.class).new
+      @kid.class.provides(:eat)
+      
+      assert_equal [:sleep, :drink, :eat], @kid.class.helper_methods
+    end
+  end
+  
+  context "On a Helper" do
+    setup do
+      assert_respond_to ::ActiveHelper::Base, :uses
+      @helper = Class.new(::ActiveHelper::Base).new
+      assert_respond_to @helper.class, :uses
+      assert ! @helper.respond_to?(:eat)
+      
+      class GreedyHelper < ::ActiveHelper::Base; provides :eat; end
+    end
+    
+    context "#use" do
+      should "delegate the new Helper methods" do
+        @helper.use GreedyHelper
+        assert_respond_to @helper, :eat
+      end
+      
+      should "set @parent => @target in the used Helper" do
+        @target = Object.new
+        @helper = Class.new(::ActiveHelper::Base).new(@target)
+        @helper.use GreedyHelper
+        assert_equal @target, helper_in(GreedyHelper, @helper).parent # parent of used handler is target, not the using handler!
+      end
+    end
+    
+    context "#uses" do    
+      setup do
+        @greedy_class = Class.new(::ActiveHelper::Base)
+        @greedy_class.instance_eval do
+          uses GreedyHelper
+        end
+      end
+      
+      context "with #class_helpers" do
+        should "yield an empty array on a fresh instance" do
+          @greedy_class = Class.new(::ActiveHelper::Base)
+          assert_equal [], @greedy_class.class_helpers
+        end
+        
+        should "remember the passed helpers in #class_helpers" do
+          assert_equal [GreedyHelper], @greedy_class.class_helpers
+        end
+        
+        should "inherit ancesting class_helpers" do
+          @dining_class = Class.new(@greedy_class)
+          @dining_class.instance_eval do
+            uses Object
+          end
+          
+          assert_equal [GreedyHelper, Object], @dining_class.class_helpers
+        end
+      end
+      
+      should "respond to the new delegated Helper methods" do
+        @helper.class.uses GreedyHelper
+        assert_respond_to @helper.class.new, :eat
+      end
+      
+      should "inherit helper methods to ancestors" do
+        class DiningHelper < ::ActiveHelper::Base
+          provides :drink
+          uses GreedyHelper
+          
+          def drink;end
+        end
+        
+        @helper = Class.new(DiningHelper).new
+        assert_respond_to @helper, :eat   # from uses GreedyHelper.
+        assert_respond_to @helper, :drink # from DiningHelper inheritance.
+      end
+    end
+  end
+  
+  context "On a non-helper" do
+    setup do
+      @target_class = Class.new(Object) # don't pollute Object directly.
+      @target_class.instance_eval { include ::ActiveHelper }
+      assert_respond_to @target_class, :use
+      
+      @target = @target_class.new
+      assert ! @target.respond_to?(:eat)
+      
+      class GreedyHelper < ::ActiveHelper::Base; provides :eat; end
+    end
+    
+    context "#use" do
+      should "delegate new delegated helper methods" do
+        @target.use GreedyHelper
+        assert_respond_to @target, :eat
+      end
+      
+      should "set @parent => @target in the used Helper" do
+        @target.use GreedyHelper
+        assert_equal @target, helper_in(GreedyHelper, @target).parent
+      end
+    end
+    
+    #context "#uses" do
+    #  should "delegate new delegated helper methods" do
+    #    @target.class.uses GreedyHelper
+    #    assert_respond_to @target, :eat
+    #  end
+    #  
+    #  should "inherit helper methods to non-helper class" do
+    #    class DiningHelper < ::ActiveHelper::Base
+    #      provides :drink
+    #      uses GreedyHelper
+    #      
+    #      def drink;end
+    #    end
+    #    
+    #    @helper = Class.new(DiningHelper).new
+    #    assert_respond_to @helper, :eat   # from uses GreedyHelper.
+    #    assert_respond_to @helper, :drink # from DiningHelper inheritance.
+    #  end
+    #end
+  end
+  
+  context "#ivar_name_for" do
+    setup do
+      @helper = helper_mock
+    end
+    
+    should "create a symbol for the class name" do
+      assert_equal '@__active_helper_object', @helper.send(:ivar_name_for, Object.new).to_s.sub(/0x.+/, "")
+    end
+    
+    should "create a symbol for an anonym class" do
+      assert_equal '@__active_helper_class', @helper.send(:ivar_name_for, Class.new).to_s.sub(/0x.+/, "")
+    end
+    
+    should "create a symbol for namespaced class" do
+      
+      assert_equal '@__active_helper_active_helperbase', @helper.send(:ivar_name_for, ActiveHelper::Base).to_s.sub(/0x.+/, "")
+    end
+  end 
+end

data/test/test_helper.rb

@@ -0,0 +1,4 @@
+require 'rubygems'
+require 'shoulda'
+
+require 'active_helper'

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification 
+name: active_helper
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Nick Sutterer
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-03-30 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.3.0
+    version: 
+description: Finally - helpers with proper encapsulation, delegation, interfaces and inheritance!
+email: apotonick@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.textile
+files: 
+- README.textile
+- Rakefile
+- lib/active_helper.rb
+- lib/active_helper/base.rb
+- lib/active_helper/version.rb
+- test/active_helper_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/apotonick/active_helper
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Finally - helpers with proper encapsulation, delegation, interfaces and inheritance!
+test_files: 
+- test/active_helper_test.rb
+- test/test_helper.rb