leap 0.4.6 → 0.5.0

data/lib/leap/decision.rb

@@ -1,18 +1,36 @@
 module Leap
+  # Encapsulates a set of strategies to determine a potentially non-obvious attribute of a Leap subject.
   class Decision
-    attr_reader :goal, :signature_method, :committees, :minutes
+    # The goal of the decision, as defined by the first parameter of <tt>Leap::Subject#decide</tt>.
+    attr_reader :goal
     
+    # The method name used to retrieve a curated hash of the subject instance's attributes for use during deliberation. Initially defined by the <tt>:with</tt> option on <tt>Leap::Subject#decide</tt>. 
+    attr_reader :signature_method
+    
+    # Returns the array of committees defined within the decision block.
+    attr_reader :committees
+    
+    # Creates a <tt>Leap::Decision</tt> object with a given goal.
+    #
+    # Generally you won't initialize a <tt>Leap::Decision</tt> directly; <tt>Leap::Subject#decide</tt> does it for you.
+    #
+    # @param [Symbol] goal The ultimate goal of the decision--what are we trying to decide about the subject?
+    # @param [Hash] options
+    # @option [optional, Symbol] with The name of an instance method on the subject that will, when called, provide a Hash of curated attributes about itself. <a href="http://github.com/brighterplanet/charisma">Charisma</a> is great for this. If this option is not provided, Leap will use a low-budget alternative (see <tt>Leap::ImplicitAttributes</tt>)
     def initialize(goal, options)
       @goal = goal
       @signature_method = options[:with] || :_leap_implicit_attributes
       @committees = []
     end
     
-    def make(subject, *considerations)
-      characteristics = subject.send(subject.class.decisions[goal].signature_method)
+    # Make the decision.
+    #
+    # General you won't call this directly, but rather use the dynamically-created method with this decision's goal as its name on the subject instance.
+    # @see Leap::GoalMethodsDocumentation
+    def make(characteristics, *considerations)
       options = considerations.extract_options!
       committees.reject { |c| characteristics.keys.include? c.name }.reverse.inject(Deliberation.new(characteristics)) do |deliberation, committee|
-        if report = committee.report(subject, deliberation.characteristics, considerations, options)
+        if report = committee.report(deliberation.characteristics, considerations, options)
           deliberation.reports.unshift report
           deliberation.characteristics[committee.name] = report.conclusion
         end
@@ -21,6 +39,11 @@ module Leap
     end
     
     include ::Blockenspiel::DSL
+
+    # Define a committee within the decision.
+    #
+    # Used within a <tt>Leap::Subject#decide</tt> block to define a new committee. See <tt>Leap::Committee</tt> for details.
+    # @param [Symbol] name The name of the attribute that the committee will return.
     def committee(name, &blk)
       committee = ::Leap::Committee.new(name)
       @committees << committee

data/lib/leap/deliberation.rb

@@ -1,17 +1,27 @@
 module Leap
+  # Encapsulates a single computation of a Leap subject's decision, as performed on an instance of that subject class.
   class Deliberation
+    # Accumulates knowledge about the Leap subject instance, beginning with the instance's explicit attributes, and later augmented by committee proceedings.
     attr_accessor :characteristics
+    
+    # Accumulates proceedings of the deliberation, including conclusions and methodology.
     attr_accessor :reports
     
+    # Create a new deliberation, to be made in light of the provided characteristics of the Leap subject instance.
+    # @param [Hash] characteristics The initial set of characteristics made available to committees during deliberation. 
     def initialize(characteristics)
       self.characteristics = characteristics
       self.reports = []
     end
     
+    # Convenience method to access values within the deliberation's characteristics hash.
+    # @param [Symbol] characteristic
     def [](characteristic)
       characteristics[characteristic]
     end
     
+    # Report which named protocols the deliberation incidentally complied with.
+    # @return [Array]
     def compliance
       reports.map(&:quorum).map(&:compliance).inject do |memo, c|
         next c unless memo

data/lib/leap/deliberations_accessor.rb

@@ -0,0 +1,16 @@
+module Leap
+  # Provides an intelligent accessor method for a subject instance's deliberations.
+  # @see Leap::Subject
+  module DeliberationsAccessor
+    # Returns a special hash of deliberations that will make necessary decisions if they have not yet been made.
+    def deliberations
+      @deliberations ||= Hash.new do |h, k|
+        return nil unless respond_to? k
+        send k
+        h[k]
+      end
+    end
+  end
+end
+      
+

