leap 0.5.4 → 0.5.5

data/README.markdown

@@ -89,12 +89,20 @@ class Person
   end
 end
 ```
+
+``` irb
+> Person.new(:watch => Watch.new).time
+ => 3:02pm
+```
+
 The `decide :time do . . . end` block is called the *decision*. In this case, we're describing how to decide *time* for a given Person; we say that time is the *goal* of the decision. Leap will define a method on the object named after the decision (in this case, `Person#time`). Calling this method computes the decision.
 
-The `committee :time do . . . end` block is called a *committee*. Committees represent a set of methodologies, all of which are appropriate means of determining its namesake property, in this case *time*. All decision blocks must at the very least provide a committee for the goal; this is implicitly the *master committee*. Typically Leap decisions will involve many more committees, each of which is tasked with determining some intermediate result necessary for the master committee to arrive at a conclusion.
+The `committee :time do . . . end` block is called a *committee*. Committees represent a set of methodologies, all of which are appropriate means of determining its namesake property, in this case *time*. Most decision blocks provide a committee named the same as the goal; this is implicitly the *master committee*. Typically Leap decisions will involve many more committees, each of which is tasked with determining some intermediate result necessary for the master committee to arrive at a conclusion.
 
 The `quorum 'look at your watch' . . . end` block is called a *quorum*. Quorums describe *one particular way* of reaching the committee's conclusion, along with a list (`:needs`) of what they need to be employed. The `characteristics` blockvar is a curated subset of the object's attributes presented to the quorum (which is in this sense a *closure*) for consideration.
 
