leap 0.5.5 → 0.5.6

data/README.markdown

@@ -256,6 +256,34 @@ and then perform your decision with a protocol constraint:
 
 You can name your protocols how ever you want; they just have to match between the quorum assertions and the decision option.
 
+## Logging
+
+You can follow along with Leap's computation process by enabling detailed logging with
+
+``` ruby
+Leap.log!
+```
+
+By default, after being enabled, Leap will log to `Logger.new($stdout)`, per Ruby convention. If you have custom logging needs, use
+
+``` ruby
+Leap.log!(my_logging_object)
+```
+
+Make sure your logging object (`my_logging_object` in this example) provides a `#info` method.
+
+## Instrumentation
+
+You can time Leap activity by enabling instrumentation:
+
+``` ruby
+Leap.instrument!
+```
+
+Leap uses `Benchmark.measure` internally and displays timings in standard `Benchmark::Tms` format.
+
+Enabling instrumentation automatically enables logging.
+
 ## Internals
 
 Normally you'll construct your decision strategies using `decide :foo . . . end` blocks and perform them using the resulting `#foo` methods, but sometimes you'll want access to Leap's internals.

data/lib/leap/committee.rb

@@ -46,12 +46,17 @@ module Leap
     # @see Leap::GoalMethodsDocumentation
     # @return Leap::Report
     def report(characteristics, considerations, options = {})
-      quorums.grab do |quorum|
+      Leap.log.committee "Convening committee", name
+      quorums.each do |quorum|
+        Leap.log.quorum "Assessing quorum", quorum.name
         next unless quorum.satisfied_by? characteristics and quorum.complies_with? Array.wrap(options[:comply])
+        Leap.log.quorum "Acknowledging quorum", quorum.name
         if conclusion = quorum.acknowledge(characteristics.slice(*quorum.characteristics), considerations.dup)
-          ::Leap::Report.new self, quorum => conclusion
+          Leap.log.quorum "Success", quorum.name 
+          return ::Leap::Report.new(self, quorum, conclusion)
         end
       end
+      nil
     end
     
     include ::Blockenspiel::DSL

data/lib/leap/decision.rb

@@ -33,11 +33,17 @@ module Leap
     # 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)
+      Leap.log.decision "Leaping to conclusion", goal
+      Leap.log.decision "Initial characteristics: #{characteristics.inspect}", goal
       options = considerations.extract_options!
       committees.reject { |c| characteristics.keys.include? c.name }.reverse.inject(Deliberation.new(characteristics)) do |deliberation, committee|
-        if report = committee.report(deliberation.characteristics, considerations, options)
-          deliberation.reports.unshift report
-          deliberation.characteristics[committee.name] = report.conclusion
+        Leap.instrument.committee committee.name do
+          if report = committee.report(deliberation.characteristics, considerations, options)
+            Leap.log.committee "Success", committee.name
+            deliberation.reports.unshift report
+            deliberation.characteristics[committee.name] = report.conclusion
+          end
+          Leap.log.decision "Updated characteristics: #{deliberation.characteristics.inspect}", goal
         end
         deliberation
       end

data/lib/leap/quorum.rb

@@ -46,8 +46,10 @@ module Leap
     # @param [Hash] characteristics
     # @return The methodology's result
     def acknowledge(characteristics, considerations)
-      considerations.unshift characteristics
-      process.call(*considerations[0...process.arity])
+      Leap.instrument.quorum name do
+        considerations.unshift characteristics
+        process.call(*considerations[0...process.arity])
+      end
     end
     
     # All characteristics either needed or wanted by the quorum.

data/lib/leap/register.rb

@@ -0,0 +1,68 @@
+module Leap
+  require 'logger'
+
+  # Begin logging Leap activity
+  #
+  # @param [optional] logger An object to receive logging signals (currently <tt>#info</tt>). If not provided, Leap will log to <tt>Logger.new($stdout)</tt>. 
+  def log!(logger = nil)
+    @@logger = Register.new logger
+  end
+  module_function :log!
+
+  # Returns the logger object if logging is enabled
+  def log?
+    defined?(@@logger)
+  end
+  module_function :log?
+
+  # Returns the logging object--or a "black hole" logger if logging is not enabled.
+  def log
+   log? ? @@logger : @@shredder ||= Shredder.new 
+  end
+  module_function :log
+
+  # Facilitates the logging of Leap activity
+  class Register
+    # Creates a <tt>Leap::Register</tt> wrapper around a given (optional) logger. If no logger is provided, Leap assumes <tt>Logger.new($stdout)</tt>.
+    def initialize(logger = nil)
+      @logger = logger || ::Logger.new($stdout)
+    end
+
+    # Log a Leap decision
+    #
+    # @param [String] message The message to be logged
+    # @param [String] name The name of the decision
+    def decision(message, name)
+      record name, message, 0
+    end
+
+    # Log Leap committee action
+    #
+    # @param [String] message The message to be logged
+    # @param [String] name The name of the committee
+    def committee(message, name)
+      record name, message, 1
+    end
+
+    # Log Leap quorum activity
+    #
+    # @param [String] message The message to be logged
+    # @param [String] name The name of the quorum
+    def quorum(message, name)
+      record name, message, 2
+    end
+
+    private
+    
+    def record(name, message, indents)
+      @logger.info 'Leap ' + (' ' * indents * 2) + " [#{name}] #{message}"  
+    end
+  end
+
+  # A "black hole" logging class that does absolutely nothing with the logging messages it receives.
+  class Shredder
+    def decision(*) nil end
+    def committee(*) nil end
+    def quorum(*) nil end
+  end
+end