data/lib/leap/goal_methods_documentation.rb

@@ -0,0 +1,20 @@
+module Leap
+  # Used strictly for documenting the dynamic methods created by <tt>Leap::Subject#decide</tt>
+  #
+  # @note This module is provided due to limitations in the YARD documentation system.
+  # @see Leap::Subject#decide
+  module GoalMethodsDocumentation
+    
+    # @overload your_goal_name(*considerations = [], options = {})
+    #   Computes a previously-defined Leap decision named <tt>your_goal_name</tt>.
+    #   
+    #   @param [optional, Array] considerations An ordered array of additional details, immutable during the course of deliberation, that should be made available to each committee for provision, upon request, to quorums.
+    #   @param [optional, Hash] options Additional options
+    #   @option comply Force the ensuing deliberation to comply with one or more "protocols" by only respecting quorums that comply with this (these) protocol(s). Protocols can be anything--a Fixnum, a String, whatever, but by tradition a Symbol. If compliance is required with multiple protocols, they should be passed in an Array.
+    #   @return The value of the newly-decided goal.
+    #   @raise [Leap::NoSolutionError] Leap could not compute the decision's goal on this subject instance given its characteristics and compliance constraint. 
+    def method_missing(*args, &blk)
+      super
+    end
+  end
+end

data/lib/leap/implicit_attributes.rb

@@ -1,7 +1,11 @@
 module Leap
+  # Ideally Leap subjects will provide methods that return a curated hash of attributes suitable for Leap decisions and indicate them with the <tt>:with</tt> option on <tt>Leap::Subject#decide</tt>.
+  # If this type of method is not available, or if it is not properly indicated, Leap will fall back to using the stopgap in this module.
   module ImplicitAttributes
+    # Provides an articifial attributes hash constructed from the object's instance variables.
+    # @return [Hash]
     def _leap_implicit_attributes
-      Hash[*instance_variables.map { |variable| variable.to_s.delete('@').to_sym }.zip(instance_variables.map { |variable| instance_variable_get variable }).flatten]
+      Hash[*instance_variables.map { |variable| variable.to_s.delete('@').to_sym }.zip(instance_variables.map { |variable| instance_variable_get variable }).flatten].except(:deliberations)
     end
   end
 end

data/lib/leap/no_solution_error.rb

@@ -0,0 +1,40 @@
+require 'active_support/inflector'
+
+module Leap
+  # Raised when a Leap solution cannot be found. 
+  #
+  # If this is raised unexpectedly, try removing compliance constraints or double-checking that you have enough quorums within mainline committees to provide conclusions given any combination of input data.
+  class NoSolutionError < ArgumentError;
+    # Create the excpetion
+    def initialize(options = {})
+      @goal = options[:goal]
+      @deliberation = options[:deliberation]
+      
+      if @goal
+        help = "No solution was found for \"#{@goal}\"."
+      else
+        help = "No solution was found."
+      end
+      
+      if @deliberation
+        help << " (#{deliberation_report})"
+      end
+      
+      super help
+    end
+    
+    private
+    
+    # A report on the deliberation proceedings, for debugging purposes.
+    def deliberation_report
+      @deliberation.characteristics.keys.sort_by(&:to_s).map do |characteristic|
+        statement = "#{characteristic}: "
+        if report = @deliberation.reports.find { |r| r.committee.name == characteristic }
+          statement << report.quorum.name.humanize.downcase
+        else
+          statement << 'provided as input'
+        end
+      end.join ', '
+    end
+  end
+end

data/lib/leap/quorum.rb

@@ -1,8 +1,25 @@
 module Leap
+  # A basic building block of a Leap decision.
+  #
+  # A quorum encapsulates a specific methodology for drawing a conclusion based on a set of input information.
   class Quorum
