motivation 0.0.1

data/.gitignore

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

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Brendon Murphy
+
+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,76 @@
+# Motivation
+
+Simple DSL for use in classes to motivate a user towards a goal.  An example
+goal might be "Complete Profile", or "Setup Project"
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'motivation'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install motivation
+
+## Usage
+
+```ruby
+require "motivation"
+
+Profile = Struct.new(:twitter_name, :age, :tweets) do
+  attr_accessor :cached_tweets_count
+end
+
+class ProfileMotivation
+  include Motivation
+
+  # Aliases profile to subject for clarity in steps
+  subject :profile
+
+  # Create a simple check.  This defines the predicate `#setup_twitter?`
+  check(:setup_twitter) { profile.twitter_name.to_s.length > 0 }
+
+  # Define a step by name then create a check
+  step :enter_age
+  check { profile.age.to_i > 0 }
+
+  # Define a completetion block.  This is useful if you your
+  # check is heavy and you want to use a cached result.  This
+  # will define a method `#complete_tweets_added
+  step :tweets_added
+  check { cached_tweets_count.to_i > 0 || profile.tweets.length > 0 }
+  complete { profile.cached_tweets_count = profile.tweets.length.to_i }
+end
+
+profile = Profile.new(nil, 42, [1,2,3])
+motivation = ProfileMotivation.new(profile)
+motivation.setup_twitter? #=> false
+profile.twitter_name = "JohnDoe"
+motivation.setup_twitter? #=> true
+
+motivation.complete_tweets_added
+```
+
+Note that the `check` and `complete` blocks will not tolerate early returns, you
+will get a `LocalJumpError`.  If you want to simplify your DSL definitions, you can
+just call methods, including privates, in your ProfileMotivation class itself.
+
+## Acknowledgements
+
+This was heavily inspired by [progression](https://github.com/mguterl/progression).
+
+I switched primarily because I wanted to use specific classes rather than inject into
+an existing model namespace, and extend the DSL some.
+
+## 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,10 @@
+#!/usr/bin/env rake
+
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+desc "Run all examples"
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = %w[--color]
+end
+

data/lib/motivation/version.rb

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

data/lib/motivation.rb

@@ -0,0 +1,170 @@
+require "motivation/version"
+require "delegate"
+
+module Motivation
+
+  def self.included(base)
+    base.send(:attr_accessor, :subject)
+    base.extend ClassMethods
+  end
+
+  def initialize(subject)
+    @subject = subject
+  end
+
+  def applies?
+    true
+  end
+
+  def checks
+    self.class.checks
+  end
+
+  def each_check(&block)
+    wrapped_checks.each &block
+  end
+
+  def wrapped_checks
+    checks.collect { |c| WrappedCheck.new(c, self) }
+  end
+
+  def completions
+    self.class.completions
+  end
+
+  def translation_key
+    self.class.translation_key
+  end
+
+  module ClassMethods
+    def checks
+      @checks ||= []
+    end
+
+    def completions
+      @completions ||= []
+    end
+
+    ##
+    # Returns the underscored name used in the full i18n translation key
+    #
+    # Example:
+    #
+    #  UserProjectMotivation.translation_key # => "user_project"
+    #
+    def translation_key
+      key = name.gsub(/Motivation\z/, '')
+      key.gsub!(/^.*::/, '')
+      key.gsub!(/([A-Z\d]+)([A-Z][a-z])/,'\1_\2')
+      key.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+      key.tr!("-", "_")
+      key.downcase!
+    end
+
+    def subject(attr_name)
+      alias_method attr_name.to_sym, :subject
+    end
+
+    ##
+    # Grant the ability to define if a progression applies.  This
+    # enables creation a progression that might only apply if a project
+    # is less than 30 days old
+    def applies(&block)
+      define_method("applies?") do
+        !! instance_exec(&block)
+      end
+    end
+
+    ##
+    # Define the current step name, used by subsequent
+    # DSL calls
+    def step(name)
+      @current_step_name = name
+    end
+
+    ##
+    # Create a predicate method for the current step name
+    # to test if it's complete
+    def check(name = @current_step_name, &block)
+      raise "No step name" unless name
+      @current_step_name ||= name
+      checks << CheckBlock.new("progression_name", name, &block)
+
+      define_method("#{name}?") do
+        check = checks.find { |s| s.name == name }
+        !! check.run(self)
+      end
+    end
+
+    # Check a method like `complete_current_step_name` to mark
+    # a step complete.  This is not always needed but useful
+    # if you want to persist a completion for performance purposes.
+    def complete(&block)
+      name = @current_step_name or raise "No step name"
+      completions << CompletionBlock.new("progression_name", name, &block)
+
+      define_method("complete_#{name}") do
+        completion = completions.find { |c| c.name == name }
+        completion.run(self)
+      end
+    end
+
+  end
+
+  class StepBlock
+    attr_reader :name
+
+    def initialize(progression_name, name, &block)
+      @progression_name = progression_name
+      @name             = name
+      @block            = block
+    end
+
+    def run(context)
+      context.instance_exec &@block
+    end
+  end
+
+  class CheckBlock < StepBlock; end
+  class CompletionBlock < StepBlock; end
+
+  ##
+  # WrappedCheck is used to wrap a Check with the context
+  # of a motivation instance, so that you can check if
+  # it is completed without passing in the subject instance
+  #
+  class WrappedCheck < DelegateClass(CheckBlock)
+    def initialize(check, motivation)
+      super(check)
+      @check      = check
+      @motivation = motivation
+    end
+
+    def completed?
+      !! @check.run(@motivation)
+    end
+
+    ##
+    # Returns a key for i18n like:
+    #
+    #   'motivations.project.incomplete.step_name'
+    #
+    # or for a completed step
+    #   'motivations.project.complete.signed_up'
+    #
+    def translation_key
+       [
+        "motivations",
+        @motivation.key,
+        status_key,
+        @check.name
+      ].join('.')
+    end
+    private
+
+    def status_key
+      completed? ? "complete" : "incomplete"
+    end
+  end
+
+end

data/motivation.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/motivation/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Brendon Murphy"]
+  gem.email         = ["xternal1+github@gmail.com"]
+  gem.summary       = %q{Simple DSL for use in classes to motivate a user towards a goal}
+  gem.description   = gem.summary
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "motivation"
+  gem.require_paths = ["lib"]
+  gem.version       = Motivation::VERSION
+
+  gem.add_development_dependency "rspec", "~> 2.13.0"
+end

data/spec/motivation_spec.rb

@@ -0,0 +1,171 @@
+require 'motivation'
+require "ostruct"
+
+Project = Struct.new(:name, :subdomain, :users) do
+  attr_accessor :users_count
+end
+
+class ProjectMotivation
+  include Motivation
+
+  attr_accessor :applies, :method_check
+  # Privatize just the getter so we
+  # cam make sure everything is callable
+  private :method_check
+
+  applies { !! applies }
+
+  subject :project
+
+  check(:name_setup) { ! project.name.to_s.empty? }
+
+  step :subdomain_setup
+  check { ! project.subdomain.to_s.empty? }
+
+  check(:local_method_step) { method_check }
+
+  step :users_signed_up
+  check do
+    project.users_count.to_i > 0 || project.users.length > 0
+  end
+  complete {
+    project.users_count = project.users.length
+  }
+end
+
+describe Motivation do
+  let(:project) { Project.new("Spec Project", "spec-subdomain", [stub, stub]) }
+  let(:motivation) { ProjectMotivation.new project }
+
+  it "provides a subject class method for aliasing the subject" do
+    expect(motivation.project).to_not be_nil
+    expect(motivation.project).to eq motivation.subject
+  end
+
+  context "a simple check step" do
+    it "creates a predicate method provided a name and block" do
+      project.name = nil
+      expect(motivation).to_not be_name_setup
+
+      project.name = "Spec Project"
+      expect(motivation).to be_name_setup
+    end
+  end
+
+  context "a step definition followed by a check" do
+    it "creates a predicate method provided a name and block" do
+      project.subdomain = nil
+      expect(motivation).to_not be_subdomain_setup
+
+      project.subdomain = "spec-subdomain"
+      expect(motivation).to be_subdomain_setup
+    end
+  end
+
+  context "a step definition calling progression instance methods" do
+    it "can call the instance method with expected scope" do
+      expect(motivation).to_not be_local_method_step
+      motivation.method_check = true
+      expect(motivation).to be_local_method_step
+    end
+  end
+
+  context "a step definition followed by a check and a completion" do
+    it "creates the completion" do
+      project.users = [stub, stub, stub]
+      motivation.complete_users_signed_up
+      expect(project.users_count).to eq 3
+      expect(motivation).to be_users_signed_up
+    end
+  end
+
+  describe "application checks" do
+    it "are true by default" do
+      klass = Class.new do
+        include Motivation
+      end
+
+      expect(klass.new(stub).applies?).to be_true
+    end
+
+    it "are overridden with the apply dsl" do
+      motivation.applies = nil
+      expect(motivation.applies?).to be_false
+    end
+  end
+
+  describe ".translation_key" do
+    it "project for ProjectMotivation" do
+      expect(ProjectMotivation.translation_key).to eq "project"
+    end
+
+    it "user_project for UserProjectMotivation" do
+      UserProjectMotivation = Class.new do
+        include Motivation
+      end
+      expect(UserProjectMotivation.translation_key).to eq "user_project"
+    end
+
+    it "is accessable via the instance" do
+      expect(motivation.translation_key).to eq "project"
+    end
+  end
+
+  describe "iterating checks" do
+    it "steps through the checks in order" do
+      names = []
+
+      motivation.each_check do |c|
+        names << c.name
+      end
+
+      expect(names).to eq [:name_setup, :subdomain_setup, :local_method_step, :users_signed_up]
+    end
+
+    it "wraps the checks to allow checking if it's completed" do
+      project.name      = "name"
+      project.subdomain = nil
+      results           = []
+
+      motivation.each_check do |c|
+        results << c.completed?
+      end
+
+      expect(results[0]).to be_true
+      expect(results[1]).to be_false
+    end
+  end
+
+end
+
+describe Motivation::WrappedCheck, "#translation_key" do
+  let(:check) { OpenStruct.new }
+  let(:motivation) { stub(:motivation, :key => "project") }
+  let(:wrapped_check) { Motivation::WrappedCheck.new(check, motivation) }
+
+  before do
+    class << check
+      attr_accessor :flag
+
+      def run(*)
+        !! flag
+      end
+    end
+
+    check.name = "foo_bar"
+  end
+
+  context "for a incomplete step" do
+    it "generates a key like motivations.project.incomplete.step_name" do
+      check.flag = false
+      expect(wrapped_check.translation_key).to eq "motivations.project.incomplete.foo_bar"
+    end
+  end
+
+  context "for a completed step" do
+    it "generates a key like motivations.project.complete.step_name" do
+      check.flag = true
+      expect(wrapped_check.translation_key).to eq "motivations.project.complete.foo_bar"
+    end
+  end
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: motivation
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Brendon Murphy
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-03-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &2160517160 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.13.0
+  type: :development
+  prerelease: false
+  version_requirements: *2160517160
+description: Simple DSL for use in classes to motivate a user towards a goal
+email:
+- xternal1+github@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/motivation.rb
+- lib/motivation/version.rb
+- motivation.gemspec
+- spec/motivation_spec.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 3
+summary: Simple DSL for use in classes to motivate a user towards a goal
+test_files:
+- spec/motivation_spec.rb