factree 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 85ee803b7b9d0ab2cbc2976de3003ebecf2298f7
-  data.tar.gz: 69fb2de29736f1b6c8ef2bd69103443f0c01a169
+  metadata.gz: 8a171e984d21c6824ec69bb8a461563f96cbaf95
+  data.tar.gz: 25e9413763b51a2a77aa217666d85853f9035ba9
 SHA512:
-  metadata.gz: 97c439bb519778fdadfb8122963dd7ead6550714f41070726e0d983b21bd76b0a96218af9489008b7f93266ec4042042478124c37c0a70e6794022f92a622c90
-  data.tar.gz: 3b37ad1ce717ca70a19d380e8a36172c0e2af65f4e195cbe8b920b0e6d083a3083031fea5a5b2b7d0c07c601a07d6123e4b1c31f3a4a42af3a8e7d91d7d3a582
+  metadata.gz: 9b1c0dbde274679313374c443e1bc8789a41ab77f89c62d03ea5b099fe544715889e7b68e54bdb71860930c68b50a76cb7d7137427f8f790658653b40d19a75c
+  data.tar.gz: 632b3d41a120579b617bba30f8afbc1283dd33d67c871fe5ae2efde350bbf613f35a599ed082cde1c5d55b25854bd333dab06900f5aff26a642c8b0235d6963d

data/CODEOWNERS

@@ -0,0 +1 @@
+* @jstrater

data/README.md

