komando 0.0.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,25 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+doc
+
+## PROJECT::SPECIFIC
+*.rbc
+.bundle
+Gemfile.lock

data/.rvmrc

@@ -0,0 +1 @@
+rvm 1.9.2@komando

data/Gemfile

@@ -0,0 +1,4 @@
+source :gemcutter
+gemspec
+
+# vim: set ft=ruby

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 François Beausoleil
+
+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,147 @@
+Komando
+=======
+
+Commands are used in many applications, especially GUIs. Komando is an implementation of the [Command pattern][1],
+especially suited to Rails applications. Commands are provided the information they need, then told to run. Commands
+can be marked best effort, or mandatory. Commands can refer to other commands, and ask that the sub-commands be
+mandatory or best effort.
+
+Most web applications have a lot of before and after hooks that occur when working with objects: sending a
+welcome email on registration, incrementing or decrementing counter caches, trigger validation on remote web
+services. When implemented using callbacks, all these occur without the developer knowing about them. A
+simple change in one area of the code can have a huge impact somewhere else. Inspiration for this came from
+[Unintented Consequences: The Pitfalls of ActiveRecord Callbacks][2] and
+[Crazy, Heretical, and Awesome: The Way I Write Rails Apps][3].
+
+
+Examples
+--------
+
+    require "komando/command"
+    require "komando/active_record"
+
+    class AdUpdateCommand
+      include Komando::Command
+
+      def initialize(*args)
+        @initiated_at = Time.now.utc
+
+        # If you must override #initialize, NEVER forget to call super
+        super
+
+        # Forgetting to call super will result in NoMethodError and such
+        # being raised from your code.
+      end
+
+      # Lets exceptions through -- nothing is rescued -- callers will have
+      # to handle exceptions themselves. The command's success/failure state
+      # is determined by the fact that no exceptions are raised. The block's
+      # return value is ignored.
+      #
+      # All #mandatory_steps are run within a single database transaction.
+      mandatory_steps do
+        @ad.update_attributes!(@params)
+        @ad.campaign.update_attribute(:active_ad_units_count, @ad.campaign.ad_units.active.count)
+      end
+
+      # The #transaction block can be used to root your transaction differently.
+      # The default #transaction block simply yields - no transactions will be
+      # processed. The komando-active_record gem will root your transactions
+      # against ActiveRecord::Base#transaction.
+      #
+      # This method is important if you have more than one database connection,
+      # where each model might open transactions against different databases.
+      transaction do
+        AdUnit.transaction do
+          yield
+        end
+      end
+    end
+
+    class PlacementEventLoggerCommand
+      include Komando::Command
+
+      mandatory_steps do
+        Event.create!(:event_type => "placement:created", :actor => @actor, :subject => @subject)
+      end
+    end
+
+    class PlacementCreationCommand
+      include Komando::Command
+
+      mandatory_steps do
+        @placement = Placement.create!(@params)
+
+        @placement.campaign.increment!(:active_placements_count, 1)    if @placement.active?
+        @placement.campaign.increment!(:scheduled_placements_count, 1) if @placement.scheduled?
+      end
+
+      # Call #best_effort_step multiple times to declare each individual step
+      # that will be attempted. If a block fails, logging will ensue, and
+      # other blocks will be attempted.
+      #
+      # #best_effort_step can document what it's supposed to do, enabling
+      # better logging. Either pass a String or Symbol, the latter of which will
+      # be #humanized.
+      best_effort_step(:event_generation) do
+
+        # Note the availability of a class-level method named #run, which simply does the obvious
+        # instantiation and call the instance-level #run.
+        PlacementEventLoggerCommand.run(:actor => @placement.created_by, :subject => @placement)
+
+      end
+    end
+
+    # Usage from Rails
+    class AdsController < ApplicationController
+
+      def update
+        @ad = Ad.find(params[:id])
+
+        # Commands accept any number of parameters, as a Hash. Parameters are translated
+        # to instance variables within the Command object itself.
+        command = AdUpdateCommand.new(:ad     => @ad,
+                                      :params => params[:ad])
+        if command.run then
+          flash[:notice] = "Ad updated"
+          redirect_to @ad
+        else
+          flash.new[:error] = "Ad failed to save"
+          render :action => :edit
+        end
+      end
+
+    end
+
+
+Notes on Patches/Pull Requests
+-----------------------------
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+
+Compatibility
+-------------
+
+Komando is known to pass it's specifications on the following Ruby implementations (rvm version specifiers):
+
+* jruby-1.5.6 [ x86_64-java ]
+* ree-1.8.7-2011.01 [ x86_64 ]
+* ruby-1.8.7-p330 [ x86_64 ]
+* ruby-1.9.2-p136 [ x86_64 ]
+
+
+Copyright
+---------
+
+Copyright (c) 2010 François Beausoleil. See LICENSE for details.
+
+  [1]: http://en.wikipedia.org/wiki/Command_pattern
+  [2]: http://blog.teksol.info/2010/09/28/unintented-consequences-the-pitfalls-of-activerecord-callbacks.html
+  [3]: http://jamesgolick.com/2010/3/14/crazy-heretical-and-awesome-the-way-i-write-rails-apps.html

