condi 0.0.1 → 0.0.5

data/{LICENSE → MIT-LICENSE}

@@ -1,7 +1,7 @@
 MIT LICENSE
 from http://www.opensource.org/licenses/mit-license.php
 
-Copyright (C) 2011 by Larry Kyrala
+Copyright (C) 2012 by Larry Kyrala
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -4,16 +4,25 @@ Condi
 
 Condi is a gem that you use with Rails to make it easier to cleanly implement conditional elements in a view.
 
-Condi allows you to define predicates in the controller that are callable in the view without relying on unneeded instance variables or business logic in the views.  Because the predicates are defined dynamically during a controller action, they are easy to find and easy to use without hopping around multiple files.
+Condi allows you to define boolean-valued *predicates* in the controller that are callable in the view without relying on unneeded instance variables or business logic in the views.  Because the predicates are defined dynamically during a controller action, they are easy to find and easy to use without hopping around multiple files.
+
+Condi also allows definition of *synonyms* that can return any value (not just booleans).
+
 
 API Doc: {Condi}
 
-Copyright (C) 2011 by Larry Kyrala. MIT Licensed.
+Copyright (C) 2012 by Larry Kyrala. MIT Licensed.
+
+Installation
+------------
 
-Example
--------
+    gem install condi
 
-For example, say you have a User who has various roles and a shopping Cart that contains items. Your StoreController loads the current User and Cart objects, and your store view displays the User and Cart information.  But let's say that orders over a certain amount for new customers should show a "free ground shipping" option.  With Condi you can do the following:
+
+A Simple Example
+----------------
+
+For example, say you have a User who has various roles and a shopping Cart that contains items. Your StoreController loads the current User and Cart objects, and your store view displays the User and Cart information.  But let's say that orders over a certain amount for new customers should show a "free ground shipping" option.  With Condi you can define a `predicate` that does the following:
 
 `app/controllers/store_controller.rb:`
 
@@ -35,6 +44,77 @@ For example, say you have a User who has various roles and a shopping Cart that
       <% end %>
     <% end %> 
 
+
+Predicates with Arguments
+-------------------------
+
+Say you would like to monitor your cart status and highlight items that are shipped but haven't arrived yet.  You would like to hand the collection of items off to a partial, but how can you use
+a predicate in this situation? You need a predicate with an argument!
+
+`app/controllers/store_controller.rb:`
+
+    class StoreController
+      include Condi
+      
+      def items
+        cart = Cart.find(cart_id)
+        @items = cart.items
+        predicate(:shipping?) { |item| item.status == :shipped && DeliveryService.status(item.tracking_number) !~ /arrived/ }
+      end
+    end
+
+`app/views/store/items.html.erb:`
+
+    <table>
+      <%= render :partial => "item", :collection => @items %>
+    </table>
+
+`app/views/store/_item.html.erb:`
+    
+    <% if shipping?(item) %>
+      <tr class="shipping">
+    <% else %>
+      <tr>
+    <% end %>
+      <td><%= item.to_s %></td>
+    </tr>
+ 
+
+Synonyms: defining blocks that return non-boolean values
+--------------------------------------------------------
+
+Although the previous example works, wouldn't it be nicer if we could simply define a `synonym` that
+returns the css class we need for a given item?
+
+`app/controllers/store_controller.rb:`
+
+    class StoreController
+      include Condi
+      
+      def items
+        cart = Cart.find(cart_id)
+        @items = cart.items
+        synonym(:css_for_item_status) do |item| 
+          if item.status == :shipped 
+            if DeliveryService.status(item.tracking_number) !~ /arrived/
+              "shipping"
+            else
+              "shipped"
+            end
+          else
+            "processing"
+          end
+        end
+      end
+    end
+
+`app/views/store/_item.html.erb:`
+    
+    <tr class="<%= css_for_item_status %>">
+      <td><%= item.to_s %></td>
+    </tr>
+
+
 The Problem
 -----------
 
