zitdunyet 0.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.idea/*

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 David Pellegrini
+
+MIT License
+
+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

@@ -0,0 +1,139 @@
+# Zitdunyet
+
+We're all familiar with social websites where you create an account and then are encouraged to provide information about yourself.  They often have something when you login that announces "Your profile is 55% complete.  Add a photo to reach 70%!" The notion of completeness can be applied to objects of all sort, to processes, and so on.
+
+This gem provides a general solution for expressing and assessing completeness.  It includes:
+
++ a DSL for expressing the conditions
++ methods to report completeness as True/False or percentage
++ a method to provide hints for completion
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'zitdunyet'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install zitdunyet
+
+## Usage
+
+To use the gem, first require the gem and include the Completeness module into the class for which you want to track completeness.
+
+    require 'zitdunyet'
+
+    class UserAccount
+      include Zitdunyet::Completeness
+
+      attr_accessor :name, :birthday, :favorite_color, :friends
+      ... etc ...
+    end
+
+If you'd rather separate concerns, create a Decorator for your model and include the Completeness module there.
+
+    require 'zitdunyet'
+
+    class UserAccountCompleteness
+      include Zitdunyet::Completeness
+
+      def initialize(user_account)
+        @user_accout = user_account
+      end
+      ... etc ...
+    end
+
+### Basic use case
+
+I'm reminded of Larry Wall's admonition to make simple things easy and difficult things possible.  In that spirit, let's start with a simple use case.
+
+#### Checkoff items
+
+The conditions for completeness are represented as check-off items.  Check-off items are expressed using the #checkoff class macro.
+
+The arguments are:
+
++ label - a String or something that evaluates to a String to identify the item
++ amount - how much of the completeness is tied to this item, expressed in percent or units
++ options - hint to encourage completion of this item
++ logic - a block to evaluate that determines if this item is done. The block is passed _self_ and evaluates to _true_/_false_.
+
+Let's start with a simple use case in the context of UserAccount.
+
+    checkoff "Name", 30.percent do |s| s.name end
+    checkoff "Birthday", 25.percent do |s| s.birthday end
+    checkoff "Favorite Color", 15.percent do |s| not s.favorite_color.nil? end
+    checkoff "Friends", 30.percent do |s| s.friends.size >= 3 end
+
+This basically gives credit when name, birthday, and favorite_color have values, and when the user has specified 3 or more friends.  Of course, the details of enforcing good values for these fields (e.g., birthdate is actually a Date, friends is an array) is not shown and is your responsibility, not this gem's.
+
+When writing the checkoff, you may chose to use ()'s and {}'s or break the do ... end over multiple lines if that's more your style.  I adopted the style above because it reads well as a DSL.  Ruby purists may have another opinion.  Any valid Ruby method syntax is fair game, though.
+
+    checkoff("Favorite Color", 15.percent) { |s| s.favorite_color }
+    checkoff "Friends", 30.percent do |s|
+      s.friends.size >= 3
+    end
+
+#### Testing completeness
+
+Instances of the class can be tested for completeness by using instance methods defined in Completeness:
+
++ #complete? - returns true if all of the check-off items' logic blocks evaluate to true; false otherwise
++ #percent_complete - returns a number 0-100 that represents the sum of percentages associated with check-off items that evaluate to true.  If the percentages specified for all of the check-off items total 100, then the result is a strict sum of the completed check-off items.  If the percentages specified total less than 100, then the returned value is scaled to make up the shortfall.
+
+#### Hints
+
+If your UserAccount happens to be incomplete, it would be nice to know what you need to do to complete it.
+
++ #hints - returns a hash in which the keys are the labels or hints of the uncompleted steps and the values are the percentages
+
+By using descriptive labels you can give a decent prompt to the user.
+
+    checkoff "Birthday filled in", 25.percent do |s| s.birthday end
+    checkoff "At least 3 friends", 30.percent do |s| s.friends.size >= 3 end
+
+Sometimes, though, you may want to be more elaborate in your hinting.  #checkoff accepts an optional argument, :hint, for such situations.  The hint must be a string or a block that evaluates to a String.
+
+    checkoff "Favorite Color", 15.percent, hint: "What's your favorite color?" do |s| s.favorite_color end
+    checkoff "Friends", 30.percent, hint: lambda {|s| "Add #{3-s.friends.size} friends"} do |s| s.friends.size >= 3 end
+
+The hint over-rides the label when reported by #hints.
+
+### Advanced Usage
+
+Basic usage is fine for most situations, but sometimes you need a little something extra.
+
+#### Units
+
+Percentages are easy to understand, but have the annoying property of having to total 100.  As noted above, the #percent_complete method is forgiving when your totals fall short, but that may be surprising when you start seeing "43.375% complete" reported when you know all your specified percentages are on the 5's and 10's.  Also, checkoff will squawk at you if you attempt to specify a percentage that puts you over 100.
+
+Instead of percent, the checkoff amount can be expressed in units.  This gives you the freedom to specify relative values at whatever scale you like.  #percent_complete will calculate the percentages for you.
+
+    checkoff "Step 1", 1.unit do |s| s.step_1_done? end
+    checkoff "Step 2", 1.unit do |s| s.step_2_done? end
+    checkoff "Step 3", 1.unit do |s| s.step_3_done? end
+
+This strategy will allow you to add a "Step 4" down the road without having to rejigger percentage.
+
+#### Mixing Percent and Units
+
+You may mix both percent and units in a series of checkoffs if desired. Let's say you want the user name to always count for 30% regardless of anything else.  You could assign it 30% and assign units to the other items.  #percent_complete will honor the explicit percents and scale the units into whatever remains.
+
+#### Inheritance
+
+Let's say you have a special account that subclasses UserAccount.  You want the special account to have additional steps toward completion.  No problem.  Simply specify the additional checkoff items in the subclass.  When evaluating completion, the checkoff items in the UserAccount will be evaluated along with the checkoff items in the subclass.
+
+In situations where subclassing is a possibility it is good practice to specify the checkoff amounts in units rather than percent.  That way the superclass can be complete relative to itself when instantiated, while allowing the subclass to contribute its share when it is instantiated without blowing the 100% barrier.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+#!/usr/bin/env rake
+# -*- ruby -*-
+require "bundler/gem_tasks"
+
+$LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
+
+# RSpec
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new('spec')
+
+task :default => :spec

data/lib/zitdunyet/checkoff.rb

@@ -0,0 +1,40 @@
+module Zitdunyet
+  class Checkoff
+    attr_accessor :label, :percent, :units, :logic, :hint, :stale, :when
+
+    def initialize(label, progress_amount, *opts, &logic)
+      # Fill in the required fields
+      (label.is_a? String) ? self.label = label : (raise ArgumentError.new "Label must be a String")
+      assign_progress(progress_amount)
+      block_given? ? self.logic = logic : (raise ArgumentError.new "Missing the block for assessing completion")
+
+      # Fill in the optional fields if present
+      assign_options(opts) unless opts.empty?
+    end
+
+    def assign_options(opts)
+      options = opts.first
+      self.hint = options.delete(:hint)
+      #self.stale = options.delete(:stale)
+      #self.when = options.delete(:when)
+      raise ArgumentError.new "Unrecognized options: #{options.inspect}" unless options.empty?
+
+      #if self.stale or self.when
+      #  raise ArgumentError.new "Specified 'stale' without 'when'" unless self.when
+      #  raise ArgumentError.new "Specified 'when' without 'stale'" unless self.stale
+      #end
+    end
+
+    def assign_progress(progress_amount)
+      if progress_amount.is_a? Zitdunyet::Unit
+        self.units=progress_amount.amount
+      elsif progress_amount.is_a? Zitdunyet::Percent
+        self.percent=progress_amount.amount
+      elsif progress_amount.is_a? Numeric
+        self.percent=progress_amount
+      else
+        raise ArgumentError.new "Invalid type for progress amount: #{progress_amount.class}"
+      end
+    end
+  end
+end

data/lib/zitdunyet/class_specific.rb

@@ -0,0 +1,40 @@
+module Zitdunyet
+  module ClassSpecific
+
+    def checklist
+      checklist = self.superclass.respond_to?(:checklist) ? self.superclass.send(:checklist) : []
+      @checklist ? checklist + @checklist : checklist
+    end
+
+    def checklist_add(item)
+      @checklist = (@checklist || []) << item
+    end
+
+    def percentage
+      percentage = self.superclass.respond_to?(:percentage) ? self.superclass.send(:percentage) : 0
+      percentage + (@percentage || 0)
+    end
+
+    def percentage=(amount)
+      @percentage = amount
+    end
+
+    def percentage_add(amount)
+      @percentage = (@percentage || 0) + amount
+    end
+
+    def units
+      units = self.superclass.respond_to?(:units) ? self.superclass.send(:units) : 0
+      units + (@units || 0)
+    end
+
+    def units=(amount)
+      @units = amount
+    end
+
+    def units_add(amount)
+      @units = (@units || 0) + amount
+    end
+
+  end
+end

data/lib/zitdunyet/completeness.rb

@@ -0,0 +1,12 @@
+module Zitdunyet
+  module Completeness
+
+    def self.included(base)
+      base.extend Zitdunyet::ClassSpecific
+      base.extend Zitdunyet::Expressions
+    end
+
+    include Zitdunyet::Evaluation
+
+  end
+end

data/lib/zitdunyet/evaluation.rb

@@ -0,0 +1,54 @@
+module Zitdunyet
+  module Evaluation
+
+    def complete?
+      self.class.checklist.each { |item| return false unless item.logic.call(self) }
+      true
+    end
+
+    def percent_complete
+      # Scale the percentages if they don't add up to 100.  When units are part of the mix, scale the units to fit into
+      # the percentage slice leftover after totaling the percentages.
+      unit_percentage = 0
+      pct_percentage = 1
+      if self.class.percentage < 100
+        unit_percentage = ((100 - self.class.percentage) / self.class.units.to_f) if (self.class.units > 0)
+        pct_percentage = (100 / self.class.percentage.to_f) if (self.class.units == 0)
+      elsif self.class.percentage > 100
+        pct_percentage = (100 / self.class.percentage.to_f) if (self.class.units == 0)
+      end
+
+      completed_pct = 0
+      completed_units = 0
+      complete = true
+      @hints = {}
+      self.class.checklist.each do |item|
+        if item.logic.call(self)
+          if item.percent
+            completed_pct += item.percent
+          else
+            completed_units += item.units if item.units
+          end
+        else
+          complete = false
+          hint = item.hint || item.label
+          @hints[hint] = item.percent ? item.percent * pct_percentage : item.units * unit_percentage
+        end
+      end
+      complete ? 100 : (completed_pct * pct_percentage) + (completed_units * unit_percentage)
+    end
+
+    def hints
+      percent_complete unless @hints
+      hints = {}
+      @hints.each_pair do |hint, pct|
+        if hint.respond_to? :call
+          hints[hint.call(self)] = pct
+        else
+          hints[hint.to_s] = pct
+        end
+      end
+      hints
+    end
+  end
+end

data/lib/zitdunyet/expressions.rb

@@ -0,0 +1,14 @@
+module Zitdunyet
+  module Expressions
+
+    def checkoff(label, progress_amount, *opts, &logic)
+      # Create an object to represent the check-off item
+      choff = Checkoff.new(label, progress_amount, *opts, &logic)
+      checklist_add choff
+      percentage_add(choff.percent) if choff.percent
+      units_add(choff.units) if choff.units
+      raise RangeError.new "Percentage total (#{percentage}) exceeds 100%" if percentage > 100
+    end
+
+  end
+end

data/lib/zitdunyet/percent.rb

@@ -0,0 +1,18 @@
+module Zitdunyet
+
+  class Percent
+
+    attr_accessor :amount
+
+    def initialize(amount)
+      self.amount=amount
+    end
+
+  end
+end
+
+class Numeric
+  def percent
+    Zitdunyet::Percent.new(self)
+  end
+end

data/lib/zitdunyet/unit.rb

@@ -0,0 +1,20 @@
+module Zitdunyet
+
+  class Unit
+
+    attr_accessor :amount
+
+    def initialize(amount)
+      self.amount=amount
+    end
+
+  end
+end
+
+class Numeric
+  def unit
+    Zitdunyet::Unit.new(self)
+  end
+
+  alias units unit
+end

data/lib/zitdunyet/version.rb

@@ -0,0 +1,3 @@
+module Zitdunyet
+  VERSION = "0.0.1"
+end

data/lib/zitdunyet.rb

@@ -0,0 +1,12 @@
+require "zitdunyet/version"
+require "zitdunyet/percent"
+require "zitdunyet/unit"
+require "zitdunyet/checkoff"
+require "zitdunyet/class_specific"
+require "zitdunyet/expressions"
+require "zitdunyet/evaluation"
+require "zitdunyet/completeness"
+
+module Zitdunyet
+  # Your code goes here...
+end

data/spec/lib/zitdunyet/checkoff_spec.rb

@@ -0,0 +1,54 @@
+require 'spec_helper'
+
+describe "Initialization" do
+
+  context "Assigning the label" do
+    it "should accept a String" do
+      label = "The Label"
+      co = Zitdunyet::Checkoff.new(label, 0) { "nuthin'" }
+      co.label.should == label
+    end
+
+    it "should reject anything besides a String" do
+      label = 1
+      expect { Zitdunyet::Checkoff.new(label, 10) { "nuthin'" } }.to raise_error(ArgumentError)
+    end
+  end
+
+  context "Assigning progress amount" do
+    it "should accept Unit" do
+      amount = 10.units
+      co = Zitdunyet::Checkoff.new("The Label", amount) { "nuthin'" }
+      co.units.should == amount.amount
+    end
+
+    it "should accept a Percent" do
+      amount = 10.percent
+      co = Zitdunyet::Checkoff.new("The Label", amount) { "nuthin'" }
+      co.percent.should == amount.amount
+    end
+
+    it "should treat Numeric as percentage" do
+      amount = 10
+      co = Zitdunyet::Checkoff.new("The Label", amount) { "nuthin'" }
+      co.percent.should == amount
+    end
+
+    it "should reject invalid type" do
+      amount = "ten"
+      expect { Zitdunyet::Checkoff.new("The Label", amount) { "nuthin'" } }.to raise_error(ArgumentError)
+    end
+  end
+
+  context "Specifying the completion logic" do
+    it "should accept an anonymous block" do
+      text = "this is a test"
+      co = Zitdunyet::Checkoff.new("The Label", 10) { text }
+      co.logic.call.should == text
+    end
+
+    it "should raise an exception if the block is missing" do
+      expect { Zitdunyet::Checkoff.new("The Label", 10) }.to raise_error(ArgumentError)
+    end
+  end
+end

data/spec/lib/zitdunyet/class_attr_spec.rb

@@ -0,0 +1,85 @@
+require "spec_helper"
+
+describe "Class Attr" do
+
+  before(:each) do
+    begin
+      Object.send(:remove_const, :Baz)
+    rescue
+    end
+    begin
+      Object.send(:remove_const, :Foo)
+    rescue
+    end
+  end
+
+  after(:each) do
+    puts "=  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  ="
+  end
+
+  let(:foo) do
+    class Foo
+      extend Zitdunyet::ClassSpecific
+
+      def add(item)
+        self.class.checklist_add item
+        self.class.units_add 1
+      end
+
+      def chklst
+        self.class.checklist
+      end
+
+      def units
+        self.class.units
+      end
+
+      def dump
+        puts "Foo#dump: checklist=#{self.class.checklist}, units=#{self.class.units}"
+      end
+    end
+
+    Foo.new
+  end
+
+  let(:baz) do
+    class Baz < Foo
+      def dump
+        puts "Baz#dump: checklist=#{self.class.checklist}, units=#{self.class.units}"
+      end
+    end
+
+    Baz.new
+  end
+
+  it "should initialize with empty array and zeros" do
+    foo.chklst.should be_empty
+    foo.chklst.should have(0).items
+    foo.units.should == 0
+  end
+
+  it "should define class-specific attrs" do
+    foo.dump
+    foo.add("Hello")
+    foo.dump
+    foo.chklst.should have(1).items
+    foo.units.should == 1
+  end
+
+  it "should support inheritance" do
+    foo.dump
+    foo.add("Hello")
+    foo.dump
+    foo.chklst.should have(1).items
+
+    baz.dump
+    baz.add("World")
+    baz.dump
+    baz.chklst.should have(2).items
+    baz.units.should == 2
+
+    foo.dump
+    foo.chklst.should have(1).items
+    foo.units.should == 1
+  end
+end

data/spec/lib/zitdunyet/evaluations_spec.rb

@@ -0,0 +1,282 @@
+require 'spec_helper'
+
+describe "Evaluations" do
+
+  before(:each) do
+    begin
+      Object.send(:remove_const, :Baz)
+    rescue
+    end
+    begin
+      Object.send(:remove_const, :Foo)
+    rescue
+    end
+  end
+
+  context "basics" do
+    it "should evaluate true" do
+      class Foo
+        include Zitdunyet::Completeness
+        checkoff "Step One", 8.percent do true end
+      end
+
+      foo = Foo.new
+      foo.complete?.should be_true
+    end
+
+    it "should evaluate false" do
+      class Foo
+        include Zitdunyet::Completeness
+        checkoff "Step One", 8.percent do false end
+      end
+
+      foo = Foo.new
+      foo.complete?.should be_false
+    end
+
+    it "should evaluate the condition for self" do
+      class Foo
+        include Zitdunyet::Completeness
+        checkoff "Step One", 60.units do |s| s.blork end
+        checkoff "Step Two", 40.units do |s| s.count >= 3 end
+
+        def blork
+          true
+        end
+
+        def count
+          3
+        end
+      end
+
+      foo = Foo.new
+      foo.complete?.should be_true
+      foo.percent_complete.should == 100
+    end
+  end
+
+  context "Percentages" do
+
+    it "should evaluate 0 percent when no checkoff items are done" do
+      class Foo
+        include Zitdunyet::Completeness
+        checkoff "Step One", 60.percent do false end
+        checkoff "Step Two", 40.percent do false end
+      end
+
+      foo = Foo.new
+      foo.percent_complete.should == 0
+    end
+
+    it "should evaluate intermediate percentage when some checkoff items are done" do
+      class Foo
+        include Zitdunyet::Completeness
+        checkoff "Step One", 60.percent do true end
+        checkoff "Step Two", 40.percent do false end
+      end
+
+      foo = Foo.new
+      foo.percent_complete.should == 60
+    end
+
+    it "should evaluate 100 percent when all checkoff items are done" do
+      class Foo
+        include Zitdunyet::Completeness
+        checkoff "Step One", 60.percent do true end
+        checkoff "Step Two", 40.percent do true end
+      end
+
+      foo = Foo.new
+      foo.percent_complete.should == 100
+    end
+
+    it "should evaluate fractional percentage when specified" do
+      class Foo
+        include Zitdunyet::Completeness
+        checkoff "Step One", 60.5.percent do true end
+        checkoff "Step Two", 39.5.percent do false end
+      end
+
+      foo = Foo.new
+      foo.percent_complete.should == 60.5
+    end
+
+    it "should scale the percentage when the specified percentages don't total 100" do
+      class Foo
+        include Zitdunyet::Completeness
+        checkoff "Step One", 40.percent do true end
+        checkoff "Step Two", 40.percent do false end
+      end
+
+      foo = Foo.new
+      foo.percent_complete.should == 50
+    end
+
+    it "should scale the percentage when the specified percentages exceed 100" do
+      pending "a decision on how to handle excess percentage"
+      class Foo
+        include Zitdunyet::Completeness
+        checkoff "Step One", 60.percent do true end
+      end
+
+      class Baz < Foo
+        include Zitdunyet::Completeness
+        checkoff "Step Two", 60.percent do false end
+      end
+
+      baz = Baz.new
+      baz.percent_complete.should == 50
+    end
+
+  end
+
+  context "Units" do
+
+    it "should evaluate 0 percent when no checkoff items are done" do
+      class Foo
+        include Zitdunyet::Completeness
+        checkoff "Step One", 60.units do false end
+        checkoff "Step Two", 40.units do false end
+      end
+
+      foo = Foo.new
+      foo.percent_complete.should == 0
+    end
+
+    it "should evaluate intermediate percentage when some checkoff items are done" do
+      class Foo
+        include Zitdunyet::Completeness
+        checkoff "Step One", 60.units do true end
+        checkoff "Step Two", 40.units do false end
+      end
+
+      foo = Foo.new
+      foo.percent_complete.should == 60
+    end
+
+    it "should evaluate 100 percent when all checkoff items are done" do
+      class Foo
+        include Zitdunyet::Completeness
+        checkoff "Step One", 60.units do true end
+        checkoff "Step Two", 40.units do true end
+      end
+
+      foo = Foo.new
+      foo.percent_complete.should == 100
+    end
+
+    it "should evaluate to fractional percents when required" do
+      class Foo
+        include Zitdunyet::Completeness
+        checkoff "Step One", 1.units do true end
+        checkoff "Step Two", 199.units do false end
+      end
+
+      foo = Foo.new
+      foo.percent_complete.should == 0.5
+    end
+  end
+
+  context "Mix of Percent and Units" do
+
+    it "should evaluate 0 percent when no checkoff items are done" do
+      class Foo
+        include Zitdunyet::Completeness
+        checkoff "Step One", 60.percent do false end
+        checkoff "Step Two", 40.units do false end
+      end
+
+      foo = Foo.new
+      foo.percent_complete.should == 0
+    end
+
+    it "should evaluate intermediate percentage when some checkoff items are done" do
+      class Foo
+        include Zitdunyet::Completeness
+        checkoff "Step One", 60.percent do true end
+        checkoff "Step Two", 40.units do false end
+      end
+
+      foo = Foo.new
+      foo.percent_complete.should == 60
+    end
+
+    it "should evaluate scale the units to fit remaining percentage" do
+      class Foo
+        include Zitdunyet::Completeness
+        checkoff "Step One", 60.units do true end
+        checkoff "Step Two", 40.percent do false end
+      end
+
+      foo = Foo.new
+      foo.percent_complete.should == 60
+    end
+
+    it "should evaluate 100 percent when all checkoff items are done" do
+      class Foo
+        include Zitdunyet::Completeness
+        checkoff "Step One", 60.percent do true end
+        checkoff "Step Two", 40.units do true end
+      end
+
+      foo = Foo.new
+      foo.percent_complete.should == 100
+    end
+
+    it "should evaluate to fractional percents when required" do
+      class Foo
+        include Zitdunyet::Completeness
+        checkoff "Step One", 1.units do true end
+        checkoff "Step Two", 1.units do false end
+        checkoff "Step Three", 99.percent do false end
+      end
+
+      foo = Foo.new
+      foo.percent_complete.should == 0.5
+    end
+  end
+
+  context "Hints" do
+
+    it "should provide a hint and percentage for uncompleted checkoff items" do
+      class Foo
+        include Zitdunyet::Completeness
+        checkoff "Step One", 60.units do false end
+        checkoff "Step Two", 40.units, hint: "Add a widget" do false end
+      end
+
+      foo = Foo.new
+      foo.hints.should have(2).items
+      one = foo.hints.delete("Step One")
+      one.should == 60
+      two = foo.hints.delete("Add a widget")
+      two.should == 40
+    end
+
+    it "should evaluate a hint when it is callable" do
+      class Foo
+        include Zitdunyet::Completeness
+        checkoff "Step One", 60.units, hint: lambda {|s| s.blork} do false end
+        checkoff "Step Two", 40.units, hint: lambda {|s| "Add #{5-s.count} widgets"} do false end
+
+        def blork
+          "Raise the blork coefficient by 30%"
+        end
+
+        def count
+          3
+        end
+      end
+
+      foo = Foo.new
+      foo.hints.should have(2).items
+      puts foo.hints.inspect
+      one = foo.hints.delete("Raise the blork coefficient by 30%")
+      one.should == 60
+      two = foo.hints.delete("Add 2 widgets")
+      two.should == 40
+    end
+
+  end
+
+end

data/spec/lib/zitdunyet/expressions_spec.rb

@@ -0,0 +1,72 @@
+require 'spec_helper'
+
+describe "Expressions" do
+
+  before(:each) do
+    begin
+      Object.send(:remove_const, :Foo)
+    rescue
+    end
+  end
+
+  context "Basics" do
+    it "should accept a minimal expression" do
+      class Foo
+        include Zitdunyet::Completeness
+        checkoff "Step One", 8.percent do true end
+      end
+
+      Foo.checklist.first.label.should == "Step One"
+      Foo.checklist.first.percent.should == 8
+    end
+  end
+
+  context "Percentages" do
+
+    it "should reject percentage exceeding 100" do
+      expect {
+        class Foo
+          include Zitdunyet::Completeness
+          checkoff "Step One", 101.percent do true end
+        end
+      }.to raise_error(RangeError)
+    end
+
+    it "should reject cumulative percentage exceeding 100" do
+      expect {
+        class Foo
+          include Zitdunyet::Completeness
+          checkoff "Step One", 8.percent do true end
+          checkoff "Step Two", 93.percent do true end
+        end
+      }.to raise_error(RangeError)
+    end
+
+    it "should accept percentage exactly 100" do
+      class Foo
+        include Zitdunyet::Completeness
+        checkoff "Step One", 100.percent do true end
+      end
+    end
+
+    it "should accept cumulative percentage exactly 100" do
+      class Foo
+        include Zitdunyet::Completeness
+        checkoff "Step One", 8.percent do true end
+        checkoff "Step Two", 92.percent do true end
+      end
+    end
+  end
+
+  context "Hints" do
+    it "should accept a hint" do
+      class Foo
+        include Zitdunyet::Completeness
+        checkoff "Step One", 8.percent, hint: "Add a widget" do true end
+      end
+
+      Foo.checklist.first.hint.should == "Add a widget"
+    end
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,10 @@
+$TESTING=true
+$:.push File.join(File.dirname(__FILE__), '..', 'lib')
+
+require "zitdunyet"
+#require "factory_girl"
+#require File.join(File.dirname(__FILE__), "support", "models", "base.rb")
+#Dir.glob(File.join(File.dirname(__FILE__), "support", "**", "*.rb")).each {|f| require f}
+#
+## TODO: (dcp) why isn't the file loading automatically?  should load from spec/factories/*.rb by default.
+#Dir.glob(File.join(File.dirname(__FILE__), "factories", "**", "*.rb")).each {|f| require f}

data/zitdunyet.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/zitdunyet/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.name          = "zitdunyet"
+  gem.version       = Zitdunyet::VERSION
+  gem.authors       = ["David Pellegrini"]
+  gem.email         = ["david.pellegrini@spoke.com"]
+  gem.description   = %q{Evaluate how done or complete a process or entity is.}
+  gem.summary       = %q{DSL to describe the steps to completion and evaluation engine to compute done-ness.}
+  gem.homepage      = ""
+
+  gem.rubyforge_project = "zitdunyet"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency "rake"
+  gem.add_development_dependency "rspec"
+  gem.add_development_dependency "factory_girl"
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification 
+name: zitdunyet
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.0.1
+platform: ruby
+authors: 
+- David Pellegrini
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-07-18 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rake
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  prerelease: false
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: factory_girl
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id003
+description: Evaluate how done or complete a process or entity is.
+email: 
+- david.pellegrini@spoke.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/zitdunyet.rb
+- lib/zitdunyet/checkoff.rb
+- lib/zitdunyet/class_specific.rb
+- lib/zitdunyet/completeness.rb
+- lib/zitdunyet/evaluation.rb
+- lib/zitdunyet/expressions.rb
+- lib/zitdunyet/percent.rb
+- lib/zitdunyet/unit.rb
+- lib/zitdunyet/version.rb
+- spec/lib/zitdunyet/checkoff_spec.rb
+- spec/lib/zitdunyet/class_attr_spec.rb
+- spec/lib/zitdunyet/evaluations_spec.rb
+- spec/lib/zitdunyet/expressions_spec.rb
+- spec/spec_helper.rb
+- zitdunyet.gemspec
+homepage: ""
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: -697234430046674194
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: -697234430046674194
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: zitdunyet
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: DSL to describe the steps to completion and evaluation engine to compute done-ness.
+test_files: 
+- spec/lib/zitdunyet/checkoff_spec.rb
+- spec/lib/zitdunyet/class_attr_spec.rb
+- spec/lib/zitdunyet/evaluations_spec.rb
+- spec/lib/zitdunyet/expressions_spec.rb
+- spec/spec_helper.rb