imperator 0.1.0

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.idea/*

data/Gemfile

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

data/README.md

@@ -0,0 +1,72 @@
+#Imperator
+Imperator is a small gem to help with command objects. The [command pattern](http://c2.com/cgi/wiki?CommandPattern) is a design pattern used to encapsulate all of the information needed to execute a method or process at a point in time. In a web application, commands are typically used to delay execution of a method from the request cycle to a background processor.
+
+###Why use commands?
+The problem with controllers in Rails is that they're a part of the web domain—their job is to respond to requests, and ONLY to respond to requests. Anything that happens between the receipt of a request and sending a response is Somebody Else's Job™. Commands are that Somebody Else™. Commands are also very commonly utilized to put work into the background. 
+
+Why are commands an appropriate place to handle that logic? Commands give you the opportunity to encapsulate all of the logic required for an interaction in one spot. Sometimes that interaction is as simple as a method call—more often there are several method calls involved, not all of which deal with domain logic (and thus, are inappropriate for inclusion on the models). Commands give you a place to bring all of these together in one spot without increasing coupling in your controllers or models.
+
+Commands can also be regarded as the contexts from DCI.
+
+###Validation 
+Commands also give you an appropriate place to handle interaction validation. Validation is most often regarded as a responsibility of the data model. This is a poor fit, because the idea of what's valid for data is very temporally tied to the understanding of the business domain at the time the data was created. Data that's valid today may well be invalid tomorrow, and when that happens you're going to run into a situation where your ActiveRecord models will refuse to work with old data that is no longer valid. Commands don't absolve you of the need to migrate your data when business requirements change, but they do let you move validation to the interaction where it belongs.
+
+`Imperator::Command`'s are ActiveModel objects, which gives you a lot of flexibility both in and out of Rails projects. Validations are included, as is serialization support. Imperator intends to support all major queueing systems in the Rails ecosystem out of the box, including DelayedJob and Resque. The standard validations for ActiveModel are included, though not the ones that ActiveRecord provides such as `#validates_uniqueness_of`.
+
+Commands can also be used on forms in place of ActiveRecord models. 
+
+###TODO
+* test coverage—Imperator was extracted out of some other work, and coverage was a part of those test suites.
+* Ensure compatibility with DJ, Resque and Sidekiq
+
+#Using Imperator
+
+##Requirements:
+* ActiveSupport 3.0 or higher
+* ActiveAttr
+
+##Installation
+ In your Gemfile:
+
+    gem 'imperator'
+
+##Usage
+
+###Creating the command:
+
+    class DoSomethingCommand < Imperator::Command
+      attribute :some_object_id
+      attribute :some_value
+
+      validates_presence_of :some_object_id
+
+      action do
+        obj = SomeObject.find(self.some_object_id)
+        obj.do_something(self.some_value)
+        end
+      end
+    end
+
+###Using a command on a form builder
+    <%= form_for(@command, :as => :do_something, :url => some_resource_path(@command.some_object_id), :method => :put) do |f| %>
+    ...
+    <% end %>
+
+###Using a command
+    class SomeController < ApplicationController
+      def update
+        command = DoSomethingCommand.new(params[:do_something])
+        if command.valid?
+          command.perform
+          redirect_to root_url
+        else
+          render edit_some_resource_path(command.some_object_id)
+        end
+      end
+    end
+
+###Using a command in the background (Delayed::Job)
+    Delayed::Job.enqueue command
+
+
+		  

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/imperator.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "imperator/version"
+
+Gem::Specification.new do |s|
+  s.name        = "imperator"
+  s.version     = Imperator::VERSION
+  s.authors     = ["Keith Gaddis"]
+  s.email       = ["keith.gaddis@gmail.com"]
+  s.homepage    = "http://github.com/karmajunkie/imperator"
+  s.summary     = %q{Imperator supports the command pattern}
+  s.description = %q{Imperator is a small gem to help with command objects. The command pattern is a design pattern used to encapsulate all of the information needed to execute a method or process at a point in time. In a web application, commands are typically used to delay execution of a method from the request cycle to a background processor.}
+
+  #s.rubyforge_project = "imperator"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # specify any dependencies here; for example:
+  s.add_development_dependency "rspec"
+  s.add_development_dependency "pry"
+  # s.add_runtime_dependency "rest-client"
+  s.add_runtime_dependency "uuidtools"
+  s.add_runtime_dependency "active_attr"
+end

data/lib/imperator.rb

@@ -0,0 +1,9 @@
+require 'active_attr'
+require "imperator/version"
+require 'imperator/invalid_command_error'
+require 'imperator/command'
+require 'pry'
+
+module Imperator
+  # Your code goes here...
+end

data/lib/imperator/command.rb

@@ -0,0 +1,86 @@
+require 'uuidtools'
+class Imperator::Command
+  include ActiveAttr::Model
+  extend ActiveModel::Callbacks
+
+  define_model_callbacks :create, :perform, :initialize
+
+  cattr_accessor :commit_mode
+  attribute :id
+
+  after_initialize :set_uuid
+
+  class << self
+    attr_accessor :perform_block
+  end
+
+  def self.action(&block)
+    @perform_block = block
+  end
+
+  alias_method :params, :attributes
+
+  def as_json
+    attributes.as_json
+  end
+
+  def persisted?
+    false
+  end
+
+  def commit!
+    raise Imperator::InvalidCommandError.new "Command was invalid" unless valid?
+    self.commit
+  end
+
+  def commit
+    #TODO: background code for this
+    self.perform
+  end
+
+  def initialize(*)
+    run_callbacks :initialize do
+      super
+    end
+  end
+
+  def dump
+    attributes.to_json
+  end
+
+  def self.load(command_string)
+    self.new(JSON.parse(command_string))
+  end
+
+  def load(command_string)
+    self.attributes = HashWithIndifferentAccess.new(JSON.parse(command_string))
+  end
+
+  def perform!
+    raise InvalidCommandError.new "Command was invalid" unless valid?
+    self.perform
+  end
+
+  def perform
+    raise "You need to define the perform block for #{self.class.name}" unless self.class.perform_block
+    run_callbacks :perform do 
+      self.instance_exec(&self.class.perform_block)
+    end
+  end
+
+  def method_missing(method, *args)
+    method_root = method.to_s.gsub(/=$/, "")
+    if method.to_s[/=$/]
+      self.attributes[method_root] = args.first
+    elsif attributes.has_key?(method_root)
+      self.attributes[method]
+    else
+      super
+    end
+  end
+
+  private 
+  def set_uuid
+    self.id = UUIDTools::UUID.timestamp_create.to_s if self.id.nil?
+  end
+end

data/lib/imperator/invalid_command_error.rb

@@ -0,0 +1,3 @@
+class Imperator::InvalidCommandError < ArgumentError
+
+end

data/lib/imperator/version.rb

@@ -0,0 +1,3 @@
+module Imperator 
+  VERSION = "0.1.0"
+end

data/spec/imperator/command_spec.rb

@@ -0,0 +1,45 @@
+require 'imperator'
+describe Imperator::Command do
+
+  describe "#perform" do
+    class CommandTestException < Exception; end
+    class TestCommand < Imperator::Command
+      action do
+        raise CommandTestException.new 
+      end
+    end
+
+    let(:command){TestCommand.new}
+    it "runs the action block when #perform is called" do
+      lambda{command.perform}.should raise_exception(CommandTestException)
+    end
+  end
+
+  describe "attributes" do
+    class AttributeCommand < Imperator::Command
+      attribute :gets_default, :default => "foo"
+      attribute :declared_attr
+    end
+
+    it "throws away undeclared attributes in mass assignment" do
+      command = AttributeCommand.new(:undeclared_attr => "foo")
+      lambda{command.undeclared_attr}.should raise_exception(NoMethodError)
+    end
+
+    it "accepts declared attributes in mass assignment" do
+      command = AttributeCommand.new(:declared_attr => "bar")
+      command.declared_attr.should == "bar"
+    end
+
+    it "allows default values to be used on commands" do
+      command = AttributeCommand.new
+      command.gets_default.should == "foo"
+    end
+    it "overrides default when supplied in constructor args" do
+      command = AttributeCommand.new :gets_default => "bar"
+      command.gets_default.should == "bar"
+    end
+  end
+
+end
+

metadata

@@ -0,0 +1,123 @@
+--- !ruby/object:Gem::Specification
+name: imperator
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Keith Gaddis
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-05-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: uuidtools
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: active_attr
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Imperator is a small gem to help with command objects. The command pattern
+  is a design pattern used to encapsulate all of the information needed to execute
+  a method or process at a point in time. In a web application, commands are typically
+  used to delay execution of a method from the request cycle to a background processor.
+email:
+- keith.gaddis@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- imperator.gemspec
+- lib/imperator.rb
+- lib/imperator/command.rb
+- lib/imperator/invalid_command_error.rb
+- lib/imperator/version.rb
+- spec/imperator/command_spec.rb
+homepage: http://github.com/karmajunkie/imperator
+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.24
+signing_key: 
+specification_version: 3
+summary: Imperator supports the command pattern
+test_files:
+- spec/imperator/command_spec.rb