@@ -69,7 +149,7 @@ Not the cleanest approach since business logic is in our views now.  What's anot
       <% end %>
     <% end %> 
 
-We haven't gained much except shuffling arguments around.
+We haven't gained much except shuffling arguments around and we're coupling Carts with Users unnecessarily.
 
 
 Or, we could put the predicate in a helper and remove the args:
@@ -117,14 +197,37 @@ How does this work?  Behind the scenes, `predicate` defines an instance method o
 Advantages
 ----------
 
-* Because predicates are closures, there is less of a chance that helpers and controllers and views get "mixed up" -- i.e. someone copies some code from one view to another but forgets to set the correct instance variables in the controller.
+* Because predicates are closures, you only have to worry about setting context once in the controller action instead of coordinating context across multiple files. This keeps your views functional and makes them easier to refactor without breaking existing business logic.
+
+* Placing predicates in the Controller allows them to orchestrate multiple Models without breaking encapsulation between Models.  The Controller is arguably a better place to define such predicates from an MVC perspective.
+
+* Condi makes it simple to define predicates and synonyms in the Controller and call them from the view without cluttering the helper namespace and creating a maze of unique names for every action.  Condi is more flexible.
+
+* Another advantage of the predicate being defined dynamically on the Controller is that the predicate can never be inadvertently called as an action itself.  Condi offers better encapsulation of state.
+
+* Condi works with Rails 2 and Rails 3 apps equally well.
+
+
+Disadvantages
+-------------
+
+* Controllers may become "thicker" than you might like.
+
+* It may be awkward to share predicates across multiple actions.  But if you think about it, it is awkward to share context as well.  Filters are a common solution for both problems.  You can define your predicates in a before_filter method to ensure that both the context and the predicates will be sharable. 
+
+
+Background
+----------
 
-* Also, the Model shouldn't define such predicates, because they control behavior in the view, not to mention that predicates can orchestrate several Models together with business logic.  The Controller is arguably a better place to define such predicates from an MVC perspective.
+Condi is something I wanted to explore as a response to the general problem of implementing *business logic* and rules in Rails apps. 
 
-* Condi makes it simple to define predicates in the Controller and call them from the view without cluttering the helper namespace and creating a maze of unique names for every action.  Condi is more flexible.
+* Rules-engines exist (i.e. `rools`), but are heavier-weight than Condi and can be complex to use.
 
-* Another important advantage of the predicate being defined as an instance method on the Controller during an action-view execution is that the predicate method will never exist on the Controller for subsequent actions -- hence the predicate can never be inadvertently called as an action itself.
+* Rails `cells` is a promising component framework, but is also on the heavy side and may not fit well with legacy apps.
 
+* Render-partial locals are a decent lighter-weight alternative to `cells`, but can sometimes be tricky to keep consistent across multiple controller action contexts.
 
+* Doing the "right thing" isn't always an option in business logic.  If a customer wants to pay you a ton of money but your business model doesn't support it, are you going to refuse the money or change your business model? 
 
+* If business logic turns into a mess, at least we can strive to contain the rules in one place/context so that we can identify which problems are due to inconsistency in the business rules and which are due to coding errors.
 

data/lib/condi.rb

@@ -1,22 +1,40 @@
-# Include this module in an ActionController to define predicates within an action that 
-# can be used later in the related action view. For example:
+# Include this module in an ActionController to define predicates or synonyms within an action context that 
+# can be used later in the related action view. 
+# @example
 #     class StoreController
 #       include Condi
 #       ...
 #     end
 module Condi
 
-	# define a predicate (instance method) on the controller which is callable from the related view. 
+  # define a method on the controller which is callable from the related view. 
   # @example define a predicate that determines whether or not to show a "free shipping" option.
