decent_exposure 0.2.0

data/COPYING

@@ -0,0 +1,12 @@
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+                    Version 2, December 2004
+
+ Everyone is permitted to copy and distribute verbatim or modified
+ copies of this license document, and changing it is allowed as long
+ as the name is changed.
+
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. You just DO WHAT THE FUCK YOU WANT TO. 
+

data/README.md

@@ -0,0 +1,106 @@
+DecentExposure
+==============
+
+_Copying over instance variables is bad, mmm-kay?_
+
+DecentExposure helps you program to an interface, rather than an implementation in
+your Rails controllers.
+
+Sharing state via instance variables in controllers promotes close coupling with
+views. DecentExposure gives you a declarative manner of exposing an interface to the
+state that controllers contain, thereby decreasing coupling and improving your
+testability and overall design.
+
+Installation
+------------
+
+    gem install decent_exposure
+
+Configure your application to use it:
+
+In `config/environment.rb`:
+
+    config.gem 'decent_exposure'
+
+The Particulars
+---------------
+
+`expose` creates a method with the given name, evaluates the provided block (or
+intuits a value when no block is passed) and memoizes the result. This method is
+then declared as a `helper_method` so that views may have access to it and is
+made unroutable as an action.
+
+Examples
+--------
+
+### In your controllers
+
+When no block is given, `expose` attempts to intuit which resource you want to
+acquire:
+
+    # Category.find(params[:category_id] || params[:id])
+    expose(:category)
+
+As the example shows, the symbol passed is used to guess the class name of the
+object you want an instance of. Almost every controller has one of these. In the
+RESTful controller paradigm, you might use this in `#show`, `#edit`, `#update`
+or `#destroy`.
+
+In the slightly more complicated scenario, you need to find an instance of an
+object which doesn't map cleanly to `Object#find`:
+
+    expose(:product){ category.products.find(params[:id]) }
+
+In the RESTful controller paradigm, you'll again find yourself using this in
+`#show`, `#edit`, `#update` or `#destroy`.
+
+When the code has become complex enough to surpass a single line (and is not
+appropriate to extract into a model method), use the `do...end` style of block:
+
+    expose(:associated_products) do
+      product.associated.tap do |associated_products|
+        present(associated_products, :with => AssociatedProductPresenter)
+      end
+    end
+
+### In your views
+
+Use the product of those assignments like you would an instance variable or any
+other method you might normally have access to:
+
+    = render bread_crumbs_for(category)
+    %h3#product_title= product.title
+    = render product
+    %h3 Associated Products
+    %ul
+      - associated_products.each do |associated_product|
+      %li= link_to(associated_product.title,product_path(associated_product))
+
+Beware
+------
+
+This is an exceptionally simple tool, which provides a solitary solution. It
+must be used in conjunction with solid design approaches ("Program to an
+interface, not an implementation.") and accepted best practices (e.g. Fat Model,
+Skinny Controller). In itself, it won't heal a bad design. It is meant only to
+be a tool to use in improving the overall design of a Ruby on Rails system and
+moreover to provide a standard implementation for an emerging best practice.
+
+Development
+-----------
+
+### Running specs
+
+`DecentExposure` has been developed with the philosophy that Ruby developers shouldn't
+force their choice in RubyGems package managers on people consuming their code.
+As a side effect of that, if you attempt to run the specs on this application,
+you might get `no such file to load` errors.  The short answer is that you can
+`export RUBYOPT='rubygems'` and be on about your way (for the long answer, see
+Ryan Tomayko's [excellent
+treatise](http://tomayko.com/writings/require-rubygems-antipattern) on the
+subject).
+
+### Documentation TODO
+
+* walk-through of an actual implementation (using an existing, popular OSS Rails
+app as an example refactor).

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/lib/decent_exposure.rb

@@ -0,0 +1,21 @@
+module DecentExposure
+  def expose(name, &block)
+    define_method name do
+      @_resources       ||= {}
+      @_resources[name] ||= if block_given?
+        instance_eval(&block)
+      else
+        _class_for(name).find(params["#{name}_id"] || params['id'])
+      end
+    end
+    helper_method name
+    hide_action name
+  end
+
+  alias let expose
+
+  private
+  def _class_for(name)
+    name.to_s.classify.constantize
+  end
+end

data/rails/init.rb

