basic_assumption 0.3.0 → 0.3.1

data/lib/basic_assumption.rb

@@ -1,24 +1,87 @@
 require 'basic_assumption/configuration'
 require 'basic_assumption/default_assumption'
 
+# == BasicAssumption
+#
+# A module that allows for a declaritive idiom that maps a name to behavior
+# inside your application. It uses memoization, blocks, and the ability to
+# set default behavior to clean up certain kinds of code, particularly Rails'
+# controllers and views.
 module BasicAssumption
-  def default_assumption(symbol=nil, &block)
-    default = block_given? ? block : symbol
-    BasicAssumption::DefaultAssumption.register(self, default)
+  # Changes the default behavior for methods created by +assume+ in the
+  # current class and its descendants. If a block is given, that block
+  # will be used as the new default. Otherwise, if +name+ is provided,
+  # +BasicAssumption+ will assume it refers to a snake-cased class name
+  # that will provide the default behavior. For details on custom defaults,
+  # please see the documentation for +DefaultAssumption+.
+  #
+  # === Example
+  #
+  #  class WidgetController
+  #    extend BasicAssumption
+  #
+  #    default_assumption do
+  #      Widget.find_by_id(params[:widget_id])
+  #      log_request(current_user, params[:widget_id])
+  #    end
+  #
+  #    assume(:widget)
+  #  end
+  def default_assumption(name=nil, &block)
+    default = block_given? ? block : name
+    DefaultAssumption.register(self, default)
   end
 
+  # Declares a resource at the instance level by creating an instance method
+  # called +name+ that returns the result of +block+ if it is given or the
+  # default if it is not.
+  #
+  # === Example
+  #
+  #  class Foo
+  #    extend BasicAssumption
+  #
+  #    assume(:cute) { 'Fuzzy kittens.' }
+  #    assume 'assumption'
+  #  end
+  #
+  #  foo = Foo.new
+  #  foo.cute         #=> 'Fuzzy kittens.'
+  #  foo.assumption   #=> nil
+  #
+  # The first call to +assume+ creates an instance method +cute+ that
+  # returns the result of evaluating the block passed to it. The second call
+  # creates a method +assumption+ that returns the default result, which
+  # will be +nil+ unless the default has been overridden. See
+  # +default_assumption+ for details on overriding the default behavior.
+  #
+  # In both cases, the result is memoized and returned directly for
+  # subsequent calls.
   def assume(name, &block)
     define_method(name) do
       @basic_assumptions       ||= {}
       @basic_assumptions[name] ||= if block_given?
         instance_eval(&block)
       else
-        block = BasicAssumption::DefaultAssumption.resolve(self.class)
+        block = DefaultAssumption.resolve(self.class)
         instance_exec(name, &block)
       end
     end
     after_assumption(name)
   end
 
+  # Callback that is invoked once +assume+ has created a new method.
+  # When BasicAssumption is used in the context of ActionController, for
+  # example, this callback is used to prevent the new method from being a
+  # visible action and to make it available in views. (See the documentation
+  # for +Railtie+.)
+  #
+  #   class ActionController::Base
+  #     extend BasicAssumption
+  #     def after_assumption(name)
+  #       helper_method(name)
+  #       hide_action(name)
+  #     end
+  #   end
   def after_assumption(name); end
 end

data/lib/basic_assumption/configuration.rb

@@ -1,9 +1,20 @@
 module BasicAssumption
+  # Provides app-level configuration options for +BasicAssumption+.
+  # Useful in a Rails initializer or something similar.
   class Configuration
-    def self.configure
+    # === Example
+    #   BasicAssumption::Configuration.configure do |conf|
+    #     conf.default_assumption = Proc.new { "I <3 GitHub." }
+    #   end
+    def self.configure #:yields: config_instance
       yield self.new
     end
 
+    # Invoke this method if you want to have API compatibility
+    # with the DecentExposure library.
+    # (http://www.github.com/voxdolo/decent_exposure)
+    # Namely, this provides +expose+ and +default_exposure+ which work
+    # identically to +assume+ and +default_assumption+ (or rather, vice-versa.)
     def emulate_exposure!
       BasicAssumption.module_eval do
         alias expose assume