data/lib/leap/report.rb

@@ -15,13 +15,15 @@ module Leap
     #
     # This is generally called in the midst of <tt>Leap::Committee#report</tt>
     # @param [Leap::Committee] The committee that produced the report.
+    # @param [Leap::Quorum] The responsible quorum.
+    # @param [any] The conclusion.
     # @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] Raised for anonymous reports.
+    def initialize(committee, quorum, conclusion)
       raise ArgumentError, 'Reports must identify themselves' unless committee.is_a?(::Leap::Committee)
       @committee = committee
-      raise ArgumentError, 'Please report with quorum => conclusion' unless report.is_a?(Hash) and report.length == 1
-      @quorum, @conclusion = report.first
+      @quorum = quorum
+      @conclusion = conclusion
     end
   end
 end

data/lib/leap/subject.rb

@@ -50,16 +50,20 @@ module Leap
       decisions[goal] = ::Leap::Decision.new goal, options
       Blockenspiel.invoke(blk, decisions[goal])
       define_method goal do |*considerations|
-        @deliberations ||= {}
-        decision = self.class.decisions[goal]
-        characteristics = send(self.class.decisions[goal].signature_method)
-        @deliberations[goal] = decision.make(characteristics, *considerations)
-        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]
+        Leap.instrument.decision goal do
+          @deliberations ||= {}
+          decision = self.class.decisions[goal]
+          characteristics = send(decision.signature_method)
+          @deliberations[goal] = decision.make(characteristics, *considerations)
+          if decision.mastered? and @deliberations[goal][goal].nil? 
+            raise ::Leap::NoSolutionError, :goal => goal, :deliberation => @deliberations[goal]
+          elsif decision.mastered?
+            Leap.log.decision "Success", goal
+            @deliberations[goal][goal]
+          else
+            Leap.log.decision "Success", goal
+            @deliberations[goal]
+          end
         end
       end
     end

data/lib/leap/version.rb

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

data/lib/leap/whip.rb

@@ -0,0 +1,62 @@
+module Leap
+  require 'benchmark'
+  
+  # Begin instrumenting Leap activity. Automatically enables logging.
+  def instrument!
+    Leap.log! unless Leap.log?
+    @@whip = Whip.new
+  end
+  module_function :instrument!
+
+  # Returns the instrumentation object if enabled
+  def instrument?
+    defined?(@@whip)
+  end
+  module_function :instrument?
+
+  # Returns the instrumentation object--or a "pass-through" substitute if not enabled
+  def instrument(&blk)
+    instrument? ? @@whip : @@bystander ||= Bystander.new
+  end
+  module_function :instrument
+
+  # Facilitates the instrumentation of Leap activity
+  class Whip
+    # Instrument a Leap decision
+    #
+    # @param [String, Symbol] name The decision's name
+    # @param [Proc] blk A proc wrapping the decision to instrument
+    def decision(name, &blk)
+      Leap.log.decision instrument(&blk), name
+    end
+
+    # Instrument Leap committee activity
+    #
+    # @param [String, Symbol] name The committee's name
+    # @param [Proc] blk A proc wrapping the committee convention to instrument
+    def committee(name, &blk)
+      Leap.log.committee instrument(&blk), name
+    end
+
+    # Instrument Leap quorum activity
+    #
+    # @param [String, Symbol] name The quorum's name
+    # @param [Proc] blk A proc wrapping the quorum activity to instrument
+    def quorum(name, &blk)
+      Leap.log.quorum instrument(&blk), name
+    end
+    
+    private
+    
+    def instrument(&blk)
+      'Completed in ' + Benchmark.measure(&blk).format('%10.6r').gsub(/[()]/,'').strip + 's'
+    end
+  end
+
+  # Allows Leap activity to continue uninstrumented
+  class Bystander
+    def decision(_, &blk) yield end
+    def committee(_, &blk) yield end
+    def quorum(_, &blk) yield end
+  end
+end

data/lib/leap.rb

@@ -8,7 +8,6 @@ require 'active_support/version'
 end if ActiveSupport::VERSION::MAJOR == 3
 require 'blockenspiel'
 
-require 'leap/core_ext'
 require 'leap/subject'
 require 'leap/committee'
 require 'leap/quorum'