-    include XmlSerializer
-
-    attr_reader :name, :requirements, :supplements, :process, :compliance
+    
+    # The name of the quorum
+    attr_reader :name
+    
+    # Quorum attribute requirements, as defined by the <tt>:needs</tt> option
+    attr_reader :requirements
+    
+    # Useful attributes, as defined by the <tt>:wants</tt> option
+    attr_reader :supplements
+    
+    # The quorum's methodology, as a Ruby closure.
+    attr_reader :process
+    
+    # Protocols with which this quorum complies.
+    attr_reader :compliance
+    
+    # (see Leap::Committee#quorum)
     def initialize(name, options, blk)
       @name = name
       @requirements = Array.wrap options[:needs]
@@ -11,41 +28,31 @@ module Leap
       @process = blk
     end
     
+    # Do the provided characteristics satisfy the quorum's requirements?
+    # @param [Hash] characteristics
+    # @return [TrueClass, NilClass]
     def satisfied_by?(characteristics)
       (requirements - characteristics.keys).empty?
     end
     
+    # Does the quorum comply with the given set of protocols?
+    # @param [Array] guideines The list of protocols we're for which we're checking compliance.
+    # @return [TrueClass, NilClass]
     def complies_with?(guidelines)
       (guidelines - compliance).empty?
     end
     
+    # Perform the quorum's methodology using the given characteristics.
+    # @param [Hash] characteristics
+    # @return The methodology's result
     def acknowledge(characteristics, considerations)
       considerations.unshift characteristics
       process.call(*considerations[0...process.arity])
     end
     
+    # All characteristics either needed or wanted by the quorum.
     def characteristics
       requirements + supplements
     end
-
-    def as_json(*)
-      { 
-        'name' => name.to_s,
-        'requirements' => requirements.map(&:to_s),
-        'appreciates' => supplements.map(&:to_s),
-        'complies' => compliance.map(&:to_s)
-      }
-    end
-
-    def to_xml(options = {})
-      super options do |xml|
-        xml.quorum do |quorum_block|
-          quorum_block.name name.to_s, :type => 'string'
-          array_to_xml(quorum_block, :requirements, requirements)
-          array_to_xml(quorum_block, :appreciates, supplements, 'supplement')
-          array_to_xml(quorum_block, :complies, compliance, 'compliance')
-        end
-      end
-    end
   end
 end

data/lib/leap/report.rb

@@ -1,41 +1,27 @@
 module Leap
+  # Encapsulates a committee's report; that is, the conclusion of its selected quorum, along with administrative details.
   class Report
-    include XmlSerializer
-
-    attr_reader :subject, :committee, :conclusion, :quorum
     
-    def initialize(subject, committee, report)
+    # The committee that produced the report
+    attr_reader :committee
+    
+    # The committee's conclusion
+    attr_reader :conclusion
+    
+    # The quorum whose methodology provided the conclusion.
+    attr_reader :quorum
+    
+    # Create a new report.
+    #
+    # This is generally called in the midst of <tt>Leap::Committee#report</tt>
+    # @param [Leap::Committee] The committee that produced the report.
+    # @param [Hash] report A single-pair hash containing the responsible quorum and its conclusion.
+    # @raise [ArgumentError] Raised for anonymous reports, or if the report is not made properly.
+    def initialize(committee, report)
       raise ArgumentError, 'Reports must identify themselves' unless committee.is_a?(::Leap::Committee)
-      @subject = subject
       @committee = committee
       raise ArgumentError, 'Please report with quorum => conclusion' unless report.is_a?(Hash) and report.length == 1
       @quorum, @conclusion = report.first
     end
-
-    def formatted_conclusion
-      return @formatted_conclusion unless @formatted_conclusion.nil?
-      if characteristic = subject.class.characteristics[committee.name]
-        @formatted_conclusion = characteristic.display committee.name => conclusion
-      end
-      @formatted_conclusion ||= conclusion
-    end
-
-    def as_json(*)
-      {
-        'committee' => committee.as_json,
-        'conclusion' => formatted_conclusion,
-        'quorum' => quorum.as_json
-      }
-    end
-
-    def to_xml(options = {})
-      super options do |xml|
-        xml.report do |report_block|
-          committee.to_xml(options.merge :skip_instruct => true, :builder => report_block)
-          report_block.conclusion formatted_conclusion, :type => formatted_conclusion.class.to_s.downcase
-          quorum.to_xml(options.merge :skip_instruct => true, :builder => report_block)
-        end
-      end
-    end
   end
 end

data/lib/leap/subject.rb

@@ -1,19 +1,66 @@
 module Leap
