poniard 0.0.1

data/HISTORY.md

@@ -0,0 +1,5 @@
+# Poniard History
+
+## 0.0.1 - 25 November 2012
+
+* Initial release

data/LICENSE

@@ -0,0 +1,14 @@
+
+   Copyright 2012 Xavier Shay
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,220 @@
+Poniard
+=======
+
+A lightweight gem that provides an alternative to Rails controllers. It uses
+parameter based dependency injection to explicitly make dependencies available,
+rather than mixing them all in from a base class. This allows you to properly
+unit test your controllers in isolation, bringing all the design benefits of
+TDD (as opposed to "test-first" development which is more common with the
+standard integration style controller tests).
+
+Poniard is designed to be compatible with standard controllers. You can use it
+for your entire application, just one action, or anything in between.
+
+Example
+-------
+
+A poniard controller is slightly more verbose than the what you may be used to.
+In particular, you need to specify all the different dependencies you wish to
+use (`response` and `finder` in this example) as parameters to your method.
+Poniard will introspect the method before calling, and ensure that the correct
+values are passed. These values will for the most part be the same objects you
+normally deal with in Rails (`session`, `flash`, etc...).
+
+The following controller renders the default index template, setting the
+instance variables `@message`.
+
+    module Controller
+      class Registration
+        def index(response)
+          response.default message: "hello"
+        end
+      end
+    end
+
+This is more explicit than traditional controllers in two ways: passing
+variables to the template is done with an explicit method call rather than
+instance variable assignment, and dependencies that would normally be made
+available by a superclass are passed in as parameters to the method.
+
+Wiring this controller into your application is a one-liner in your normal
+controller definition.
+
+    class RegistrationsController < ApplicationController
+      include Poniard::Controller
+
+      provided_by Controller::Registration
+    end
+
+You can mix and match traditional and poniard styles. Some actions can be
+implemented in the normal controller, others can be provided by an injectable
+one.
+
+    class RegistrationsController < ApplicationController
+      include Poniard::Controller
+
+      # index action provided by this class
+      provided_by Controller::Registration
+
+      # All controller features work in harmony with poniard, such as this
+      before_filter :require_user
+
+      # update action implemented normally
+      def update
+        # ...
+      end
+    end
+
+### Sources
+
+Poniard knows about all the standard controller objects such as `response`,
+`session` and `flash`. You then layer your own domain specific definitions on
+top by creating **sources**:
+
+    class Source
+      class Registration
+        def finder
+          Registration.accepted
+        end
+
+        def current_registration
+          Registration.find(params[:id])
+        end
+      end
+    end
+
+Wire this up in the `provided_by` call:
+
+    provided_by Controller::Registration, sources: [
+      Source::Registration
+    ]
+
+You can specify as many sources as you like, making it easy to reuse logic
+across controllers.
+
+Testing
+-------
+
+Set up a common injector for the scope of your controller that knows about
+common sources that all tests require (such as `response`). Add extra required
+sources on a per test basis (`finder` in the below example).
+
+    require 'poniard/injector'
+    require 'controller/registration'
+
+    describe Controller::Registration do
+      let(:response) { double("Poniard::ControllerSource") }
+      let(:injector) { Poniard::Injector.new([OpenStruct.new(
+        response: response.as_null_object
+      )]) }
+
+      def dispatch(action, overrides = {})
+        injector.dispatch described_class.new.method(action), overrides
+      end
+
+      describe '#index' do
+        it 'should render default action with all registrations' do
+          finder = double(all: ['r1'])
+          response.should_receive(:default).with(registrations: ['r1'])
+
+          dispatch :index, finder: finder
+        end
+      end
+    end
+
+Techniques
+----------
+
+### Built-in sources
+
+Undocumented, but it is a pretty straight-forward mapping to Rails objects with
+the exception of `response`. The code is in `lib/poniard/controller_source.rb`.
+
+### Layouts
+
+If you implement a `layout` method in your controller, it will be used to
+select a layout for the controller. This is equivalent to adding a custom
+`layout` method to a standard controller.
+
+### Mime types
+
+The Rails `respond_with` API is not very OO, so is hard to test in isolation.
+Poniard provides a wrapper that allows you to provide a response object that is
+much easier to work with.
+
+    module Controller
+      class Registration
+        def index(response, finder)
+          response.respond_with RegistrationsIndexResponse, finder.all
+        end
+
+        RegistrationsIndexResponse = Struct.new(:registrations) do
+          def html(response)
+            response.default registrations: registrations
+          end
+
+          def json(response)
+            response.render json: registrations.to_json
+          end
+        end
+      end
+    end
+
+### Authorization
+
+Poniard sources can raise exceptions to indicate authorization failure, which
+can then be handled in a standard manner using `rescue_from`.
+
+    module Source
+      class Admin
+        def current_organiser(session)
+          Organiser.find_by_id(session[:organiser_id])
+        end
+
+        def authorized_organiser(current_organiser)
+          current_organiser || raise(ResponseException::Unauthorized)
+        end
+      end
+    end
+
+This can be slightly weird if the method you are authorizing does not actually
+need to interact with the organiser, since it will have a method parameter that
+is never used.
+
+    RSpec::Matchers.define :have_param do |attribute|
+      match do |obj|
+        obj.parameters.map(&:last).include?(attribute)
+      end
+    end
+
+    def instance_method(name)
+      described_class.new.method(name)
+    end
+
+    it 'requires authorization' do
+      instance_method(:index).should have_param(:authorized_organiser)
+    end
+
+Developing
+----------
+
+### Status
+
+Experimental. I've backported an existing app, added minor new features, and it
+was a pleasant experience. It needs a lot more usage before the API stabilizes,
+or it is even proved to be useful.
+
+### Compatibility
+
+Requires 1.9, should be easy to backport to 1.8 if anyone is interested. Use
+1.9 style hashes and probably relies on `methods` calls returning symbols
+rather than strings.
+
+## Support
+
+Make a [new github issue](https://github.com/xaviershay/poniard/issues/new).
+
+## Contributing
+
+Fork and patch! Please update the README and other documentation if you add
+features.

data/lib/poniard.rb

@@ -0,0 +1,3 @@
+require 'poniard/controller'
+require 'poniard/controller_source'
+require 'poniard/injector'

data/lib/poniard/controller.rb

@@ -0,0 +1,51 @@
+module Poniard
+  module Controller
+    def self.included(klass)
+      klass.extend(ClassMethods)
+    end
+
+    def inject(method)
+      injector = Injector.new [
+        ControllerSource.new(self)
+      ] + self.class.sources.map(&:new)
+      injector.dispatch self.class.provided_by.new.method(method)
+    end
+
+    module ClassMethods
+      def provided_by(klass = nil, opts = {})
+        if klass
+          methods = klass.public_instance_methods(false)
+
+          layout_method = methods.delete(:layout)
+
+          methods.each do |m|
+            class_eval <<-RUBY
+              def #{m}
+                inject :#{m}
+              end
+            RUBY
+          end
+
+          if layout_method
+            layout :layout_for_controller
+
+            class_eval <<-RUBY
+              def layout_for_controller
+                inject :layout
+              end
+            RUBY
+          end
+
+          @provided_by = klass
+          @sources = opts.fetch(:sources, []).reverse
+        else
+          @provided_by
+        end
+      end
+
+      def sources
+        @sources
+      end
+    end
+  end
+end

data/lib/poniard/controller_source.rb

@@ -0,0 +1,81 @@
+module Poniard
+  class ControllerSource
+    Response = Struct.new(:controller, :injector) do
+      def redirect_to(path, *args)
+        unless path.to_s.ends_with?('_url')
+          path = "#{path}_path"
+        end
+
+        controller.redirect_to(controller.send(path, *args))
+      end
+
+      def redirect_to_action(action)
+        controller.redirect_to action: action
+      end
+
+      def render_action(action, ivars = {})
+        render action: action, ivars: ivars
+      end
+
+      def render(*args)
+        opts = args.last
+        if opts.is_a?(Hash)
+          ivars   = opts.delete(:ivars)
+          headers = opts.delete(:headers)
+        end
+        ivars ||= {}
+        headers ||= {}
+
+        ivars.each do |name, val|
+          controller.instance_variable_set("@#{name}", val)
+        end
+
+        headers.each do |name, val|
+          controller.headers[name] = val
+        end
+
+        controller.render *args
+      end
+
+      def default(ivars)
+        ivars.each do |name, val|
+          controller.instance_variable_set("@#{name}", val)
+        end
+      end
+
+      def respond_with(klass, *args)
+        obj = klass.new(*args)
+        format = controller.request.format.symbol
+        if obj.respond_to?(format)
+          injector.dispatch obj.method(format)
+        end
+      end
+
+      def send_data(*args)
+        controller.send_data(*args)
+      end
+    end
+
+    def initialize(controller)
+      @controller = controller
+    end
+
+    def request;   @controller.request; end
+    def params;    @controller.params; end
+    def session;   @controller.session; end
+    def flash;     @controller.flash; end
+    def now_flash; @controller.flash.now; end
+
+    def response(injector)
+      Response.new(@controller, injector)
+    end
+
+    def env
+      Rails.env
+    end
+
+    def app_config
+      Rails.application.config
+    end
+  end
+end

data/lib/poniard/injector.rb

@@ -0,0 +1,43 @@
+require 'ostruct'
+
+module Poniard
+  class Injector
+    attr_reader :sources
+
+    def initialize(sources)
+      @sources = sources + [self]
+    end
+
+    def dispatch(method, overrides = {})
+      args = method.parameters.map {|_, name|
+        source = (
+          [OpenStruct.new(overrides)] +
+          sources
+        ).detect {|source| source.respond_to?(name) }
+        if source
+          dispatch(source.method(name), overrides)
+        else
+          UnknownInjectable.new(name)
+        end
+      }
+      method.call(*args)
+    end
+
+    def injector
+      self
+    end
+  end
+
+  class UnknownParam < RuntimeError; end
+
+  class UnknownInjectable < BasicObject
+    def initialize(name)
+      @name = name
+    end
+
+    def method_missing(*args)
+      ::Kernel.raise UnknownParam,
+        "Tried to call method on an uninjected param: #{@name}"
+    end
+  end
+end

data/lib/poniard/version.rb

@@ -0,0 +1,3 @@
+module Poniard
+  VERSION = '0.0.1'
+end

data/poniard.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/poniard/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Xavier Shay"]
+  gem.email         = ["contact@xaviershay.com"]
+  gem.description   =
+    %q{A dependency injector for Rails, allows you to write clean controllers.}
+  gem.summary       =
+    %q{A dependency injector for Rails, allows you to write clean controllers.}
+  gem.homepage      = "http://github.com/xaviershay/poniard"
+
+  gem.executables   = []
+  gem.required_ruby_version = '>= 1.9.0'
+  gem.files         = Dir.glob("{spec,lib}/**/*.rb") + %w(
+                        README.md
+                        HISTORY.md
+                        LICENSE
+                        poniard.gemspec
+                      )
+  gem.test_files    = Dir.glob("spec/**/*.rb")
+  gem.name          = "poniard"
+  gem.require_paths = ["lib"]
+  gem.version       = Poniard::VERSION
+  gem.has_rdoc      = false
+  gem.add_development_dependency 'rspec', '~> 2.11'
+  gem.add_development_dependency 'rake'
+end

data/spec/injector_spec.rb

@@ -0,0 +1,15 @@
+require 'poniard/injector'
+
+describe Poniard::Injector do
+  it 'yields a fail object when source is unknown' do
+    called = false
+    m = ->(unknown) {
+      ->{
+        unknown.bogus
+      }.should raise_error(Poniard::UnknownParam)
+      called = true
+    }
+    Poniard::Injector.new([]).dispatch(m)
+    called.should be_true
+  end
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: poniard
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Xavier Shay
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-11-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.11'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A dependency injector for Rails, allows you to write clean controllers.
+email:
+- contact@xaviershay.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- spec/injector_spec.rb
+- lib/poniard/controller.rb
+- lib/poniard/controller_source.rb
+- lib/poniard/injector.rb
+- lib/poniard/version.rb
+- lib/poniard.rb
+- README.md
+- HISTORY.md
+- LICENSE
+- poniard.gemspec
+homepage: http://github.com/xaviershay/poniard
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: A dependency injector for Rails, allows you to write clean controllers.
+test_files:
+- spec/injector_spec.rb