factree 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5c35f29630bd9cb9399531725ed218c5da73e1c2
-  data.tar.gz: '09686d69ee9aeb3ea37f75d13af3c2f686dfa11e'
+  metadata.gz: c1acd242c9352248bdd755e245c55e026d16cdc0
+  data.tar.gz: b888a69e8cd08b85e1d3177e2b38b5c3f8cda78c
 SHA512:
-  metadata.gz: faf9cbfe994babe6b72d2038a8cab88f4123db61d505afdb26e0f07b57175456b49293558836ad48cd9809da8f93d78a195608910efa4eab5e71b5513c0b1bac
-  data.tar.gz: 2a279be3fa08b4fb588195eb6d6fd948ca759f19d8d622701478cf0694b328e6e299380aede9998c33523030720d2bac87f1974511ef6d2d93bc7c25f6ed7f80
+  metadata.gz: cf47060ea361430911941b26da4cef20bb527847c9f0efd522f3bac3b32d7fe94dc56d750dc91f1947598d6e6aa07bcb8573d6a462a350af2c9c17f42782795a
+  data.tar.gz: 42455c60d1d5b9ddb10a0d50cd6a7c2d4847e855453a60c9f1058bce56327dc1469684e5358c243d36db5513779ef33d4a0476ab852cec54c021038f8a4d96f2

data/.ruby-version

@@ -1 +1 @@
-2.4.0
+2.1.5

data/.travis.yml

@@ -1,5 +1,6 @@
 sudo: false
 language: ruby
 rvm:
-  - 2.4.0
+  - 2.1.5
+  - 2.4.1
 before_install: gem install bundler -v 1.14.6

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Grand Rounds
+
+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.

data/README.md

@@ -1,7 +1,8 @@
 # Factree