@@ -11,6 +22,9 @@ module BasicAssumption
       end
     end
 
+    # Allows setting the default behavior for +assume+ calls in your app. Note
+    # this is an assignment, which differs from the +default_assumption+ calls
+    # inside of classes that extend +BasicAssumption+.
     def default_assumption=(value)
       BasicAssumption::DefaultAssumption.default = value
     end

data/lib/basic_assumption/default_assumption.rb

@@ -2,12 +2,41 @@ require 'basic_assumption/default_assumption/base'
 require 'basic_assumption/default_assumption/class_resolver'
 
 module BasicAssumption
+  # Handles coordinating the default behaviors available in the application
+  # that is using the BasicAssumption library. Classes that extend
+  # +BasicAssumption+ can use the +default_assumption+ method to set their
+  # own default, like so:
+  #
+  #   class WidgetController
+  #     default_assumption { Widget.find_by_id(123) }
+  #   end
+  #
+  # Any calls to +assume+ inside the WidgetController class that do not also
+  # pass a block will use this default block as their behavior.
+  #
+  # === Providing custom default classes
+  #
+  # It is possible to pass a symbol (or string) 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+,
+  # and will use the block provided by an instance of
+  # BasicAssumption::DefaultAssumption::SimpleRails 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.
   module DefaultAssumption
-    def self.register(klass, default)
+    # Stores the +default+ as the default behavior for class +klass+ that
+    # will be used by calls to +assume+.
+    def self.register(klass, default) #:nodoc:
       registry[klass.object_id] = strategy(default)
     end
 
-    def self.resolve(klass)
+    # Returns the default behavior used by calls to +assume+ for the class
+    # +klass+.
+    def self.resolve(klass) #:nodoc:
       while !registry.has_key?(klass.object_id)
         klass = klass.superclass
         break if klass.nil?
@@ -15,15 +44,15 @@ module BasicAssumption
       registry[klass.object_id]
     end
 
-    class << self
-      attr_accessor :default
+    class << self 
+      attr_accessor :default #:nodoc:
 
       protected
-      def registry
+      def registry #:nodoc:
         @registry ||= Hash.new { |h, k| strategy(default) }
       end
 
-      def strategy(given=nil)
+      def strategy(given=nil) #:nodoc:
         case given
         when Proc
           given

data/lib/basic_assumption/default_assumption/base.rb

@@ -1,6 +1,10 @@
 module BasicAssumption
   module DefaultAssumption
+    # Provides the default behavior out of the box for calls to
+    # BasicAssumption#assume. +block+ is a method that returns a Proc instance.
     class Base
+      # Returns a proc that accepts an argument (which is, in practice, the
+      # name that was passed to BasicAssumption#assume) and returns +nil+.
       def block
         Proc.new { |name| }
       end

data/lib/basic_assumption/default_assumption/class_resolver.rb

@@ -1,6 +1,6 @@
 module BasicAssumption
   module DefaultAssumption
-    class ClassResolver
+    class ClassResolver #:nodoc:
       def self.instance(name, *args)
         new(name).instance(*args)
       end

data/lib/basic_assumption/default_assumption/simple_rails.rb

@@ -1,6 +1,19 @@
 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

data/lib/basic_assumption/rails.rb

@@ -2,12 +2,18 @@ if defined?(Rails) && Rails::VERSION::MAJOR == 3
   require 'basic_assumption/default_assumption/rails'
 
   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.
     class Railtie < Rails::Railtie
 
       initializer "basic_assumption.set_up_action_controller_base" do |app|
         ActionController::Base.class_eval do
           extend BasicAssumption
 
+          # Uses hide_action and helper_method to expose the method created
+          # by +assume+ as a helper inside of views, and also disallows the
+          # method from being called directly as a route endpoint.
           def self.after_assumption(name)
             hide_action name
             helper_method name

data/lib/basic_assumption/version.rb

@@ -1,3 +1,3 @@
 module BasicAssumption
-  VERSION = '0.3.0'
+  VERSION = '0.3.1'
 end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 3
-  - 0
-  version: 0.3.0
+  - 1
+  version: 0.3.1
 platform: ruby
 authors: 
 - Matt Yoho
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-05-12 00:00:00 -05:00
+date: 2010-05-24 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency