basic_assumption 0.3.7 → 0.3.8

data/README.rdoc

@@ -1,8 +1,11 @@
 == BasicAssumption
 
-A clone of DecentExposure with a psuedo-modular interface for providing
-custom defaults. It provides a declarative interface for specifying helper
-methods that is useful in Rails applications.
+BasicAssumption is a gem meant to let you declare resources inside of a class
+in a concise manner. It is targetted at making Rails controllers and views
+cleaner.
+
+It is a clone of DecentExposure that adds a psuedo-modular interface for
+providing custom defaults and some useful defaults out of the box.
 
 === What is DecentExposure?
 
@@ -10,12 +13,10 @@ It's a plugin written by {Stephen Caudill}[http://voxdolo.me/] that provides a w
 cleaning up Rails controller and view code. Find it at
 {its GitHub repository}[http://github.com/voxdolo/decent_exposure].
 
-It represents an idiom for writing certain kinds of code in a declarative way.
-Particularly in your Rails apps, it's worth checking out. BasicAssumption is
-another implementation of the idiom. It exists largely because I felt like
-practicing writing a gem, though it does have a differentiating feature or two.
-Check the BasicAssumption::Configuration options for enabling compatibility
-with the DecentExposure API.
+DecentExposure coins an idiom for writing certain kinds of code in a declarative
+way. Particularly for your Rails apps, it's worth checking out. BasicAssumption
+is another implementation of the idiom. Check the BasicAssumption::Configuration
+options for enabling compatibility with the DecentExposure API.
 
 == Install BasicAssumption
 
@@ -84,8 +85,39 @@ And then inside of the 'widgets/purchase_complete.html.haml' view:
           %td= widget.manufacturer
 
 By calling +assume+ with the symbol :widget and passing it a block, an instance
-method is created on the controller class that is also exposed as a helper
-inside views. For more details on how BasicAssumption is wired into your Rails
+method +widget+ is created on the controller that is also exposed as a helper
+inside views.
+
+==== Special cases in controllers
+
+A named resource created with +assume+ may be used in multiple controller
+actions, or the same view template or partial referencing the named
+resource may be rendered by more than one action. There will be times when
+the behavior given to +assume+ is correct for most cases save one or two. It's
+possible to override the value of the resource method within a particular
+action to accommodate an exceptional case more easily. For example:
+
+    class WidgetController < ActionController::Base
+      assume :widget
+
+      def show
+      end
+
+      def show_mine
+        self.widget = current_user.widgets.find(params[:widget_id])
+        render :action => 'show'
+      end
+
+      def destroy
+        widget.destroy if widget.owned_by? current_user
+      end
+    end
+
+In this case, the +show_mine+ action overrides the value of widget so that it
+may reuse the view template for the regular +show+ action. Overriding the
+assumed resource should be the exception, not the rule.
+
+For more details on how BasicAssumption is wired into your Rails
 app, please see the BasicAssumption::Railtie documentation.
 
 === When to use it
@@ -115,47 +147,78 @@ would become this:
       assume :record
     end
 
-and would have the added benefit of not tossing instance variables around.
+and would provide the added benefit of not tossing instance variables around.
 If a controller has protected or hidden methods that find or create instance
 variables used in actions and/or views, it might be cleaner to use an
-assumption instead.
+assumption instead. This:
+
+    class CompanyController < ActionController::Base
+
+      def show
+        @company = Company.find(params[:company_id])
+      end
+
+      def unique_groups
+        @unique_groups = Group.unique_groups(@company)
+      end
+      helper_method :unique_groups
+      hide_action   :unique_groups
+
+    end
+
+could instead be written as:
+
+    class CompanyController < ActionController::Base
+
+      assume :company
+      assume(:unique_groups) { Group.unique_groups(company) }
+
+    end
 
 BasicAssumption allows for a simple, declarative, and very lightweight approach
-to RESTful controllers.  It also can make for a cleaner, more testable interface
-for controller or view testing. There may even be uses outside of Rails apps.
-Give it a shot.
+to RESTful controllers.  It also tends to make for a cleaner, more testable
+interface for controller or view testing. There may even be uses outside of
+Rails apps. Give it a shot.
 
-=== Defaults
+== Defaults
 
 BasicAssumption allows for default behavior to be associated with methods
 created by +assume+ whenever a block is not passed. Here is a simple example:
 
-    class WidgetController < ActionController::Base
-      default_assumption { Widget.find(params[:id]) }
-      assume(:widget)
+    class MariosController < ActionController::Base
+      default_assumption { "It's a me, Mario!" }
+      assume :mario
 
       ...
     end
 
-This will provide the same behavior as the similar example above. It is also
-possible to pass a proc or lambda directly.
+    MariosController.new.mario    #=> 'It's a me, Mario!'
 
-Finally, a symbol may be passed if it corresponds to a
-specifically-defined helper class that came packaged with the library or was
-provided by the application.
+In this case, any calls to +assume+ that don't provide a block will create
+methods that return the string "It's a me, Mario!".
+
+In addition to passing a default block, a symbol may be passed if it corresponds
+to a specifically-defined helper class that came packaged with the
+BasicAssumption library or was provided by the application as a custom default.
+See below for more information on providing custom defaults.
+
+Specifying a built-in or application-defined default can be done on +assume+
+calls as well.
+
+    assume :luigi, :using => :luigi_strategy
 
 === In Rails
 
 In Rails, a useful default is already active out of the box. It attempts to
-guess the name of a class derived from ActiveRecord::Base and do a find on it
-based on an id available in the +params+ of the request. Because of this, the
+guess the name of a class derived from ActiveRecord::Base and perform a find on
+it based on an id available in the +params+ of the request. Because of this, the
 following two constructs would be equivalent in your controllers:
 
     assume(:film) { Film.find(params[:film_id] || params[:id]) }
     # The above line is exactly the same as:
     assume(:film)
 
-Please see +SimpleRails+ for details of implementation. Because finding on :id
+Please see +Rails+ for implementation details . Because finding on :id
 could be considered dangerous, there is another default available for use,
 +CautiousRails+, that will only find on :name_id. (In the example above,
 this would be :film_id.) Enable that for one of your controllers like so:
@@ -170,27 +233,64 @@ description of how it works.
 
 Default assumptions are inherited by derived classes.
 
-=== Supplying custom default behavior classes
+== Supplying custom default behavior classes
 
 There is an ability to provide custom, modular default extensions to
 BasicAssumption and then use them by passing a symbol, as in the following:
 
     class WidgetController < ActionController::Base
-      default_assumption :my_custom_default_class
+      default_assumption :my_custom_rails_default
+    end
+
+The symbol is converted to a class in the same manner as Rails
+classify/constantize operates, but it is looked up in the
+BasicAssumption::DefaultAssumption namespace. The following code implements the
+custom default specified in the preceding example. It reimplements the behavior
+that is active by default within Rails.
+
+    module BasicAssumption
+      module DefaultAssumption
+        class MyCustomRailsDefault
+
+          def initialize(name=nil, params={})
+            @name   = name.to_s
+            @lookup = params['id']
+          end
+
+          def block
+            klass = self.class
+            Proc.new do |name|
+              klass.new(name, params).result
+            end
+          end
+
+          def result
+            model_class.find(@lookup)
+          end
+
+          # Rely on ActiveSupport methods
+          def model_class
+            name.classify.constantize
+          end
+        end
+      end
     end
 
-The symbol is converted to a class in the same manner as Rails classify/
-constantize operates, but it is looked up in the
-BasicAssumption::DefaultAssumption namespace. Please see the documentation for
-+DefaultAssumption+ for a discussion and +SimpleRails+ for an example of this.
+The only method that BasicAssumption depends on in the interface of custom
+default classes is the +block+ method. Note the hoops that have to be jumped
+through inside the implementation of +block+ in this example. Keep in mind the
+implications of evaluating the +Proc+ returned by +block+ using +instance_eval+
+(or +instance_exec+).
 
-=== Configuration
+== Configuration
 
-There are a couple of simple configuration settings that can be set inside of
+There are a couple of configuration settings that can be set inside of
 a configuration block that can be used in places such as Rails initializer
-blocks. For more information, see BasicAssumption::Configuration.
+blocks. #emulate_exposure! will alias +assume+ and +default_assumption+ to
++expose+ and +default_exposure+, respectively. You can also set the app-wide
+default behavior. For more information, see BasicAssumption::Configuration.
 
-== Issues
+== Issues to note
 
 === Memoization
 
@@ -208,30 +308,24 @@ be observed.
 Using BasicAssumption may change the exception handling strategy inside your
 classes. In Rails, the +rescue_from+ method may be useful.
 
-=== Other
-
-There are probably others, and when I remember what they were, I'll write them
-up.
-
 == Hacking/running specs
 
 There is nothing special about running the specs, aside from ensuring the
 RUBYOPT environment variable is set to your preferred Ruby dependency
-manager. For example, if RubyGems:
+manager. For example, if that's RubyGems:
 
     export RUBYOPT=rubygems
 
 If you're unfamiliar with why this is being done, take a look
 {here for a start}[http://tomayko.com/writings/require-rubygems-antipattern].
-Other than that, please feel free to fork and send back pull requests! Thanks.
+Other than that, fork away and send back pull requests! Thanks.
 
 == But should I use it?
 
 Sure! Absolutely. I think it's a cool idea that lets you cut down on line
 noise, particularly in your Rails controllers. You may want to consider going
-with {DecentExposure}[http://github.com/voxdolo/decent_exposure], simply
-because it's used by much of {Hashrocket}[http://www.hashrocket.com/]
-and BasicAssumption is used, so far as I know, only by me. But so far as I know
-BasicAssumption is pretty solid, and I'm happy to accept bug fixes and field
-feature requests. If you use it, feel free to let me know! Email mby [at]
-mattyoho [dot] com with questions, comments, or non-sequiters.
+with {DecentExposure}[http://github.com/voxdolo/decent_exposure] instead, simply
+because it's used by much of {Hashrocket}[http://www.hashrocket.com/].
+But so far as I know, BasicAssumption is pretty solid. Feel free to let me know
+if you use it! Email mby [at] mattyoho [dot] com with questions, comments, or
+non-sequiters.

data/lib/basic_assumption.rb

@@ -67,7 +67,7 @@ module BasicAssumption
       @basic_assumptions[name] ||= if block_given?
         instance_eval(&block)
       else
-        which = strategy[:with] || self.class
+        which = strategy[:using] || self.class
         block = DefaultAssumption.resolve(which)
         instance_exec(name, &block)
       end

data/lib/basic_assumption/default_assumption.rb

@@ -18,15 +18,15 @@ module BasicAssumption
   #
   # It is possible to pass a symbol instead of a block to the
   # +default_assumption+ call. BasicAssumption out of the box will understand
-  # the symbol :simple_rails as an option passed to +default_assumption+,
+  # the symbol :rails as an option passed to +default_assumption+,
   # and will use the block provided by an instance of
-  # BasicAssumption::DefaultAssumption::SimpleRails as the default behavior.
+  # BasicAssumption::DefaultAssumption::Rails as the default behavior.
   #
   # BasicAssumption will use the same process for any symbol passed to
   # +default_assumption+. If you pass it :my_custom_default it will attempt
   # to find a class BasicAssumption::DefaultAssumption::MyCustomDefault that
   # provides a +block+ instance method, and use the result as the default
-  # behavior. See the +SimpleRails+ class for an example.
+  # behavior. See the +Rails+ class for an example.
   module DefaultAssumption
     def self.register(klass, default) #:nodoc:
       registry[klass.object_id] = strategy(default)

data/lib/basic_assumption/default_assumption/cautious_rails.rb

@@ -1,7 +1,9 @@
+require 'basic_assumption/default_assumption/rails'
+
 module BasicAssumption
   module DefaultAssumption
     # Custom default behavior in the context of Rails.
-    class CautiousRails < BasicAssumption::DefaultAssumption::Base
+    class CautiousRails < BasicAssumption::DefaultAssumption::Rails
       # Returns a block that will attempt to find an instance of
       # an ActiveRecord model based on the name that was given to
       # BasicAssumption#assume and an id value in the parameters.
@@ -16,10 +18,12 @@ module BasicAssumption
       #     assume(:widget) { Widget.find(params[:widget_id]) }
       #   end
       def block
-        Proc.new do |name|
-          model_class = name.to_s.classify.constantize
-          model_class.find(params["#{name}_id"])
-        end
+        super
+      end
+
+      protected
+      def lookup_id #:nodoc:
+        params["#{name}_id"]
       end
     end
   end

data/lib/basic_assumption/default_assumption/rails.rb

@@ -1,2 +1,43 @@
-require 'basic_assumption/default_assumption/simple_rails'
+module BasicAssumption
+  module DefaultAssumption
+    # Custom default behavior in the context of Rails.
+    class Rails < BasicAssumption::DefaultAssumption::Base
+      attr_reader :name, :params #:nodoc:
 
+      def initialize(name=nil, params={}) #:nodoc:
+        @name, @params = name.to_s, params
+      end
+      # Returns a block that will attempt to find an instance of
+      # an ActiveRecord model based on the name that was given to
+      # BasicAssumption#assume and an id value in the parameters.
+      # The following two examples would be equivalent:
+      #
+      #   class WidgetController < ActionController::Base
+      #     assume :widget
+      #   end
+      #
+      #   class WidgetController < ActionController::Base
+      #     assume(:widget) { Widget.find(params[:widget_id] || params[:id]) }
+      #   end
+      def block
+        klass = self.class
+        Proc.new do |name|
+          klass.new(name, params).result
+        end
+      end
+
+      def result #:nodoc:
+        model_class.find(lookup_id)
+      end
+
+      protected
+      def lookup_id #:nodoc:
+        params["#{name}_id"] || params['id']
+      end
+
+      def model_class #:nodoc:
+        @model_class ||= name.classify.constantize
+      end
+    end
+  end
+end

data/lib/basic_assumption/default_assumption/restful_rails.rb

@@ -1,20 +1,17 @@
+require 'basic_assumption/default_assumption/rails'
+
 module BasicAssumption
   module DefaultAssumption
     # Restful default behavior in the context of Rails
-    class RestfulRails < BasicAssumption::DefaultAssumption::Base
+    class RestfulRails < BasicAssumption::DefaultAssumption::Rails
       attr_reader :action,
-                  :lookup_id,
-                  :name,
                   :page,
-                  :params,
                   :per_page,
                   :resource_attributes #:nodoc:
 
       def initialize(name = nil, params = {}) #:nodoc:
+        super
         @action    = params['action']
-        @lookup_id = params['id']
-        @name      = name.to_s
-        @params    = params
         @resource_attributes = params[singular_name]
 
         if @page = params['page']
@@ -52,10 +49,7 @@ module BasicAssumption
       # results, also observing a +per_page+ value in the +params+ hash or
       # defaulting to 15 if one is not found.
       def block
-        klass = self.class
-        Proc.new do |name|
-          klass.new(name, params).result
-        end
+        super
       end
 
       def result #:nodoc:
@@ -86,16 +80,16 @@ module BasicAssumption
         action.eql?('index') && plural_name.eql?(name)
       end
 
-      def lookup?
-        params['id'].present?
+      def lookup_id #:nodoc:
+        params['id']
       end
 
-      def make? #:nodoc:
-        %w(new create).include?(action) || !lookup?
+      def lookup? #:nodoc:
+        lookup_id.present?
       end
 
-      def model_class #:nodoc:
-        @model_class ||= name.classify.constantize
+      def make? #:nodoc:
+        %w(new create).include?(action) || !lookup?
       end
 
       def page? #:nodoc:

data/lib/basic_assumption/rails.rb

@@ -4,7 +4,7 @@ if defined?(Rails) && Rails::VERSION::MAJOR == 3
   module BasicAssumption
     # Must be required explicitly in Rails 3. Extends ActionController::Base
     # with BasicAssumption, sets the default assumption behavior to be the
-    # :simple_rails behavior, and sets up an +after_assumption+ hook.
+    # :rails behavior, and sets up an +after_assumption+ hook.
     class Railtie < Rails::Railtie
 
       initializer "basic_assumption.set_up_action_controller_base" do |app|
@@ -21,7 +21,7 @@ if defined?(Rails) && Rails::VERSION::MAJOR == 3
         end
 
         BasicAssumption::Configuration.configure do |config|
-          config.default_assumption = :simple_rails
+          config.default_assumption = :rails
         end
       end
     end

data/lib/basic_assumption/version.rb

@@ -1,3 +1,3 @@
 module BasicAssumption
-  VERSION = '0.3.7'
+  VERSION = '0.3.8'
 end

data/rails/init.rb

@@ -11,5 +11,5 @@ ActionController::Base.class_eval do
 end
 
 BasicAssumption::Configuration.configure do |config|
-  config.default_assumption = :simple_rails
+  config.default_assumption = :rails
 end

data/spec/lib/basic_assumption/default_assumption/{simple_rails_spec.rb → rails_spec.rb}

@@ -1,12 +1,12 @@
 require 'spec_helper'
 require 'active_support'
-require 'basic_assumption/default_assumption/simple_rails'
+require 'basic_assumption/default_assumption/rails'
 
-describe BasicAssumption::DefaultAssumption::SimpleRails do
+describe BasicAssumption::DefaultAssumption::Rails do
   class Model; end
 
   context "#block" do
-    let(:default) { BasicAssumption::DefaultAssumption::SimpleRails.new }
+    let(:default) { BasicAssumption::DefaultAssumption::Rails.new }
     let(:params)  { stub(:[] => 42) }
 
     before(:each) do

data/spec/lib/basic_assumption/default_assumption_spec.rb

@@ -1,5 +1,5 @@
 require 'spec_helper'
-require 'lib/basic_assumption/default_assumption/simple_rails'
+require 'lib/basic_assumption/default_assumption/rails'
 
 describe BasicAssumption::DefaultAssumption do
   let(:mod) { BasicAssumption::DefaultAssumption }
@@ -25,8 +25,8 @@ describe BasicAssumption::DefaultAssumption do
       mod.send(:strategy, a_proc).call.should eql(:block)
     end
     it "returns the block of a class in the BasicAssumption::DefaultAssumption namespace when given a symbol" do
-      mod::SimpleRails.should_receive(:new).and_return(stub(:block => :block))
-      mod.send(:strategy, :simple_rails).should eql(:block)
+      mod::Rails.should_receive(:new).and_return(stub(:block => :block))
+      mod.send(:strategy, :rails).should eql(:block)
     end
     it "returns the block of a Base instance otherwise" do
       mod.send(:strategy, nil).call.should be_nil

data/spec/lib/basic_assumption_spec.rb

@@ -44,7 +44,7 @@ describe BasicAssumption do
         context "when a strategy is passed to #assume" do
           it "looks up the strategy from the existing defaults to provide the behavior of the instance method" do
             extender_class.class_eval do
-              assume :looked_up, :with => :strategy
+              assume :looked_up, :using => :strategy
             end
             BasicAssumption::DefaultAssumption.should_receive(:resolve).with(:strategy).and_return(Proc.new {})
             extender_instance.looked_up

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 3
-  - 7
-  version: 0.3.7
+  - 8
+  version: 0.3.8
 platform: ruby
 authors: 
 - Matt Yoho
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-05-02 00:00:00 -05:00
+date: 2010-06-04 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -79,7 +79,6 @@ files:
 - lib/basic_assumption/default_assumption/class_resolver.rb
 - lib/basic_assumption/default_assumption/rails.rb
 - lib/basic_assumption/default_assumption/restful_rails.rb
-- lib/basic_assumption/default_assumption/simple_rails.rb
 - lib/basic_assumption/rails.rb
 - lib/basic_assumption/version.rb
 - rails/init.rb
@@ -121,5 +120,5 @@ test_files:
 - spec/lib/basic_assumption/default_assumption/base_spec.rb
 - spec/lib/basic_assumption/default_assumption/cautious_rails_spec.rb
 - spec/lib/basic_assumption/default_assumption/class_resolver_spec.rb
+- spec/lib/basic_assumption/default_assumption/rails_spec.rb
 - spec/lib/basic_assumption/default_assumption/restful_rails_spec.rb
-- spec/lib/basic_assumption/default_assumption/simple_rails_spec.rb

data/lib/basic_assumption/default_assumption/simple_rails.rb

@@ -1,26 +0,0 @@
-module BasicAssumption
-  module DefaultAssumption
-    # Custom default behavior in the context of Rails.
-    class SimpleRails < BasicAssumption::DefaultAssumption::Base
-      # Returns a block that will attempt to find an instance of
-      # an ActiveRecord model based on the name that was given to
-      # BasicAssumption#assume and an id value in the parameters.
-      # The following two examples would be equivalent:
-      #
-      #   class WidgetController < ActionController::Base
-      #     assume :widget
-      #   end
-      #
-      #   class WidgetController < ActionController::Base
-      #     assume(:widget) { Widget.find(params[:widget_id] || params[:id]) }
-      #   end
-      def block
-        Proc.new do |name|
-          model_class = name.to_s.classify.constantize
-          model_class.find(params["#{name}_id"] || params['id'])
-        end
-      end
-    end
-  end
-end
-