@@ -19,6 +18,8 @@ require 'leap/implicit_attributes'
 require 'leap/no_solution_error'
 require 'leap/deliberations_accessor'
 require 'leap/goal_methods_documentation'
+require 'leap/register'
+require 'leap/whip'
 
 # Leap is a system for: 1) describing decision-making strategies used to determine a potentially non-obvious attribute of an object and 2)
 # computing that attribute by choosing appropriate strategies given a specific set of input information

metadata

@@ -1,137 +1,101 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: leap
-version: !ruby/object:Gem::Version 
-  hash: 1
+version: !ruby/object:Gem::Version
+  version: 0.5.6
   prerelease: 
-  segments: 
-  - 0
-  - 5
-  - 5
-  version: 0.5.5
 platform: ruby
-authors: 
+authors:
 - Andy Rossmeissl
 - Seamus Abshere
 - Derek Kastner
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-08-17 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2011-12-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: charisma
-  version_requirements: &id001 !ruby/object:Gem::Requirement 
+  requirement: &10759248 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 23
-        segments: 
-        - 0
-        - 2
-        - 0
+      - !ruby/object:Gem::Version
         version: 0.2.0
-  prerelease: false
   type: :development
-  requirement: *id001
-- !ruby/object:Gem::Dependency 
+  prerelease: false
+  version_requirements: *10759248
+- !ruby/object:Gem::Dependency
   name: shoulda
-  version_requirements: &id002 !ruby/object:Gem::Requirement 
+  requirement: &10758996 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
-  prerelease: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  requirement: *id002
-- !ruby/object:Gem::Dependency 
+  prerelease: false
+  version_requirements: *10758996
+- !ruby/object:Gem::Dependency
   name: bueller
-  version_requirements: &id003 !ruby/object:Gem::Requirement 
+  requirement: &10758720 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
-  prerelease: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  requirement: *id003
-- !ruby/object:Gem::Dependency 
+  prerelease: false
+  version_requirements: *10758720
+- !ruby/object:Gem::Dependency
   name: blockenspiel
-  version_requirements: &id004 !ruby/object:Gem::Requirement 
+  requirement: &10758420 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 23
-        segments: 
-        - 0
-        - 3
-        - 2
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
         version: 0.3.2
-  prerelease: false
   type: :runtime
-  requirement: *id004
-- !ruby/object:Gem::Dependency 
+  prerelease: false
+  version_requirements: *10758420
+- !ruby/object:Gem::Dependency
   name: activesupport
-  version_requirements: &id005 !ruby/object:Gem::Requirement 
+  requirement: &10758120 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 11
-        segments: 
-        - 2
-        - 3
-        - 4
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
         version: 2.3.4
-  prerelease: false
   type: :runtime
-  requirement: *id005
-- !ruby/object:Gem::Dependency 
+  prerelease: false
+  version_requirements: *10758120
+- !ruby/object:Gem::Dependency
   name: i18n
-  version_requirements: &id006 !ruby/object:Gem::Requirement 
+  requirement: &10757892 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
-  prerelease: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  requirement: *id006
-- !ruby/object:Gem::Dependency 
+  prerelease: false
+  version_requirements: *10757892
+- !ruby/object:Gem::Dependency
   name: builder
-  version_requirements: &id007 !ruby/object:Gem::Requirement 
+  requirement: &10757616 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
-  prerelease: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  requirement: *id007
+  prerelease: false
+  version_requirements: *10757616
 description: Leap to conclusions
 email: andy@rossmeissl.net
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .document
 - .gitignore
 - Gemfile
@@ -140,7 +104,6 @@ files:
 - leap.gemspec
 - lib/leap.rb
 - lib/leap/committee.rb
-- lib/leap/core_ext.rb
 - lib/leap/decision.rb
 - lib/leap/deliberation.rb
 - lib/leap/deliberations_accessor.rb
@@ -148,43 +111,41 @@ files:
 - lib/leap/implicit_attributes.rb
 - lib/leap/no_solution_error.rb
 - lib/leap/quorum.rb
+- lib/leap/register.rb
 - lib/leap/report.rb
 - lib/leap/subject.rb
 - lib/leap/version.rb
+- lib/leap/whip.rb
 - test/helper.rb
 - test/test_leap.rb
 homepage: http://github.com/rossmeissl/leap
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+      hash: 744383405
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
+      hash: 744383405
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.8.8
+rubygems_version: 1.8.11
 signing_key: 
 specification_version: 3
 summary: A heuristics engine for your Ruby objects
 test_files: []
-

data/lib/leap/core_ext.rb

@@ -1,11 +0,0 @@
-class Array
-  # Like <tt>Array#detect</tt>, but returns the calculated value
-  def grab(&blk)
-    result = each do |element|
-      value = yield element
-      break value if value
-    end
-    return if result == self
-    result
-  end
-end