+  # In Leap lingo, Subject refers to the host class, instances of which we're trying to arrive at conclusions about.
+  # 
+  # It is within Subjects that we establish decision-making strategies using <tt>#decide</tt>
+  # @see #decide
   module Subject
+    # Establishes the <tt>@decisions</tt> class instance variable for accumulating Leap decisions, along with an accessor for their deliberations.
+    # Also injects <tt>Leap::ImplicitAttributes</tt>, which provides a low-budget attribute curation method.
+    # @see Leap::Decision
+    # @see Leap::Deliberation
+    # @see Leap::DeliberationsAccessor
+    # @see Leap::ImplicitAttributes
     def self.extended(base)
       base.instance_variable_set :@decisions, {}
-      base.send :attr_reader, :deliberations
       base.send :include, ::Leap::ImplicitAttributes
+      base.send :include, ::Leap::DeliberationsAccessor
+      base.send :include, ::Leap::GoalMethodsDocumentation
     end
+    
+    # Accumulates <tt>Leap::Decision</tt> objects, having been defined with <tt>#decide</tt>.
+    # @see #decide
     attr_reader :decisions
+    
+    # Defines a new <tt>Leap::Decision</tt> on the subject, using a DSL within its block.
+    #
+    # The DSL within the block is primarily composed of <tt>Leap::Decision#committee</tt>.
+    # Using <tt>#decide</tt> will define a new method on instances of the subject class, named after the decision's <tt>goal</tt>,
+    # that <i>computes</i> the decision through a process called deliberation (see <tt>Leap::GoalMethodsDocumentation</tt>).
+    #
+    # @example Defining a Leap decision
+    #   class Person
+    #     include Leap
+    #     decide :lucky_number do
+    #       # Decision definition elided (see Leap::Decision#committee)
+    #     end
+    #   end
+    #
+    #   Person.new.lucky_number # => 42
+    #
+    # @param [Symbol] goal The goal of the decision--what is it that we're trying to decide about the subject?
+    # @param [optional, Hash] options
+    # @option [optional, Symbol] with The name of an instance method on the subject that will, when called, provide a Hash of curated attributes about itself. <a href="http://github.com/brighterplanet/charisma">Charisma</a> is great for this. If this option is not provided, Leap will use a low-budget alternative (see <tt>Leap::ImplicitAttributes</tt>) 
+    #
+    # @see Leap::Decision
+    # @see Leap::Decision#committee
+    # @see Leap::Deliberation
+    # @see Leap::GoalMethodsDocumentation
+    # @see Leap::ImplicitAttributes
     def decide(goal, options = {}, &blk)
       decisions[goal] = ::Leap::Decision.new goal, options
       Blockenspiel.invoke(blk, decisions[goal])
       define_method goal do |*considerations|
         options = considerations.extract_options!
         @deliberations ||= {}
-        @deliberations[goal] = self.class.decisions[goal].make(self, *considerations.push(options))
-        @deliberations[goal][goal] or raise ::Leap::NoSolutionError
+        decision = self.class.decisions[goal]
+        characteristics = send(self.class.decisions[goal].signature_method)
+        considerations.push(options)
+        @deliberations[goal] = decision.make(characteristics, *considerations)
+        if @deliberations[goal][goal].nil? 
+          raise ::Leap::NoSolutionError, :goal => goal,
+            :deliberation => @deliberations[goal]
+        end
+        @deliberations[goal][goal]
       end
     end
   end

data/lib/leap/version.rb

@@ -1,3 +1,3 @@
-module Leap
-  VERSION = '0.4.6'
-end
+module Leap
+  VERSION = "0.5.0"
+end

data/test/helper.rb

@@ -3,7 +3,13 @@ require 'bundler'
 Bundler.setup
 require 'test/unit'
 require 'shoulda'
-require 'characterizable'
+require 'charisma'
+require 'active_support/version'
+%w{
+  active_support/core_ext/hash/except
+}.each do |active_support_3_requirement|
+  require active_support_3_requirement
+end if ActiveSupport::VERSION::MAJOR == 3
 
 $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 $LOAD_PATH.unshift(File.dirname(__FILE__))
@@ -25,7 +31,7 @@ class Person
     @magic_integer = options[:magic_integer] if options[:magic_integer] && options[:magic_integer].is_a?(Integer)
   end
   
