factree 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5c35f29630bd9cb9399531725ed218c5da73e1c2
+  data.tar.gz: '09686d69ee9aeb3ea37f75d13af3c2f686dfa11e'
+SHA512:
+  metadata.gz: faf9cbfe994babe6b72d2038a8cab88f4123db61d505afdb26e0f07b57175456b49293558836ad48cd9809da8f93d78a195608910efa4eab5e71b5513c0b1bac
+  data.tar.gz: 2a279be3fa08b4fb588195eb6d6fd948ca759f19d8d622701478cf0694b328e6e299380aede9998c33523030720d2bac87f1974511ef6d2d93bc7c25f6ed7f80

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.ruby-version

@@ -0,0 +1 @@
+2.4.0

data/.travis.yml

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

data/.yardopts

@@ -0,0 +1,2 @@
+lib/**/*.rb - README.md
+--embed-mixin DSL

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in factree.gemspec
+gemspec

data/README.md

@@ -0,0 +1,35 @@
+# 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.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'factree'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install factree
+
+## Usage
+
+[API documentation](http://www.rubydoc.info/github/jstrater/factree/)
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/jstrater/factree.
+

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "factree"
+
+include Factree::DSL
+
+require "pry"
+Pry.start

data/bin/setup

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install

data/factree.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'factree/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "factree"
+  spec.version       = Factree::VERSION
+  spec.authors       = ["Josh Strater"]
+  spec.email         = ["jstrater@gmail.com"]
+
+  spec.summary       = %q{Decision trees that request facts as needed}
+  spec.homepage      = "https://github.com/jstrater/factree"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.14"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "yard", "~> 0.9"
+end

data/lib/factree/aggregate.rb

@@ -0,0 +1,28 @@
+require 'factree/decision'
+
+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
+    end
+  end
+end

data/lib/factree/conclusion.rb

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

data/lib/factree/decision.rb

@@ -0,0 +1,35 @@
+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/dsl.rb

@@ -0,0 +1,24 @@
+require 'factree/decision'
+require 'factree/conclusion'
+require 'factree/path'
+require 'factree/aggregate'
+
+# 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)
+    Factree::Conclusion.new(value)
+  end
+
+  def path(through:, given: {})
+    Factree::Path.through_tree(through, given)
+  end
+
+  def decision_with_alternatives(*decisions)
+    Factree::Aggregate.alternatives(*decisions)
+  end
+end

data/lib/factree/node.rb

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

data/lib/factree/path.rb

@@ -0,0 +1,43 @@
+require 'factree/pathfinder'
+
+# 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
+
+  # A path is {complete?} if it has reached a conclusion.
+  def complete?
+    @nodes.last.conclusion?
+  end
+
+  # Returns the conclusion value if this path is complete.
+  def conclusion
+    raise "Attempted to get conclusion from incomplete path" unless complete?
+
+    @nodes.last.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
+
+  def ==(other)
+    other.is_a?(self.class) &&
+      @nodes == other.instance_variable_get(:@nodes)
+  end
+end

data/lib/factree/pathfinder.rb

@@ -0,0 +1,36 @@
+module Factree
+  CycleError = Class.new(StandardError)
+  InvalidDecisionError = 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}"
+      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?
+
+      # 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])
+    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}"
+      end
+    end
+  end
+end

data/lib/factree/version.rb

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

data/lib/factree.rb

@@ -0,0 +1,10 @@
+require "factree/version"
+require "factree/decision"
+require "factree/conclusion"
+require "factree/path"
+require "factree/aggregate"
+require "factree/dsl"
+
+module Factree
+  extend DSL
+end

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification
+name: factree
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Josh Strater
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-04-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: 
+email:
+- jstrater@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".ruby-version"
+- ".travis.yml"
+- ".yardopts"
+- Gemfile
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- factree.gemspec
+- 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/path.rb
+- lib/factree/pathfinder.rb
+- lib/factree/version.rb
+homepage: https://github.com/jstrater/factree
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.8
+signing_key: 
+specification_version: 4
+summary: Decision trees that request facts as needed
+test_files: []