-  #       predicate(:show_free_shipping?) { user.new_customer? && cart.amount > 100 }
-  # @param [Symbol] method_name name of the predicate method. (e.g. :show_action_button?)
-  # @param [Proc] block {} or do...end block that evaluates to true or false.
-  # @note You are not required to end your method name in a question mark, however it is conventional to do so.
-  # @see the full example in the README 
- 	def predicate(method_name, &block)
-		self.class.instance_eval do
-			define_method(method_name, &block)
-			helper_method(method_name)
-		end
-	end
+  #     predicate(:show_free_shipping?) { user.new_customer? && cart.amount > 100 }
+  # @example define a predicate that takes an element of a collection as an argument.
+  #     predicate(:shipping?) { |item| item.status == :shipped && DeliveryService.status(item.tracking_number) !~ /arrived/ }
+  # @example define a synonym that returns a css class based on item status
+  #     synonym(:css_for_item_status) do |item| 
+  #       if item.status == :shipped 
+  #         if DeliveryService.status(item.tracking_number) !~ /arrived/
+  #           "shipping"
+  #         else
+  #           "shipped"
+  #         end
+  #       else
+  #         "processing"
+  #       end
+  #     end
+  # @param [Symbol] method_name name of the predicate or synonym method. (e.g. :show_action_button?)
+  # @param [Proc] block {} or do...end block.
+  # @note You are not required to end a predicate with a question mark, however it is conventional in Ruby to do so.
+  # @see the full example in the <a href="index.html">README</a>. 
+  def predicate(method_name, &block)
+    self.class.instance_eval do
+      define_method(method_name, &block)
+      helper_method(method_name)
+    end
+  end
+
+  # a synonym is similar to a predicate but returns values besides true and false.
+  alias_method :synonym, :predicate
 end

data/test/test_condi.rb

@@ -7,6 +7,8 @@ require 'mocha'
 require 'action_controller'
 require 'condi'
 
+require 'ostruct'
+
 #require 'ruby-debug'
 
 
@@ -84,8 +86,60 @@ class CondiTest < Test::Unit::TestCase
     assert_raise RuntimeError do
       puts "ah ha!" if @controller_instance.blows_up?
     end    
-    
   end
 
+  # predicates can be used with collections!
+  def test_collection_predicate
+    @controller_instance.instance_eval do
+      predicate(:is_usa?) do |location|
+        case location
+          when :arizona then true
+          when :massachusetts then true
+          else false
+        end
+      end
+    end
+
+    assert @controller_instance.respond_to?(:is_usa?)
+
+    @locations = [:arizona, :massachusetts, :england]
+    expected_values = [true, true, false]
+    @locations.each_with_index do |location,i|
+      assert @controller_instance.is_usa?(location) == expected_values[i]
+    end
+  end
+
+  # `synonym` is an alias for `predicate` for when you want to return something besides a boolean.
+  def test_synonyms
+    @controller_instance.instance_eval do
+      synonym(:css_for_item_status) do |item| 
+        if item.status == :shipped 
+          if item.delivery_status !~ /arrived/
+            "shipping"
+          else
+            "shipped"
+          end
+        else
+          "processing"
+        end
+      end
+    end
+
+    item = OpenStruct.new
+    item.status = :shipped
+    item.delivery_status = "order left Ohio. checkin MN. checkin AZ."
+    assert @controller_instance.css_for_item_status(item) == "shipping"
+
+    item = OpenStruct.new
+    item.status = :shipped
+    item.delivery_status = "order left Ohio. checkin MN. checkin AZ. arrived HI."
+    assert @controller_instance.css_for_item_status(item) == "shipped"
+
+    item = OpenStruct.new
+    item.status = :awaiting_payment
+    item.delivery_status = ""
+    assert @controller_instance.css_for_item_status(item) == "processing"
+  end
+  
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: condi
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -19,7 +19,7 @@ extra_rdoc_files: []
 files:
 - lib/condi.rb
 - README.md
-- LICENSE
+- MIT-LICENSE
 - test/test_condi.rb
 homepage: http://github.com/coldnebo/condi
 licenses: []