-  include Characterizable
+  include Charisma
   
   characterize do
     has :name
@@ -61,7 +67,7 @@ class Person
     end
     
     committee :magic_float do
-      quorum 'ancient recipe', :needs => :name do |characteristics|
+      quorum 'ancient recipe', :needs => :name, :complies => :zeus do |characteristics|
         ('A'..'Z').to_a.index(characteristics[:name].chars.to_a.first).to_f / ('A'..'Z').to_a.index(characteristics[:name].chars.to_a.last).to_f 
       end
     end
@@ -102,3 +108,14 @@ class Thing
     committee(:anything) {}
   end
 end
+
+class Seamus
+  include Leap
+  decide :can_i_commit_to_that_date do
+    committee :can_i_commit_to_that_date do
+      quorum 'my first instinct', :complies => :bent do |characteristics|
+        :maybe
+      end
+    end
+  end
+end

data/test/test_leap.rb

@@ -11,7 +11,6 @@ class TestLeap < Test::Unit::TestCase
     end
     
     should 'naturally receive an International Psychics Association-compliant lucky number' do
-      @person.lucky_number
       assert_equal [:ipa], @person.deliberations[:lucky_number].compliance
     end
   end
@@ -26,22 +25,15 @@ class TestLeap < Test::Unit::TestCase
     end
     
     should 'nevertheless remember how his lucky number was determined' do
-      @person.lucky_number # make the decision
-      assert_equal({ :magic_integer => 6, :lucky_number => 36, :age => 5, :litmus => {}}, @person.deliberations[:lucky_number].characteristics)
+      assert_equal(@person.deliberations[:lucky_number].characteristics, { :magic_integer => 6, :lucky_number => 36, :age => 5, :litmus => {}})
       assert_equal 'ninja style', @person.deliberations[:lucky_number].reports.find{ |r| r.committee.name == :magic_integer }.quorum.name
     end
     
-    should 'but only as long as it had actually been determined' do
-      assert_nil @person.deliberations
-    end
-    
     should 'only give quorums what they ask for' do
-      @person.lucky_number # make the decision
       assert_equal({}, @person.deliberations[:lucky_number].reports.find{ |r| r.committee.name == :litmus }.conclusion)
     end
     
     should 'not receive an International Psychics Association-compliant lucky number unless he asks for it' do
-      @person.lucky_number
       assert_equal [], @person.deliberations[:lucky_number].compliance
     end
   end
@@ -90,15 +82,63 @@ class TestLeap < Test::Unit::TestCase
     end
   end
   
+  context "A lazy subject" do
+    setup do
+      @thing = Thing.new
+      @thing.anything rescue nil
+    end
+    
+    should 'have proper implicit characteristics' do
+      assert_equal Hash.new, @thing.deliberations[:anything].characteristics
+    end
+  end
+  
   context "An impossible decision" do
     setup do
       @thing = Thing.new
     end
     
     should 'be impossible to make' do
-      assert_raise ::Leap::NoSolutionError do
+      exception = assert_raise ::Leap::NoSolutionError do
         @thing.anything
       end
+      
+      assert_match(/No solution was found for "anything"/, exception.message)
+    end
+  end
+  
+  context "A difficult decision" do
+    setup do
+      @person = Person.new :name => 'Bozo'
+    end
+    
+    should 'provide details about its apparent impossibility' do
+      exception = assert_raise ::Leap::NoSolutionError do
+        @person.lucky_number :comply => :zeus
+      end
+      
+      assert_match(/No solution was found for "lucky_number"/, exception.message)
+      assert_match(/magic_float: ancient recipe, name: provided as input/, exception.message)
+    end
+  end
+  
+  context 'Seamus deciding about whether he can commit to a date' do
+    setup do
+      @seamus = Seamus.new
+    end
+    
+    should 'work for most people' do
+      assert_equal :maybe, @seamus.can_i_commit_to_that_date
+    end
+    
+    should 'work for BenT, who is easygoing' do
+      assert_equal :maybe, @seamus.can_i_commit_to_that_date(:comply => :bent)
+    end
+    
+    should 'never work for andy' do
+      assert_raise ::Leap::NoSolutionError do
+        @seamus.can_i_commit_to_that_date(:comply => :andy)
+      end
     end
   end
 end