data/Rakefile

@@ -0,0 +1,111 @@
+# coding: utf-8
+
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "komando"
+    gem.summary = %Q{Command-driven framework, especially suited for web applications}
+    gem.description = %Q{Most web applications have a lot of before/after hooks that occur when working with objects: sending a welcome email on registration, incrementing/decrementing counter caches, trigger validation on remote web services. When implemented using callbacks, all these occur without the developer knowing about them. A simple change in one area of the code can have a huge impact somewhere else. Inspiration for this came from http://blog.teksol.info/2010/09/28/unintented-consequences-the-pitfalls-of-activerecord-callbacks.html and http://jamesgolick.com/2010/3/14/crazy-heretical-and-awesome-the-way-i-write-rails-apps.html}
+    gem.email = "francois@teksol.info"
+    gem.homepage = "http://github.com/francois/komando"
+    gem.authors = ["François Beausoleil"]
+
+    # Don't bundle development code with the gem
+    gem.files -= FileList["samples/**/*"]
+
+    gem.add_development_dependency "bacon", ">= 0"
+    gem.add_development_dependency "yard", ">= 0"
+    gem.add_development_dependency "bluecloth", ">= 0"
+    # BlueCloth is "required" by yard, where it is used to format the docs, but is not really a required dependency.
+    # Use 1.9.2 to generate the docs.
+
+    gem.add_development_dependency "activerecord", "~> 2.3.8"
+    gem.add_development_dependency "jeweler", "~> 1.4.0"
+
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |spec|
+    spec.libs << 'spec'
+    spec.pattern = 'spec/**/*_spec.rb'
+    spec.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end
+
+RUBIES = %w(
+  1.9.2@komando
+  1.8.7@komando
+  ree@komando
+  jruby@komando
+)
+
+def rvm(command)
+  sh "rvm #{RUBIES.join(",")} exec #{command}"
+end
+
+namespace :rubies do
+  namespace :bundle do
+    task :install do
+      rvm "gem install bundler"
+      rvm "bundle install"
+    end
+  end
+
+  task :version do
+    rvm "ruby --version"
+  end
+
+  task :spec do
+    rvm "rake spec"
+  end
+
+  task :default do
+    sh "rvm use #{RUBIES.first}"
+  end
+
+  namespace :gemset do
+    task :create do
+      RUBIES.each do |ruby|
+        sh "rvm use #{ruby} && rvm --force gemset create komando"
+      end
+    end
+
+    task :delete do
+      RUBIES.each do |ruby|
+        sh "rvm use #{ruby} && rvm --force gemset delete"
+      end
+    end
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.0

data/komando.gemspec

@@ -0,0 +1,82 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{komando}
+  s.version = "0.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["François Beausoleil"]
+  s.date = %q{2011-03-15}
+  s.description = %q{Most web applications have a lot of before/after hooks that occur when working with objects: sending a welcome email on registration, incrementing/decrementing counter caches, trigger validation on remote web services. When implemented using callbacks, all these occur without the developer knowing about them. A simple change in one area of the code can have a huge impact somewhere else. Inspiration for this came from http://blog.teksol.info/2010/09/28/unintented-consequences-the-pitfalls-of-activerecord-callbacks.html and http://jamesgolick.com/2010/3/14/crazy-heretical-and-awesome-the-way-i-write-rails-apps.html}
+  s.email = %q{francois@teksol.info}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.md"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     ".rvmrc",
+     "Gemfile",
+     "LICENSE",
+     "README.md",
+     "Rakefile",
+     "VERSION",
+     "komando.gemspec",
+     "lib/komando.rb",
+     "lib/komando/command.rb",
+     "lib/komando/command/dsl.rb",
+     "lib/komando/persistence.rb",
+     "lib/komando/persistence/active_record.rb",
+     "lib/komando/version.rb",
+     "samples/rails3/.gitignore",
+     "samples/rails3/.rvmrc",
+     "samples/rails3/lib/tasks/.gitkeep",
+     "samples/rails3/public/stylesheets/.gitkeep",
+     "samples/rails3/vendor/plugins/.gitkeep",
+     "spec/active_record_integration_spec.rb",
+     "spec/command_runner_spec.rb",
+     "spec/dsl_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/francois/komando}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Command-driven framework, especially suited for web applications}
+  s.test_files = [
+    "spec/active_record_integration_spec.rb",
+     "spec/command_runner_spec.rb",
+     "spec/dsl_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<bacon>, [">= 0"])
+      s.add_development_dependency(%q<yard>, [">= 0"])
+      s.add_development_dependency(%q<bluecloth>, [">= 0"])
+      s.add_development_dependency(%q<activerecord>, ["~> 2.3.8"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.4.0"])
+    else
+      s.add_dependency(%q<bacon>, [">= 0"])
+      s.add_dependency(%q<yard>, [">= 0"])
+      s.add_dependency(%q<bluecloth>, [">= 0"])
+      s.add_dependency(%q<activerecord>, ["~> 2.3.8"])
+      s.add_dependency(%q<jeweler>, ["~> 1.4.0"])
+    end
+  else
+    s.add_dependency(%q<bacon>, [">= 0"])
+    s.add_dependency(%q<yard>, [">= 0"])
+    s.add_dependency(%q<bluecloth>, [">= 0"])
+    s.add_dependency(%q<activerecord>, ["~> 2.3.8"])
+    s.add_dependency(%q<jeweler>, ["~> 1.4.0"])
+  end
+end
+

data/lib/komando.rb

@@ -0,0 +1,18 @@
+# The main Komando module. Holder for declarations.
+module Komando
+
+  # Indicates the mandatory steps have not been declared on instances of this class.
+  class MissingMandatoryStepsError < StandardError; end
+
+  autoload :Command, "komando/command"
+
+  def self.make_command(base)
+    base.send :include, Komando::Command
+    base.send :extend, Komando::Command::Dsl
+    if defined?(ActiveRecord) then
+      require "komando/persistence/active_record"
+      base.send :include, Komando::Persistence::ActiveRecord
+    end
+  end
+
+end

data/lib/komando/command.rb

@@ -0,0 +1,76 @@
+module Komando
+  module Command
+
+    autoload :Dsl, "komando/command/dsl"
+
+    # Instantiates and runs this command.
+    #
+    # @param (see #initialize)
+    # @return [true] When the mandatory parts of the command are run to completion.
+    def self.run!(instance_variable_declarations)
+      new.run!(instance_variable_declarations)
+    end
+
+    # @param [Hash] instance_variable_declarations The list of instance variables to declare on this instance.
+    # The instance variables will be available in the blocks, courtesy of Ruby
+    # and it's dynamic nature.
+    def initialize(instance_variable_declarations={})
+      instance_variable_declarations.each do |name, value|
+        instance_variable_set("@#{name}", value)
+      end
+    end
+
+    # Executes the mandatory and best effort steps, in order of definition, raising or
+    # logging and swallowing exceptions as appropriate.
+    #
+    # @return [true] Always returns +true+, since exceptions indicate failure.
+    # @raise [Exception] In case of a failure in the mandatory part of the command.
+    def run!
+      run_mandatory!
+      run_best_effort
+      true
+    end
+
+    # Returns a Logger-like object that will log receive #warn, #info and #debug calls.
+    # The logger can do whatever it wants with those calls.
+    #
+    # @return [#warn, #info, #debug] A Logger-like object that responds to logging commands.
+    #
+    # @example
+    #
+    #   # config/initializers/komando.rb
+    #   require "komando/command"
+    #
+    #   module Komando::Command
+    #     def logger
+    #       Rails.logger
+    #     end
+    #   end
+    def logger
+      @logger ||= Logger.new(STDERR)
+    end
+
+    private
+
+    # Runs and raises
+    def run_mandatory!
+      steps = self.class.mandatory_steps
+      raise Komando::MissingMandatoryStepsError if steps.empty?
+      steps.each do |step|
+        instance_exec(&step)
+      end
+    end
+
+    # Runs and logs
+    def run_best_effort
+      self.class.best_effort_steps.each do |name, block|
+        begin
+          instance_exec &block
+        rescue StandardError => e
+          logger.warn "[Komando] Ignoring failed #{name.inspect} step in #{self.class}: #{e.class.name} - #{e.message}"
+        end
+      end
+    end
+
+  end
+end

data/lib/komando/command/dsl.rb

@@ -0,0 +1,95 @@
+module Komando
+  module Command
+
+    # The Komando DSL. Extend your command classes with this module to start using
+    # Komando in your application.
+    #
+    # It is recommended you do not implement #initialize in your commands. If you do,
+    # you *must* call super or your parameters will not be available as instance variables.
+    #
+    # @example
+    #
+    #   require "komando/command/dsl"
+    #
+    #   class CreateUserCommand
+    #     extend Komando::Command::Dsl
+    #
+    #     # If you must override #initialize, make sure you call super,
+    #     # or your instance variables won't be assigned.
+    #     def initialize(*args)
+    #       super # MUST call, or all hell will break loose
+    #     end
+    #
+    #     mandatory_step "generate records" do
+    #       # TODO
+    #     end
+    #
+    #     mandatory_step "generate audit log" do
+    #       # TODO
+    #     end
+    #
+    #   end
+    module Dsl
+
+      # Returns the list of mandatory steps
+      def mandatory_steps
+        @mandatory_steps ||= []
+      end
+
+      # Declares a set of actions that must run to completion for this command to be deemed successful.
+      # The declared actions may be anything: method calls or direct actions. Parameters are passed from the
+      # environment as instance variables passed to the instance.
+      #
+      # @example
+      #
+      #   class CreateUserCommand
+      #     extend Komando::Command::Dsl
+      #
+      #     mandatory_step do
+      #       # Assuming an ActiveRecord-like User class exists
+      #       User.create!(@attributes)
+      #     end
+      #   end
+      #
+      #   # Run the command with parameters gathered from the environment
+      #   CreateUserCommand.new(:attributes => params[:user]).run!
+      def mandatory_step(name=nil, &block)
+        mandatory_steps << block
+      end
+
+      # Declares a new best effort step - one that will be executed, but will not stop processing.
+      # If the block raises an exception, {Komando::Command#run!} will log and swallow the exception.
+      # Best effort stop blocks have access to the same environment as {#mandatory_step} blocks -
+      # they execute within the same instance. You can pass values from one block to the next by
+      # using instance variables.
+      #
+      # @example
+      #
+      #   class CreateUserCommand
+      #     extend Komando::Command::Dsl
+      #
+      #     mandatory_step do
+      #       @user = User.create!(@attributes)
+      #     end
+      #
+      #     best_effort_step("generate audit log record") do
+      #       AuditLog.append(@user, @created_by)
+      #     end
+      #   end
+      #
+      #   # Run the command with parameters gathered from the environment
+      #   CreateUserCommand.new(:attributes => params[:user], :created_by => current_user).run!
+      def best_effort_step(name=nil, &block)
+        @best_effort_steps ||= Array.new
+        @best_effort_steps << [name, block]
+      end
+
+      # Helper method to access the declared blocks.
+      #
+      # @return [Array] The list of best effort blocks that were collected. This array may be empty.
+      def best_effort_steps
+        @best_effort_steps ||= Array.new
+      end
+    end
+  end
+end

data/lib/komando/persistence.rb

@@ -0,0 +1,6 @@
+module Komando
+  # Persistence helpers that wrap {Komando::Command} executions within
+  # transactions, or other mechanisms that ease use with persistence.
+  module Persistence
+  end
+end

data/lib/komando/persistence/active_record.rb

@@ -0,0 +1,65 @@
+require "komando"
+require "active_record"
+
+module Komando
+  module Persistence
+    # Wraps command executions within a database transaction.
+    module ActiveRecord
+
+      # Insinuates this module within {Komando::Command}.
+      #
+      # @private
+      def self.included(base)
+        base.send :alias_method_chain, :run!, :transaction
+      end
+
+      # Wraps a command execution within a database transactions.
+      # This method delegates actual transaction semantics to {#wrap_transaction}.
+      # This method is renamed as {Komando::Command##run!} during inclusion.
+      def run_with_transaction!
+        wrap_transaction do
+          run_without_transaction!
+        end
+      end
+
+      # Does the actual work of wrapping in a transaction. The default is to wrap
+      # using {ActiveRecord::Base#transaction}.
+      #
+      # @example Wrapping using a specific connection
+      #   # config/database.yml
+      #   development:
+      #     adapter: sqlite3
+      #     database: db/development.sqlite3
+      #
+      #   require "komando/persistence/active_record"
+      #
+      #   class User < ActiveRecord::Base
+      #     establish_connection :adapter => "sqlite3", :database => "/var/dbs/users.sqlite3"
+      #   end
+      #
+      #   class CreateUserCommand
+      #     include Komando::Command
+      #     include Komando::Persistence::ActiveRecord
+      #
+      #     def wrap_transaction
+      #       User.transaction do
+      #         yield
+      #       end
+      #     end
+      #   end
+      #
+      # @yieldreturn The block's last value.
+      def wrap_transaction
+        ::ActiveRecord::Base.transaction do
+          yield
+        end
+      end
+
+      # Uses the same Logger instance as ActiveRecord.
+      def logger
+        ::ActiveRecord::Base.logger
+      end
+
+    end
+  end
+end

data/lib/komando/version.rb

@@ -0,0 +1,13 @@
+module Komando
+  module Version
+
+    MAJOR = "0"
+    MINOR = "0"
+    PATCH = "0"
+
+    def self.to_s
+      [MAJOR, MINOR, PATCH].join(".")
+    end
+
+  end
+end

data/samples/rails3/.gitignore

@@ -0,0 +1,4 @@
+.bundle
+db/*.sqlite3
+log/*.log
+tmp/**/*

data/samples/rails3/.rvmrc

@@ -0,0 +1 @@
+rvm 1.9.2@komando-rails3

data/spec/active_record_integration_spec.rb

@@ -0,0 +1,35 @@
+require "spec_helper"
+require "komando/persistence/active_record"
+
+describe "An active-record enabled command" do
+
+  before do
+    ActiveRecord::Base.establish_connection :adapter => adapter_name, :database => ":memory:"
+  end
+
+  def adapter_name
+    return "jdbcsqlite3" if defined?(JRUBY_VERSION)
+    return "sqlite3"
+  end
+
+  before do
+    @command = Class.new do
+      extend Komando::Command::Dsl
+      include Komando::Command
+      include Komando::Persistence::ActiveRecord
+
+      attr_reader :open_transactions
+
+      mandatory_step do
+        @open_transactions = ActiveRecord::Base.connection.open_transactions
+      end
+    end
+  end
+
+  should "wrap the mandatory_steps within an ActiveRecord transaction" do
+    command = @command.new
+    command.run!
+    command.open_transactions.should == 1
+  end
+
+end

data/spec/command_runner_spec.rb

@@ -0,0 +1,242 @@
+require "spec_helper"
+
+describe "A command with a mandatory step" do
+
+  before do
+    @command = Class.new do
+      extend Komando::Command::Dsl
+      include Komando::Command
+
+      attr_reader :ran
+
+      mandatory_step do
+        @ran = true
+      end
+    end
+  end
+
+  should "run the mandatory steps" do
+    command = @command.new
+    command.run!
+
+    command.ran.should == true
+  end
+
+end
+
+describe "A command with a failing mandatory step" do
+
+  before do
+    @command = Class.new do
+      extend Komando::Command::Dsl
+      include Komando::Command
+
+      attr_reader :ran, :log
+
+      mandatory_step do
+        raise "failure to run"
+      end
+
+      best_effort_step do
+        @log ||= []
+        @log << 1
+      end
+    end
+  end
+
+  should "let the exception bubble through" do
+    lambda do
+      @command.new.run!
+    end.should.raise(RuntimeError)
+  end
+
+  should "NOT run best effort blocks" do
+    command = @command.new
+    begin
+      command.run!
+    rescue StandardError => ignored
+      # NOP
+    end
+
+    command.log.should.be.nil?
+  end
+
+end
+
+describe "A command with no step declarations" do
+
+  before do
+    @command = Class.new do
+      extend Komando::Command::Dsl
+      include Komando::Command
+    end
+  end
+
+  should "raise an exception when running" do
+    lambda { @command.new.run! }.should.raise(Komando::MissingMandatoryStepsError)
+  end
+
+end
+
+describe "A command with a best effort step" do
+
+  before do
+    @command = Class.new do
+      extend Komando::Command::Dsl
+      include Komando::Command
+
+      attr_reader :ran
+
+      mandatory_step do
+        # NOP
+      end
+
+      best_effort_step(:always_succeeds) do
+        @ran = true
+      end
+    end
+  end
+
+  should "run the best effort step" do
+    command = @command.new
+    command.run!
+    command.ran.should == true
+  end
+
+end
+
+describe "A command with two mandatory steps" do
+
+  before do
+    @command = Class.new do
+      extend Komando::Command::Dsl
+      include Komando::Command
+
+      attr_accessor :raise_in_first, :raise_in_second
+      attr_reader :log
+
+      def initialize(*args)
+        @log = []
+        super
+      end
+
+      mandatory_step do
+        raise "asked to raise" if raise_in_first
+        log << 1
+      end
+
+      mandatory_step do
+        raise "asked to raise" if raise_in_second
+        log << 2
+      end
+    end
+  end
+
+  should "run both blocks in order" do
+    command = @command.new
+    command.run!
+
+    command.log.should == [1, 2]
+  end
+
+  should "NOT run the 2nd block when the 1st one raises" do
+    command = @command.new
+    command.raise_in_first = true
+
+    lambda do
+      command.run!
+    end.should.raise
+
+    command.log.should == []
+  end
+
+end
+
+describe "A command with two best effort steps" do
+
+  before do
+    @command = Class.new do
+      extend Komando::Command::Dsl
+      include Komando::Command
+
+      attr_reader :log
+
+      mandatory_step do
+        # NOP
+      end
+
+      best_effort_step(:first) do
+        @log ||= []
+        @log << 1
+      end
+
+      best_effort_step(:second) do
+        @log ||= []
+        @log << 2
+      end
+    end
+  end
+
+  should "run both blocks, in order" do
+    command = @command.new
+    command.run!
+    command.log.should == [1, 2]
+  end
+
+end
+
+describe "A command with two best effort steps, where the 1st will fail" do
+
+  after do
+    $OK = false
+  end
+
+  before do
+    @command = Class.new do
+      extend Komando::Command::Dsl
+      include Komando::Command
+
+      attr_reader :log
+
+      mandatory_step do
+        # NOP
+      end
+
+      best_effort_step(:first) do
+        raise "failure to run"
+      end
+
+      best_effort_step(:second) do
+        @log ||= []
+        @log << 2
+      end
+
+      def logger
+        @logger ||= Class.new do
+          attr_reader :messages
+
+          def warn(message)
+            @messages ||= []
+            @messages << message
+          end
+        end.new
+      end
+    end
+  end
+
+  should "run both blocks, in order, and not return errors" do
+    command = @command.new
+    command.run!
+    command.log.should == [2]
+  end
+
+  should "log errors using #logger" do
+    command = @command.new
+    command.run!
+    messages = command.logger.messages
+
+    messages.length.should == 1
+    messages.first.should.match /ignoring failed.*first.*RuntimeError.*failure to run/im
+  end
+
+end

data/spec/dsl_spec.rb

@@ -0,0 +1,44 @@
+require "spec_helper"
+
+describe "A command with no step declarations" do
+
+  before do
+    @command = Class.new do
+      extend Komando::Command::Dsl
+    end
+  end
+
+  should "have no mandatory step blocks" do
+    @command.mandatory_steps.should == []
+  end
+
+  should "have no best effort blocks" do
+    @command.best_effort_steps.should == []
+  end
+end
+
+describe "A command with one mandatory step block and no best effort blocks" do
+
+  before do
+    @command = Class.new do
+      extend Komando::Command::Dsl
+
+      mandatory_step do
+      end
+    end
+  end
+
+  should "have a mandatory step block" do
+    @command.mandatory_steps.should.not.be.nil?
+  end
+
+  should "allow declaring a second mandatory step" do
+    lambda do
+      @command.class_eval do
+        mandatory_step do
+        end
+      end
+    end.should.not.raise
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,15 @@
+require 'rubygems'
+require 'bacon'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'komando'
+require "komando/command"
+require "komando/command/dsl"
+
+print "\n\n#{RUBY_PLATFORM} -- #{RUBY_VERSION} -- #{RUBY_RELEASE_DATE}"
+print "-- JRuby Detected" if Object.const_defined?("JRUBY_VERSION")
+print "\n\n"
+
+Bacon.summary_on_exit

metadata

@@ -0,0 +1,159 @@
+--- !ruby/object:Gem::Specification 
+name: komando
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 0
+  version: 0.0.0
+platform: ruby
+authors: 
+- "Fran\xC3\xA7ois Beausoleil"
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-03-15 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: bacon
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: bluecloth
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 3
+        - 8
+        version: 2.3.8
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: jeweler
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 4
+        - 0
+        version: 1.4.0
+  type: :development
+  version_requirements: *id005
+description: "Most web applications have a lot of before/after hooks that occur when working with objects: sending a welcome email on registration, incrementing/decrementing counter caches, trigger validation on remote web services. When implemented using callbacks, all these occur without the developer knowing about them. A simple change in one area of the code can have a huge impact somewhere else. Inspiration for this came from http://blog.teksol.info/2010/09/28/unintented-consequences-the-pitfalls-of-activerecord-callbacks.html and http://jamesgolick.com/2010/3/14/crazy-heretical-and-awesome-the-way-i-write-rails-apps.html"
+email: francois@teksol.info
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.md
+files: 
+- .document
+- .gitignore
+- .rvmrc
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- VERSION
+- komando.gemspec
+- lib/komando.rb
+- lib/komando/command.rb
+- lib/komando/command/dsl.rb
+- lib/komando/persistence.rb
+- lib/komando/persistence/active_record.rb
+- lib/komando/version.rb
+- samples/rails3/.gitignore
+- samples/rails3/.rvmrc
+- samples/rails3/lib/tasks/.gitkeep
+- samples/rails3/public/stylesheets/.gitkeep
+- samples/rails3/vendor/plugins/.gitkeep
+- spec/active_record_integration_spec.rb
+- spec/command_runner_spec.rb
+- spec/dsl_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/francois/komando
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Command-driven framework, especially suited for web applications
+test_files: 
+- spec/active_record_integration_spec.rb
+- spec/command_runner_spec.rb
+- spec/dsl_spec.rb
+- spec/spec_helper.rb