@@ -0,0 +1,7 @@
+begin
+  require File.join(File.dirname(__FILE__), 'lib', 'decent_exposure') # From here
+rescue LoadError
+  require 'decent_exposure' # From gem
+end
+
+ActionController::Base.extend(DecentExposure)

data/spec/helper.rb

@@ -0,0 +1,2 @@
+require 'mocha'
+require File.join(File.dirname(__FILE__), '..', 'lib', 'decent_exposure')

data/spec/lib/decent_exposure_spec.rb

@@ -0,0 +1,95 @@
+require File.join(File.dirname(__FILE__), '..', 'helper')
+
+class Quacker
+  extend DecentExposure
+  def self.helper_method(*args); end
+  def self.hide_action(*args); end
+  def self.find(*args); end
+  def memoizable(*args); args; end
+  def params; {'proxy_id' => 42}; end
+  expose(:proxy)
+  expose(:quack){ memoizable('quack!') }
+end
+
+describe DecentExposure do
+  context "classes extending DecentExposure" do
+    it "respond to :expose" do
+      Quacker.respond_to?(:expose).should be_true
+    end
+  end
+
+  context "#expose" do
+    let(:instance){ Quacker.new }
+
+    it "creates a method with the given name" do
+      Quacker.new.methods.map{|m| m.to_s}.should include('quack')
+    end
+
+    it "prevents the method from being a callable action" do
+      Quacker.expects(:hide_action).with(:blerg)
+      Quacker.class_eval do
+        expose(:blerg){ 'ehm' }
+      end
+    end
+
+    it "declares the method as a helper method" do
+      Quacker.stubs(:hide_action)
+      Quacker.expects(:helper_method).with(:blarg)
+      Quacker.class_eval do
+        expose(:blarg){ 'uhm' }
+      end
+    end
+
+    it "returns the value of the method" do
+      instance.quack.should == %w(quack!)
+    end
+
+    it "memoizes the value of the created method" do
+      instance.expects(:memoizable).once.returns('value')
+      instance.quack
+      instance.quack
+    end
+
+    context "when no block is given" do
+      before do
+        instance.stubs(:_class_for).returns(Quacker)
+      end
+      it "attempts to guess the class of the resource to expose" do
+        instance.expects(:_class_for).with(:proxy).returns(Quacker)
+        instance.proxy
+      end
+      it "calls find with {resource}_id on the resources class" do
+        Quacker.expects(:find).with(42)
+        instance.proxy
+      end
+      context "and there is no {resource}_id" do
+        before do
+          Quacker.class_eval do
+            def params; {'id' => 24}; end
+          end
+        end
+        it "calls find with params[:id] on the resources class" do
+          Quacker.expects(:find).with(24)
+          instance.proxy
+        end
+      end
+    end
+  end
+
+  describe '#_class_for' do
+    let(:name){ 'quacker' }
+    let(:classified_name){ 'Quacker' }
+    before do
+      name.stubs(:to_s => name, :classify => classified_name)
+      classified_name.stubs(:constantize => Quacker)
+    end
+    it 'retrieves a string representation of the class name' do
+      name.expects(:classify).returns(classified_name)
+      Quacker.send(:_class_for,name)
+    end
+    it 'returns the string representation of the name as a constant' do
+      classified_name.expects(:constantize)
+      Quacker.send(:_class_for,name)
+    end
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification 
+name: decent_exposure
+version: !ruby/object:Gem::Version 
+  version: 0.2.0
+platform: ruby
+authors: 
+- Stephen Caudill
+- Jon Larkowski
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-01-31 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.9
+    version: 
+description: "\n      DecentExposure helps you program to an interface, rather than an implementation\n      in your Rails controllers.  The fact of the matter is that sharing state\n      via instance variables in controllers promotes close coupling with views.\n      DecentExposure gives you a declarative manner of exposing an interface to the\n      state that controllers contain and thereby decreasing coupling and\n      improving your testability and overall design.\n    "
+email: scaudill@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+files: 
+- COPYING
+- README.md
+- VERSION
+- lib/decent_exposure.rb
+- rails/init.rb
+has_rdoc: true
+homepage: http://github.com/voxdolo/decent_exposure
+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: A helper for creating declarative interfaces in controllers
+test_files: 
+- spec/helper.rb
+- spec/lib/decent_exposure_spec.rb