fact_checker 0.0.3 → 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 49efc644177e73e8127c70768faeb8d3c4f29b54
+  data.tar.gz: 7c91d43ed59898af6d528880e15cd69375eb4940
+SHA512:
+  metadata.gz: 69ae38383592c810071ecef53093fbfc13844eeb30aac26b5679a8757243ffb2cc476cb9a6dd4e2e6297f12ff46a30cc8db554ca8cbc14dd0b342afd060d960d
+  data.tar.gz: 8103359a9eeff6f0d438dffbbaccd8fa33bef1d2b5a3e614a2bea835f10f90250d0eaea9c1c15f50d17b2015c849bcbbe4926714cabec5c709743fc57baf4de0

data/.ruby-gemset

@@ -0,0 +1 @@
+fact_checker

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.0.0

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 1.9.2
+  - 1.9.3

data/README.md

@@ -1,10 +1,7 @@
-# Fact Checker
+# Fact Checker [![Build Status](https://secure.travis-ci.org/alexis/fact_checker.png?branch=master)](http://travis-ci.org/alexis/fact_checker)
+[![Code Climate](https://codeclimate.com/github/alexis/fact_checker.png)](https://codeclimate.com/github/alexis/fact_checker)
 
-  Simple ruby gem to check hierarchically dependent "facts" about objects.
-
-## Installation
-
-    gem install fact_checker
+  Simple ruby gem to define and check hierarchically dependent "facts" about objects.
 
 ## Synopsys
 
@@ -12,20 +9,108 @@
 class Person
   include FactChecker
 
-  def_fact :good_job,    if: ->(p) { p.job.good? }
-  def_fact :good_family, if: ->(p) { p.family.good? }
-  def_fact :is_healthy,  if: ->(p) { p.health.good? }
-  def_fact :is_happy => [:is_healthy, :good_family, :good_job],  if: ->(p) { ! p.too_clever? }
+  define_fact(:good_job)    { p.job.good? }
+  define_fact(:good_family) { p.family.good? }
+  define_fact(:is_healthy)  { p.health.good? }
+  define_fact(:is_happy => [:is_healthy, :good_family, :good_job]) { ! p.too_clever? }
 
   ...
 end
 
-p = Person.new(:job => good_job, :family => good_family, :health => :good, :intellect => :too_clever)
-p.good_job?                 # => true
-p.good_family?              # => true
-p.is_healthy?               # => true
-p.fact_possible?(:is_happy) # => true (dependency satisfied)
-p.is_happy?                 # => false
+p = Person.new(job: good_job, family: good_family, health: :good, intellect: :too_clever)
+p.good_job?                     # => true
+p.good_family?                  # => true
+p.is_healthy?                   # => true
+p.is_happy.available?           # => true (dependency satisfied)
+p.is_happy?                     # => false
+```
+
+## Description
+
+The gem is most usefull when you have something
+like a checklist, a list of tasks that your users should complete to achieve some goal. 
+
+For example, let's say that in order to publish an article, user have to:
+
+1. write the article
+2. name the article (user may complete steps 1 & 2 in any order)
+3. choose its category
+4. assign tags to the article (user may complete steps 3 & 4 in any order, but only after steps 1 & 2)
+5. mark article as ready for review (only after steps 1-3 are completed, but step 4 is not required)
+6. recieve approvement from one of moderators (all steps 1-5 are required)
+
+<!--- The imporant thing here - which makes fact_checker worth its use - is that you want to display this 
+checklist for users in a way that they could instantly understand which steps are completed, which
+is not available yet, and which are ready for action.
+This means that each step could be in 3 different states: "completed", "ready for action" and "not available".
+-->
+
+Using fact_checker that logic could be implemented like this:
+
+```ruby
+include FactChecker
+
+define_fact(:step1)                     { content.present? }
+define_fact(:step2)                     { name.present? }
+define_fact(:step3 => [:step1, :step2]) { category.present? }
+define_fact(:step4 => [:step1, :step2]) { tag_list.present? }
+define_fact(:step5 => :step3)           { ready_for_approvement? }
+define_fact(:step6 => [:step4, :step5]) { approved? }
+
+def state_of(step)
+  return 'completed'         if valid?(step)
+  return 'ready_for_action'  if available?(step)
+  return 'not_available'
+end
+```
+
+Just to compare, a possible alternative implimentation without fact_checker:
+
+``` ruby
+def step1_available?
+  true
+end
+def step1_valid?
+  content.present?
+end
+def step2_available?
+  true
+end
+def step2_valid?
+  name.present?
+end
+def step3_available?
+  step1? && step2?
+end
+def step3_valid?
+  step3_available? && a.category.present?
+end
+def step4_available?
+  step1? && step2?
+end
+def step4_valid?
+  step4_available? && tag_list.present?
+end
+def step5_available?
+  step3
+end
+def step5_valid?
+  step5_available? && a.ready_for_approvement?
+end
+def step6_available?
+  step4? && step5
+end
+def step6_valid?
+  step6_available? && a.approved?
+end
 
-p.possible_facts - p.accomplished_facts # => [:happy]
+def state_of(step)
+  return 'completed'         if self.send(step + '_valid?')
+  return 'ready_for_action'  if self.send(step + '_available?')
+  return 'not_available'
+end
 ```
+
+## Installation
+
+    gem install fact_checker

data/fact_checker.gemspec

@@ -20,11 +20,12 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
-  s.required_ruby_version = ">= 1.8.7"
-  s.required_rubygems_version = ">= 1.3.5"
+  s.required_ruby_version     = '>= 1.9.2'
+  s.required_rubygems_version = '>= 1.3.5'
 
   s.add_development_dependency 'rake'
   s.add_development_dependency 'bundler'
-  s.add_development_dependency 'rspec', '~> 2.9.0'
-  s.add_development_dependency 'simplecov', '~> 0.6.1'
+  s.add_development_dependency 'rspec',     '~> 2.14'
+  s.add_development_dependency 'simplecov'
+  s.add_development_dependency 'debugger'
 end

data/lib/fact_checker/mixin.rb

@@ -0,0 +1,32 @@
+# encoding: utf-8
+
+module FactChecker
+  def self.included(klass)
+    klass.extend ClassMethods
+  end
+
+  module ClassMethods
+    def define_fact(arg, &block)
+      fail ArgumentError, 'block not supplied'  unless block
+
+      name, dependencies = arg.is_a?(Hash) ? arg.to_a.flatten(1) : [arg, []]
+
+      (@fact_checker_facts ||= []) << name.to_sym
+
+      define_method(name) do
+        dependencies_satisfied = [*dependencies].all?{ |dep_name| send(dep_name).valid? }
+        Result.new(dependencies_satisfied, instance_eval(&block))
+      end
+
+      define_method("#{name}?") do
+        send(name).valid?
+      end
+
+      private name, "#{name}?"  if name[0] == '_'
+    end
+
+    def facts
+      ancestors.reverse.map{ |klass| klass.instance_eval{ @fact_checker_facts } }.compact.flatten(1)
+    end
+  end
+end

data/lib/fact_checker/result.rb

@@ -0,0 +1,18 @@
+# encoding: utf-8
+
+module FactChecker
+  class Result
+    def initialize(dependency_state, requirement_state)
+      @dependency_state = dependency_state
+      @requirement_state = requirement_state
+    end
+
+    def valid?
+      @dependency_state && @requirement_state
+    end
+
+    def available?
+      @dependency_state
+    end
+  end
+end

data/lib/fact_checker/version.rb

@@ -1,5 +1,5 @@
 # encoding: utf-8
 
 module FactChecker
-  VERSION = '0.0.3'
+  VERSION = '0.1.0'
 end

data/lib/fact_checker.rb

@@ -1,5 +1,5 @@
 # encoding: utf-8
 
-require 'fact_checker/base'
 require 'fact_checker/version'
-require 'fact_checker/boot'
+require 'fact_checker/result'
+require 'fact_checker/mixin'

data/spec/mixin_spec.rb

@@ -0,0 +1,238 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe FactChecker do
+  context "when included into a class" do
+
+    let(:klass) { Class.new { include FactChecker } }
+
+    describe ".facts" do
+      it "exists" do
+        expect(klass.superclass.methods).to_not include(:facts)
+        expect(klass.methods).to include(:facts)
+      end
+
+      it "returns [] when no facts were defined" do
+        expect(klass.facts).to eq([])
+      end
+
+      it "returns list of all defined facts names" do
+        klass.class_eval do
+          define_fact(:x) {}
+          define_fact(:y => [:x, :x1]) {}
+        end
+
+        expect(klass.facts).to eq([:x, :y])
+      end
+
+      it "returns independent results for independent classes" do
+        klass1 = Class.new { include FactChecker; define_fact(:x) {} }
+        klass2 = Class.new { include FactChecker; define_fact(:y) {} }
+        expect(klass1.facts).to eq([:x])
+        expect(klass2.facts).to eq([:y])
+      end
+
+      it "returns one-way dependent results for superclass and subclasses" do
+        klass1 = Class.new { include FactChecker; define_fact(:x) {} }
+        klass2 = Class.new(klass1) { define_fact(:y) {} }
+        klass3 = Class.new(klass2) { define_fact(:z) {} }
+        klass1.class_eval { define_fact(:q) {} }
+
+        expect(klass1.facts).to eq([:x, :q])
+        expect(klass2.facts).to eq([:x, :q, :y])
+        expect(klass3.facts).to eq([:x, :q, :y, :z])
+      end
+
+      it "returns symbols even when facts were defined with string names" do
+        klass.define_fact('x') {}
+        expect(klass.facts).to eq([:x])
+      end
+    end
+
+
+    describe ".define_fact" do
+      it "exists" do
+        expect(klass.superclass.methods).to_not include(:define_fact)
+        expect(klass.methods).to include(:define_fact)
+      end
+
+      context "when called with no arguments" do
+        it "raises an ArgumentError" do
+          expect{klass.define_fact}.to raise_error(ArgumentError)
+        end
+      end
+
+      context "when called with (:name)" do
+        it "raises an ArgumentError" do
+          expect{klass.define_fact(:x)}.to raise_error(ArgumentError)
+        end
+      end
+
+      context "when called with (:name, &block)" do
+        it "behaves as if it was called with (:name => [], &block)" do
+          klass.define_fact(:x) { :result }
+          expect(klass.instance_methods).to include(:x)
+          expect(klass.instance_methods).to include(:x?)
+          expect(klass.new.x.valid?).to be(:result)
+          expect(klass.new.x.available?).to be(true)
+          expect(klass.new.x?).to be(:result)
+        end
+      end
+
+      context "when called with (:name => :dependency_name, &block)" do
+        it "behaves as if it was called with (:name => [:dependency_name], &block)" do
+          klass.define_fact(:y) { false }
+          klass.define_fact(:x => :y) { :result }
+          expect(klass.instance_methods).to include(:x)
+          expect(klass.instance_methods).to include(:x?)
+          expect(klass.new.x.valid?).to be(false)
+          expect(klass.new.x.available?).to be(false)
+          expect(klass.new.x?).to be(false)
+
+          klass.define_fact(:y) { true }
+          klass.define_fact(:x => :y) { :result }
+          expect(klass.new.x.valid?).to be(:result)
+          expect(klass.new.x.available?).to be(true)
+          expect(klass.new.x?).to be(:result)
+        end
+      end
+
+      context "when called with (:name => dependency_names, &block)" do
+        it "defines an instance method #name" do
+          expect(klass.instance_methods).to_not include(:x)
+          klass.define_fact(:x => []) {}
+          expect(klass.instance_methods).to include(:x)
+        end
+
+        it "defines an instance method #name?" do
+          expect(klass.instance_methods).to_not include(:x?)
+          klass.define_fact(:x => []) {}
+          expect(klass.instance_methods).to include(:x?)
+        end
+
+        context "and the newly defined instance methods:" do
+          let(:instance) { klass.new }
+
+          describe "#<name>" do
+            it "returns an object of FactChecker::Result" do
+              klass.define_fact(:x => []) {}
+              expect(instance.x).to be_a_kind_of(FactChecker::Result)
+            end
+
+            it "evaluates block in the context of the current instance" do
+              klass.define_fact(:x => []) { check? }
+              klass.class_eval { def check?; end }
+              expect(instance).to receive(:check?).and_call_original
+              instance.x
+            end
+
+            context "when the :name fact has blank dependencies" do
+              before(:each) { klass.define_fact(:x => []) {:result} }
+
+              it "returns result with .valid? == block.call" do
+                expect(instance.x.valid?).to be(:result)
+              end
+
+              it "returns result with .available? == true" do
+                expect(instance.x.available?).to be_true
+              end
+            end
+
+            context "when the :name fact has valid dependencies" do
+              before(:each) do
+                klass.class_eval do
+                  define_fact(:x) { true }
+                  define_fact(:y) { :truthy }
+                  define_fact(:z => [:x, :y]) { :result }
+                end
+              end
+
+              it "returns result with .valid? == block.call" do
+                expect(instance.z.valid?).to be(:result)
+              end
+
+              it "returns result with .available? == true" do
+                expect(instance.z.available?).to be_true
+              end
+            end
+
+            context "when the :name fact has at least 1 invalid dependency" do
+              before(:each) do
+                klass.class_eval do
+                  define_fact(:x) { true }
+                  define_fact(:y) { false }
+                  define_fact(:z => [:x, :y]) { :something }
+                end
+              end
+
+              it "returns result with .valid? == false" do
+                expect(instance.z.valid?).to be(false)
+              end
+
+              it "returns result with .available? == false" do
+                expect(instance.z.available?).to be(false)
+              end
+            end
+
+            context "when the :name fact has dependencies inherited from a superclass" do
+              it "return correct results" do
+                klass1 = Class.new(klass)
+                klass.define_fact(:x) { true }
+                klass.define_fact(:y) { false }
+                klass1.define_fact(:z1 => [:x, :y]) { true }
+                klass1.define_fact(:z2 => [:x]) { true }
+                klass1.define_fact(:z3 => [:x]) { false }
+                instance = klass1.new
+
+                expect(instance.z1.valid?).to be(false)
+                expect(instance.z1.available?).to be(false)
+                expect(instance.z2.valid?).to be(true)
+                expect(instance.z3.available?).to be(true)
+                expect(instance.z3.valid?).to be(false)
+                expect(instance.z2.available?).to be(true)
+              end
+            end
+          end
+
+          describe "#<name>?" do
+            it "delegates to name.valid?" do
+              klass.define_fact(:x) {}
+              result = double(:valid? => :yeah!)
+              expect(instance).to receive(:x).and_return(result)
+              expect(instance.x?).to be(:yeah!)
+            end
+          end
+        end
+      end
+
+      context "when called with ('name' => string_deppendency_names, &block)" do
+        it "defines an instance method #name" do
+          expect(klass.instance_methods).to_not include(:x)
+          klass.define_fact('x' => []) {}
+          expect(klass.instance_methods).to include(:x)
+        end
+
+        it "defines an instance method #name?" do
+          expect(klass.instance_methods).to_not include(:x?)
+          klass.define_fact('x' => []) {}
+          expect(klass.instance_methods).to include(:x?)
+        end
+      end
+
+      context "when called with (:_underscored_name => dependency_names, &block)" do
+        it "marks new #_underscored_name method as private" do
+          klass.define_fact(:_x) {}
+          expect{ klass.new._x }.to raise_error
+        end
+
+        it "marks new #_undersrored_name? method as private" do
+          klass.define_fact(:_x) {}
+          expect{ klass.new._x? }.to raise_error
+        end
+      end
+    end
+
+  end
+end
+