+The `Person#time` method, which is created dynamically by Leap, is called the *goal method*---it actually performs the decision on the object.
+
 Back to the example. Having a watch does indeed make telling time easy. Complexities arise when you don't; you have to fallback to more intuitive methods.
 
 For example, we can look at the angle of the sun. (I'm going to start abbreviating the code blocks at this point.)
@@ -133,7 +141,17 @@ end
 
 Surely there is more than one way of determining the Person's current address, so, as you can see, a dozen or more committees, each with several quorums, would be necessary to completely describe the intuitive process that we humans use to figure out something as simple as the likely time of day. This is a useful way to think about Leap: it's a non-learning artifical intelligence system that attempts to model human intuition by describing heuristic strategies.
 
-Now that we've looked at an overview of the Leap system, let's look at each component in depth, from the inside (characteristics) out (decisions).
+Now that we've looked at an overview of the Leap system, let's look at each component in depth, starting with the goal method and proceeding from the inside (characteristics) out (decisions).
+
+## Goal method
+
+Since Leap helps determine non-obvious attributes of objects, its decisions are made using methods that look and behave like attribute accessors:
+
+``` ruby
+@person.time # Makes the "time" decision (as defined on Person) using @person's characteristics
+```
+
+If there is a master commitee, the goal method returns its report; if not, it returns a hash of all the committees' reports.
 
 ## Characteristics
 

data/Rakefile

@@ -25,16 +25,3 @@ Rake::TestTask.new(:test) do |test|
   test.verbose = true
 end
 task :default => :test
-
-begin
-  require 'rake/rdoctask'
-  Rake::RDocTask.new do |rdoc|
-    rdoc.rdoc_dir = 'rdoc'
-    rdoc.title = 'leap'
-    rdoc.options << '--line-numbers' << '--inline-source'
-    rdoc.rdoc_files.include('README*')
-    rdoc.rdoc_files.include('lib/**/*.rb')
-  end
-rescue LoadError
-   puts "Rdoc is not available"
-end

data/leap.gemspec

@@ -1,28 +1,28 @@
-# -*- encoding: utf-8 -*-
-$:.push File.expand_path("../lib", __FILE__)
-require "leap/version"
-
-Gem::Specification.new do |s|
-  s.name        = "leap"
-  s.version     = Leap::VERSION
-  s.platform    = Gem::Platform::RUBY
-  s.authors     = ["Andy Rossmeissl", "Seamus Abshere", "Derek Kastner"]
-  s.email       = "andy@rossmeissl.net"
-  s.homepage    = "http://github.com/rossmeissl/leap"
-  s.summary     = %Q{A heuristics engine for your Ruby objects}
-  s.description = %Q{Leap to conclusions}
-
-  s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
-  s.require_paths = ["lib"]
-  
-  s.add_development_dependency "charisma", '~>0.2.0'
-  s.add_development_dependency "shoulda"
-  s.add_development_dependency 'bueller'
-  s.add_dependency 'blockenspiel', '>=0.3.2'
-  s.add_dependency 'activesupport', '>=2.3.4'
-  # sabshere 1/27/11 for activesupport - http://groups.google.com/group/ruby-bundler/browse_thread/thread/b4a2fc61ac0b5438
-  s.add_dependency 'i18n'
-  s.add_dependency 'builder'
-end
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "leap/version"
+
+Gem::Specification.new do |s|
+  s.name        = "leap"
+  s.version     = Leap::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Andy Rossmeissl", "Seamus Abshere", "Derek Kastner"]
+  s.email       = "andy@rossmeissl.net"
+  s.homepage    = "http://github.com/rossmeissl/leap"
+  s.summary     = %Q{A heuristics engine for your Ruby objects}
+  s.description = %Q{Leap to conclusions}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+  
+  s.add_development_dependency "charisma", '~>0.2.0'
+  s.add_development_dependency "shoulda"
+  s.add_development_dependency 'bueller'
+  s.add_dependency 'blockenspiel', '>=0.3.2'
+  s.add_dependency 'activesupport', '>=2.3.4'
+  # sabshere 1/27/11 for activesupport - http://groups.google.com/group/ruby-bundler/browse_thread/thread/b4a2fc61ac0b5438
+  s.add_dependency 'i18n'
+  s.add_dependency 'builder'
+end

data/lib/leap/decision.rb

@@ -23,6 +23,11 @@ module Leap
       @committees = []
     end
     
+    # Answers whether or not the decision has a "master committee"--a committee with the same name as the decision's goal.
+    def mastered?
+      !!committees.find { |committee| committee.name == goal }
+    end
+    
     # 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.

data/lib/leap/goal_methods_documentation.rb

@@ -11,7 +11,7 @@ module Leap
     #   @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.
+    #   @return The value of the newly-decided goal--or, if there is no committee with the same name as the goal, a hash of committee reports
     #   @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

data/lib/leap/subject.rb

@@ -54,10 +54,13 @@ module Leap
         decision = self.class.decisions[goal]
         characteristics = send(self.class.decisions[goal].signature_method)
         @deliberations[goal] = decision.make(characteristics, *considerations)
-        if @deliberations[goal][goal].nil? 
+        if self.class.decisions[goal].mastered? and @deliberations[goal][goal].nil? 
           raise ::Leap::NoSolutionError, :goal => goal, :deliberation => @deliberations[goal]
+        elsif self.class.decisions[goal].mastered?
+          @deliberations[goal][goal]
+        else
+          @deliberations[goal]
         end
-        @deliberations[goal][goal]
       end
     end
   end

data/lib/leap/version.rb

@@ -1,3 +1,3 @@
-module Leap
-  VERSION = "0.5.4"
-end
+module Leap
+  VERSION = "0.5.5"
+end

data/test/helper.rb

@@ -119,3 +119,15 @@ class Seamus
     end
   end
 end
+
+class Idea
+  include Leap
+  decide :value do
+    committee :cost do
+      quorum('default') {0}
+    end
+    committee :benefit do
+      quorum('default') {1}
+    end
+  end
+end

data/test/test_leap.rb

@@ -157,4 +157,19 @@ class TestLeap < Test::Unit::TestCase
       assert_equal :length, Owl.decisions[:eye_size].committees.first.options[:measures]
     end
   end
+  
+  context 'A decision without a master committee' do
+    setup do
+      @idea = Idea.new
+    end
+    
+    should 'still compute' do
+      @idea.value
+      assert_equal({:cost => 0, :benefit => 1}, @idea.deliberations[:value].characteristics)
+    end
+    
+    should 'provide easy access to committee reports' do
+      assert_equal 0, @idea.value[:cost]
+    end
+  end
 end

metadata

@@ -1,8 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: leap
 version: !ruby/object:Gem::Version 
+  hash: 1
   prerelease: 
-  version: 0.5.4
+  segments: 
+  - 0
+  - 5
+  - 5
+  version: 0.5.5
 platform: ruby
 authors: 
 - Andy Rossmeissl
@@ -12,86 +17,112 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-06-02 00:00:00 -05:00
-default_executable: 
+date: 2011-08-17 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: charisma
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  version_requirements: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 0
+        - 2
+        - 0
         version: 0.2.0
-  type: :development
   prerelease: false
-  version_requirements: *id001
+  type: :development
+  requirement: *id001
 - !ruby/object:Gem::Dependency 
   name: shoulda
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
         version: "0"
-  type: :development
   prerelease: false
-  version_requirements: *id002
+  type: :development
+  requirement: *id002
 - !ruby/object:Gem::Dependency 
   name: bueller
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
         version: "0"
-  type: :development
   prerelease: false
-  version_requirements: *id003
+  type: :development
+  requirement: *id003
 - !ruby/object:Gem::Dependency 
   name: blockenspiel
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  version_requirements: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 0
+        - 3
+        - 2
         version: 0.3.2
-  type: :runtime
   prerelease: false
-  version_requirements: *id004
+  type: :runtime
+  requirement: *id004
 - !ruby/object:Gem::Dependency 
   name: activesupport
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  version_requirements: &id005 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 11
+        segments: 
+        - 2
+        - 3
+        - 4
         version: 2.3.4
-  type: :runtime
   prerelease: false
-  version_requirements: *id005
+  type: :runtime
+  requirement: *id005
 - !ruby/object:Gem::Dependency 
   name: i18n
-  requirement: &id006 !ruby/object:Gem::Requirement 
+  version_requirements: &id006 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
         version: "0"
-  type: :runtime
   prerelease: false
-  version_requirements: *id006
+  type: :runtime
+  requirement: *id006
 - !ruby/object:Gem::Dependency 
   name: builder
-  requirement: &id007 !ruby/object:Gem::Requirement 
+  version_requirements: &id007 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
         version: "0"
-  type: :runtime
   prerelease: false
-  version_requirements: *id007
+  type: :runtime
+  requirement: *id007
 description: Leap to conclusions
 email: andy@rossmeissl.net
 executables: []
@@ -104,7 +135,6 @@ files:
 - .document
 - .gitignore
 - Gemfile
-- LICENSE
 - README.markdown
 - Rakefile
 - leap.gemspec
@@ -123,7 +153,6 @@ files:
 - lib/leap/version.rb
 - test/helper.rb
 - test/test_leap.rb
-has_rdoc: true
 homepage: http://github.com/rossmeissl/leap
 licenses: []
 
@@ -137,7 +166,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: -1210512428885299124
+      hash: 3
       segments: 
       - 0
       version: "0"
@@ -146,17 +175,16 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: -1210512428885299124
+      hash: 3
       segments: 
       - 0
       version: "0"
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.6.2
+rubygems_version: 1.8.8
 signing_key: 
 specification_version: 3
 summary: A heuristics engine for your Ruby objects
-test_files: 
-- test/helper.rb
-- test/test_leap.rb
+test_files: []
+

data/LICENSE

@@ -1,20 +0,0 @@
-Copyright (c) 2009 Andy Rossmeissl
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.