@@ -1,8 +1,9 @@
 # Factree
 [![Gem Version](https://badge.fury.io/rb/factree.svg)](https://rubygems.org/gems/factree)
 [![Build Status](https://travis-ci.org/ConsultingMD/factree.svg?branch=master)](https://travis-ci.org/ConsultingMD/factree)
+[![YARD Docs](https://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/gems/factree)
 
-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.
+Have a complicated decision to make? Factree will guide you through it step by step, identifying exactly which questions you need to answer along the way in order to reach a conclusion.
 
 ## Installation
 
@@ -22,7 +23,197 @@ Or install it yourself as:
 
 ## Usage
 
-[API documentation](http://www.rubydoc.info/gems/factree)
+*For details, check out the [API documentation](http://www.rubydoc.info/gems/factree).*
+
+### Finding paths through a decision function
+
+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 any are missing, Factree will tell you what's needed to continue.
+
+For example, say I want to pick an animal based on its attributes. First I'll write a function to make the decision.
+
+```ruby
+include Factree::DSL
+
+decide = ->(facts) do
+  return conclusion :turtle unless facts[:mammal?]
+
+  if facts[:herbivore?]
+    conclusion :rabbit
+  else
+    conclusion :dog
+  end
+end
+```
+
+Then I'll pass that function to {Factree.find_path `find_path`} without any facts.
+
+```ruby
+path = find_path &decide
+
+path.complete?
+#=> false
+
+path.required_facts
+#=> [:mammal?]
+```
+
+`find_path` will run my `decide` function until it reaches a conclusion or asks for a fact that is unknown. In this case, my function checks `facts[:mammal?]` right off the bat, and since I didn't provide that fact, `find_path` stopped there. The path through my decision tree was incomplete.
+
+Thankfully, `find_path` keeps track of all of the facts that are requested as it makes its way through a decision function. If it has to stop because a fact is unknown, the fact's name will be included in {Path.required_facts `required_facts`}. You can check `required_facts` to see exactly what's required to progress through the function.
+
+Let's give `find_path` another try, this time with `mammal?: false`.
+
+```ruby
+path = find_path mammal?: false, &decide
+
+path.complete?
+#=> true
+
+path.conclusion
+#=> :turtle
+```
+
+This time `find_path` had all of the facts it needed to reach a conclusion, so it returned a complete path.
+
+Supplying different values for facts may lead to a different path through the decision function, changing the facts that are required. For example, if `mammal?` is true, then we'll also need `herbivore?` to get to a conclusion.
+
+```ruby
+path = find_path mammal?: true, &decide
+
+path.complete?
+#=> false
+
+path.required_facts
+#=> [:mammal?, :herbivore?]
+```
+
+### Using `Factree::DSL`
+
+Including {Factree::DSL `Factree::DSL`} in your code isn't mandatory. It just makes certain methods (like `find_path` and `conclusion`) easier to access. You can call the same methods on the {Factree `Factree`} module.
+
+```ruby
+Factree.find_path **facts, &decide
+
+# is the same as
+
+include Factree::DSL
+find_path **facts, &decide
+```
+
+### Supplying facts
+
+Factree is designed to work with decision functions that depend on many different facts. The {Factree::FactSource FactSource} mixin can help you organize them. A fact source class also provides a place for you to distill complex data into simple values, allowing you to keep your decision functions concise and readable.
+
+Here's an example of a fact source that supplies a set of facts to help select a car for a buyer.
+
+```ruby
+class DriverFactSource
+  include Factree::FactSource
+
+  def initialize(person)
+    @person = person
+    freeze
+  end
+
+  def_fact(:needs_fast_car?) { @person.name == 'Ricky Bobby' }
+
+  def_fact(:needs_cheap_car?) { @person.account_balance < 500.00 }
+
+  def_fact(:needs_extra_seats?) do
+    unknown if @person.family_size == :unknown
+
+    @person.family_size > 4
+  end
+end
+```
+
+Our DriverFactSource is just a class with some method-like fact definitions. Let's instantiate it for a person and see how it works.
+
+```ruby
+Person = Struct.new(:name, :account_balance, :family_size)
+tom = Person.new("Tom", 10_000.00, :unknown)
+source = DriverFactSource.new(tom)
+```
+
+The source's primary job is to crank out a set of facts that can be fed into `find_path`.
+
+```ruby
+source.to_h
+#=> {:needs_fast_car?=>false, :needs_cheap_car?=>false}
+```
+
+Two of the facts we defined are included, but you might have noticed that `:needs_extra_seats?` is missing. Since we're dealing with facts that might not be known, FactSource provides an easy way to conditionally omit those facts. Just call {Factree::FactSource#unknown `#unknown`} instead of returning a value, and the fact will be omitted from the collection returned by {Factree::FactSource#to_h `#to_h`}. Attempting to {Factree::FactSource#fetch `#fetch`} it will raise an error.
+
+```ruby
+source.fetch(:needs_extra_seats?)
+# Factree::FactSource::UnknownFactError: unknown fact: needs_extra_seats?
+```
+
+### Organizing your decision functions
+
+It's recommended that you define your decision functions in their own modules, particularly when they're large or complex. For example:
+
+```ruby
+module Decisions
+  def self.decide_something(facts)
+    # ...
+  end
+end
+```
+
+A method reference can be used to pass your decision function to `#find_path`.
+
+```ruby
+find_path **facts, &Decisions.method(:decide_something)
+```
+
+#### Splitting up large functions
+
+Factree comes with a tool for splitting big decisions into separate functions to simplify them and make them independently testable. Take this cheese choice, for example.
+
+```ruby
+def choose_cheese(facts)
+  if facts[:soft?]
+    return conclusion :brie unless facts[:blue?]
+    return conclusion :gorgonzola if facts[:cows_milk?]
+    conclusion :brie
+  else
+    return conclusion :pecorino_toscano unless facts[:from_cows_milk?]
+    return conclusion :emmental if facts[:holes?]
+    conclusion :gruyere
+  end
+end
+```
+
+Say I wanted to split up my choice into separate functions for soft and hard cheeses. I can use {Factree.decide_between_alternatives `decide_between_alternatives`} to accomplish that.
+
+```ruby
+def choose_soft_cheese(facts)
+  return unless facts[:soft?]
+
+  return conclusion :brie unless facts[:blue?]
+  return conclusion :gorgonzola if facts[:cows_milk?]
+  conclusion :roquefort
+end
+
+def choose_hard_cheese(facts)
+  return if facts[:soft?]
+
+  return conclusion :pecorino_toscano unless facts[:from_cows_milk?]
+  return conclusion :emmental if facts[:holes?]
+  conclusion :gruyere
+end
+
+def choose_cheese(facts)
+  decide_between_alternatives facts,
+    method(:choose_soft_cheese),
+    method(:choose_hard_cheese)
+end
+```
+
+`decide_between_alternatives` will try each decision function in order. If the first returns `nil`, it will try the second, and so on, until a conclusion or an unknown fact is reached.
+
+By splitting up my decision method into two separate ones, I've made them independently testable. They can also be reordered, and I've eliminated a level of nesting inside of a conditional statement.
 
 ## Development
 

data/lib/factree/version.rb

@@ -1,3 +1,3 @@
 module Factree
-  VERSION = "0.5.0"
+  VERSION = "0.5.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: factree
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Josh Strater
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-07-06 00:00:00.000000000 Z
+date: 2017-08-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -91,6 +91,7 @@ files:
 - ".ruby-version"
 - ".travis.yml"
 - ".yardopts"
+- CODEOWNERS
 - Gemfile
 - LICENSE.txt
 - README.md