+[![Gem Version](https://badge.fury.io/rb/factree.svg)](https://rubygems.org/gems/factree)
 [![Build Status](https://travis-ci.org/jstrater/factree.svg?branch=master)](https://travis-ci.org/jstrater/factree)
 
-Factree provides a way to make choices based on a set of facts that are not yet known. It breaks the process down into individual decisions, each of which can lead to a number of other decisions, until finally a conclusion is reached -- something like a choose your own adventure novel. As each decision is made, the facts necessary to make the next decision are identified.
+Factree provides tools for making choices based on a set of facts that are not yet known. You write a decision function that takes a set facts and returns a conclusion. Factree will run your function and make sure it has all of the facts it needs to complete. If it doesn't, then Factree will tell you what's needed to continue.
 
 ## Installation
 
@@ -33,3 +34,6 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/jstrater/factree.
 
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/factree.gemspec

@@ -11,6 +11,7 @@ Gem::Specification.new do |spec|
 
   spec.summary       = %q{Decision trees that request facts as needed}
   spec.homepage      = "https://github.com/jstrater/factree"
+  spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})

data/lib/factree/aggregate.rb

@@ -1,28 +1,12 @@
-require 'factree/decision'
-
+# @api private
 module Factree::Aggregate
-  # Returns a new decision tree. The root of the tree calls the first Decision's decide function. If that returns nil, the next alternative is tried, and the next, and so on, until a valid Conclusion is returned.
-  #
-  # @param [Array<Decision>] decisions A decision followed by alternative decisions.
-  # @return [Decision] A decision tree that checks the alternatives in order to reach a conclusion.
-  def self.alternatives(*decisions)
-    if decisions.empty?
-      # Base case: no more decisions
-      return Factree::Decision.new{ nil }
-    else
-      # Recursive case
-      first, *rest = decisions
-      remaining_alternatives = alternatives(*rest)
-
-      return Factree::Decision.new first.required_facts do |facts|
-        first_result = first.decide(facts)
-
-        if first_result.nil?
-          remaining_alternatives
-        else
-          first_result
-        end
-      end
+  # @see DSL.decide_between_alternatives
+  def self.alternatives(facts, *decide_procs)
+    conclusion = nil
+    decide_procs.each do |decide|
+      conclusion = decide.call(facts)
+      break unless conclusion.nil?
     end
+    conclusion
   end
 end

data/lib/factree/conclusion.rb

@@ -1,6 +1,4 @@
-require 'factree/node'
-
-class Factree::Conclusion < Factree::Node
+class Factree::Conclusion
   attr_reader :value
 
   def initialize(value)
@@ -8,16 +6,8 @@ class Factree::Conclusion < Factree::Node
     freeze
   end
 
-  def conclusion?
-    true
-  end
-
-  def to_s
-    "<Factree::Conclusion value=#{@value.inspect}>"
-  end
-
   def ==(other)
-    other.is_a?(self.class) &&
+    self.class == other.class &&
       @value == other.instance_variable_get(:@value)
   end
 end

data/lib/factree/dsl.rb

@@ -1,24 +1,44 @@
-require 'factree/decision'
 require 'factree/conclusion'
-require 'factree/path'
+require 'factree/pathfinder'
 require 'factree/aggregate'
 
-# Readable shortcuts to common functions
+# Readable shortcuts to common functions.
 module Factree::DSL
-  def decision(requires: [], &decide)
-    required_facts = [requires].flatten
-    Factree::Decision.new(required_facts, &decide)
-  end
-
-  def conclusion(value)
+  # Creates a {Conclusion} to return from a decision proc.
+  #
+  # The conclusion has an associated value (can be anything.)
+  #
+  # @param [Object] value Any value, including nil
+  # @return [Conclusion]
+  def conclusion(value=nil)
     Factree::Conclusion.new(value)
   end
 
-  def path(through:, given: {})
-    Factree::Path.through_tree(through, given)
+  # Navigates as far as possible through a decision tree with the given set of facts.
+  #
+  # The path will stop when either
+  # - a conclusion is returned, or
+  # - there aren't enough facts to make the decision.
+  #
+  # == Errors
+  #
+  # If a decision function fails to return a {Conclusion}, an {InvalidConclusionError} will be raised.
+  #
+  # @param [Hash] facts The set of facts used to make decisions
+  # @param [Proc] decide The decision proc. Takes a set of {Facts} and returns a {Conclusion}.
+  # @return [Path] Information about the path followed through the tree
+  def find_path(**facts, &decide)
+    Factree::Pathfinder.find(facts, &decide)
   end
 
-  def decision_with_alternatives(*decisions)
-    Factree::Aggregate.alternatives(*decisions)
+  # A tool for composing lists of decision procs to be tried one after another until a conclusion is reached. When a proc returns nil instead of a {Conclusion}, the next proc in decide_procs is used instead.
+  #
+  # If the last decision proc is reached and it returns nil, then this method returns nil.
+  #
+  # @param [Facts] facts The facts to pass through to the decision procs.
+  # @param [Array<#call>] decide_procs A decision proc followed by alternative procs.
+  # @return [Decision] A decision tree that checks the alternatives in order to reach a conclusion.
+  def decide_between_alternatives(facts, *decide_procs)
+    Factree::Aggregate.alternatives(facts, *decide_procs)
   end
 end

data/lib/factree/facts.rb

@@ -0,0 +1,66 @@
+require 'forwardable'
+
+class Factree::Facts
+  extend Forwardable
+  def_delegators :@hash,
+    :[],
+    :to_h,
+    :keys
+
+  def self.coerce(source)
+    return source if source.is_a? self
+    new(**source)
+  end
+
+  def initialize(**hash)
+    @hash = hash.freeze
+    freeze
+  end
+
+  # Checks to see if a fact is present.
+  #
+  # @param [Symbol] fact_name
+  # @return [Boolean]
+  def known?(fact_name)
+    @hash.has_key? fact_name
+  end
+
+  # Requires that certain facts are present in order to proceed with the decision. If any of the facts are missing, the path will stop here.
+  #
+  # @param [Array<Symbol>] fact_names Names of facts to require
+  # @return [void]
+  def require(*fact_names)
+    self.class.throw_missing_facts unless fact_names.all? { |name| known? name }
+  end
+
+  # Gets the value of a fact. This also {#require}s the fact.
+  #
+  # @param [Symbol] fact_name
+  # @return [Object]
+  def [](fact_name)
+    self.require(fact_name)
+    @hash[fact_name]
+  end
+
+  def ==(other)
+    self.to_h == other.to_h
+  end
+
+  # @api private
+  def self.throw_missing_facts
+    throw MISSING_FACTS
+  end
+
+  # @api private
+  def self.catch_missing_facts
+    catch(MISSING_FACTS) do
+      yield
+    end
+  end
+
+  # Kernel#catch uses object ID to match thrown values. This gives us a unique
+  # ID and a readable message in case it's thrown somewhere it's not expected.
+  #
+  # @api private
+  MISSING_FACTS = "Attempted to read missing facts from a Factree::Facts instance"
+end

data/lib/factree/facts_spy.rb

@@ -0,0 +1,22 @@
+require 'delegate'
+
+# {Facts} decorator to spy on calls to {Facts#require}
+# @api private
+class Factree::FactsSpy < SimpleDelegator
+  def initialize(facts, &before_require)
+    @facts = facts
+    @before_require = before_require
+    super(facts)
+    freeze
+  end
+
+  def require(*fact_names)
+    @before_require.call(*fact_names)
+    super
+  end
+
+  def [](fact_name)
+    @before_require.call(fact_name)
+    super
+  end
+end

data/lib/factree/path.rb

@@ -1,43 +1,42 @@
-require 'factree/pathfinder'
+module Factree
+  # Raised when attempting to get a conclusion from an incomplete path
+  NoConclusionError = Class.new(StandardError)
 
-# Paths follow a sequence of nodes from the root of a decision tree toward the leaves. Use {Path.through_tree} to find a path through a tree.
-#
-# A path may or may not actually reach a conclusion. If it does, it will be {complete?} and return the {conclusion} value. If it doesn't, then you can get the names of all of the facts needed to get past the next decision from {required_facts}.
-class Factree::Path
-  # Uses the given set of facts to find a path through the tree. The path will go as far as possible, and it will only stop when a conclusion is reached or when it doesn't have all the facts needed to make a decision.
-  # @param [Factree::Decision, Factree::Conclusion] root The root node of the tree
-  # @param [Hash] facts The set of facts used to make decisions
-  # @return [Factree::Path]
-  def self.through_tree(root, facts, finder: Factree::Pathfinder)
-    new(finder.find_node_sequence(root, facts))
-  end
-
-  # Want to create a path? Use {.through_tree} instead.
-  def initialize(node_sequence)
-    @nodes = node_sequence.to_a.freeze
-    freeze
-  end
+  # {Path}s record useful information about an attempt to reach a {Conclusion} for a decision proc.
+  #
+  # A path may or may not actually reach a conclusion. If it does, it will be {complete?} and return the {conclusion} value. If it doesn't, then you can get the names of all of the facts needed to get past the next decision step from {required_facts}.
+  class Path
+    # Want to create a path? Use {DSL.find_path} instead.
+    #
+    # @api private
+    def initialize(required_facts=[], conclusion=nil)
+      @required_facts = required_facts.to_a.uniq
+      @conclusion = conclusion
+      freeze
+    end
 
-  # A path is {complete?} if it has reached a conclusion.
-  def complete?
-    @nodes.last.conclusion?
-  end
+    # A path is {complete?} if it has reached a conclusion.
+    def complete?
+      !@conclusion.nil?
+    end
 
-  # Returns the conclusion value if this path is complete.
-  def conclusion
-    raise "Attempted to get conclusion from incomplete path" unless complete?
+    # Returns the conclusion value if this path is complete.
+    def conclusion
+      # We don't want to return nil to indicate a missing conclusion, since that could confused for a nil conclusion with a nil value.
+      raise Factree::NoConclusionError, "Attempted to get conclusion from incomplete path" unless complete?
 
-    @nodes.last.value
-  end
+      @conclusion.value
+    end
 
-  # A list of the facts required to make all of the decisions along the path, including the last one. If the path is not complete, then the facts in this list are sufficient to progress to the next node.
-  # @return [Symbol] A list of fact names in the order they're required in the tree
-  def required_facts
-    [].concat(*@nodes.map(&:required_facts)).uniq
-  end
+    # A list of the facts that were required to get this far, plus any facts needed to make further progress. If the path is not complete, then the facts in this list are sufficient to progress past this point.
+    #
+    # @return [Array<Symbol>] A list of fact names in the order they're required in the tree
+    attr_reader :required_facts
 
-  def ==(other)
-    other.is_a?(self.class) &&
-      @nodes == other.instance_variable_get(:@nodes)
+    def ==(other)
+      self.class == other.class &&
+        @required_facts == other.instance_variable_get(:@required_facts) &&
+        @conclusion == other.instance_variable_get(:@conclusion)
+    end
   end
 end

data/lib/factree/pathfinder.rb

@@ -1,35 +1,35 @@
+require 'factree/path'
+require 'factree/facts'
+require 'factree/facts_spy'
+
 module Factree
-  CycleError = Class.new(StandardError)
-  InvalidDecisionError = Class.new(StandardError)
+  # Raised when a decision proc fails to return a Conclusion as expected
+  InvalidConclusionError = Class.new(StandardError)
 
   # @api private
   module Pathfinder
-    # Returns the sequence of nodes for the furthest path possible from the given node with the given set of facts.
-    def self.find_node_sequence(node, facts, visited=Set.new)
-      # No cycles allowed
-      if visited.include? node
-        raise Factree::CycleError,
-          "Cycle detected in decision tree. Node appeared twice: #{node}"
+    # @see DSL.find_path
+    def self.find(raw_facts, &decide)
+      facts_without_spy = Factree::Facts.coerce(raw_facts)
+      required_facts = []
+      facts = Factree::FactsSpy.new(facts_without_spy) do |*fact_names|
+        required_facts += fact_names
       end
 
-      # Base case: leaf node (conclusion)
-      return [node] if node.conclusion?
-
-      # Base case: not enough facts to call node.decide
-      missing_facts = node.required_facts - facts.keys
-      return [node] unless missing_facts.empty?
+      conclusion = Factree::Facts.catch_missing_facts do
+        conclusion = decide.call(facts)
+        type_check_conclusion conclusion, &decide
+        conclusion
+      end
 
-      # Recursive case: return full path by prepending this node to the rest
-      next_node = node.decide(facts)
-      type_check_next_node(node, next_node)
-      return [node] + find_node_sequence(next_node, facts, visited + [node])
+      Factree::Path.new(required_facts.uniq, conclusion)
     end
 
-    private_class_method def self.type_check_next_node(source_node, next_node)
-      unless next_node.is_a? Factree::Node
-        raise Factree::InvalidDecisionError,
-          "Expected #{source_node} to return a Factree::Node" +
-          "from #decide. Got: #{next_node.inspect}"
+    private_class_method def self.type_check_conclusion(conclusion, &decide)
+      unless conclusion.is_a? Factree::Conclusion
+        raise Factree::InvalidConclusionError,
+          "Expected #{decide.inspect} to return a Factree::Conclusion. " +
+          "Got #{conclusion.inspect}"
       end
     end
   end

data/lib/factree/version.rb

@@ -1,3 +1,3 @@
 module Factree
-  VERSION = "0.2.0"
+  VERSION = "0.3.1"
 end

data/lib/factree.rb

@@ -1,5 +1,4 @@
 require "factree/version"
-require "factree/decision"
 require "factree/conclusion"
 require "factree/path"
 require "factree/aggregate"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: factree
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Josh Strater
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-04-22 00:00:00.000000000 Z
+date: 2017-04-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -92,6 +92,7 @@ files:
 - ".travis.yml"
 - ".yardopts"
 - Gemfile
+- LICENSE.txt
 - README.md
 - Rakefile
 - bin/console
@@ -100,14 +101,15 @@ files:
 - lib/factree.rb
 - lib/factree/aggregate.rb
 - lib/factree/conclusion.rb
-- lib/factree/decision.rb
 - lib/factree/dsl.rb
-- lib/factree/node.rb
+- lib/factree/facts.rb
+- lib/factree/facts_spy.rb
 - lib/factree/path.rb
 - lib/factree/pathfinder.rb
 - lib/factree/version.rb
 homepage: https://github.com/jstrater/factree
-licenses: []
+licenses:
+- MIT
 metadata: {}
 post_install_message: 
 rdoc_options: []
@@ -125,7 +127,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.8
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
 summary: Decision trees that request facts as needed

data/lib/factree/decision.rb

@@ -1,35 +0,0 @@
-require 'factree/node'
-
-# A Decision is a single node in a decision tree. It's responsible for choosing the next node based on the given set of facts.
-class Factree::Decision < Factree::Node
-  # The names of the facts required to make this decision
-  # @return [Array<Symbol>]
-  attr_reader :required_facts
-
-  # Create a new decision tree node. The block is used to decide on the next node for a given set of facts when navigating through the tree.
-  #
-  # The block will be called with a hash containing all of the available facts. It must return another {Decision} (the next decision in the path through the tree) or a {Conclusion}.
-  #
-  # @param [Array<Symbol>] required_facts The names of facts required to decide on the next node.
-  def initialize(required_facts=[], &decide)
-    @decide = decide
-    @required_facts = required_facts.uniq.freeze
-    freeze
-  end
-
-  # Use the provided facts to decide on the next step.
-  # @return [Decision, Conclusion] The next node
-  def decide(facts)
-    @decide.call(facts)
-  end
-
-  def to_s
-    "<Factree::Decision decide=#{@decide} required_facts=[#{required_facts.join(", ")}]>"
-  end
-
-  def ==(other)
-    other.is_a?(self.class) &&
-      @required_facts == other.required_facts &&
-      @decide == other.instance_variable_get(:@decide)
-  end
-end

data/lib/factree/node.rb

@@ -1,10 +0,0 @@
-# This is the base class for nodes in a decision tree.
-class Factree::Node
-  def conclusion?
-    false
-  end
-
-  def required_facts
-    []
-  end
-end