stack_commander 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ae92cb3f3a8d18e64d2db4c240119b96e1062e80
+  data.tar.gz: d5294e75db6fb3afb27f1d56db44270c38be8840
+SHA512:
+  metadata.gz: cccf36d9c8c16c035f3f43aef5d88daf0cb75bd6d0f95a58fd4f0dd3d3817f10fd1b23199f11dba4b8b4163c0b5a0a9475f282fd66dc0a47c8ed8a77d7e5cee5
+  data.tar.gz: d93ec0f9f0f91166cac8099d6362ec66bf6d6b32e08a5065df8e8213a18ec9f7b03e900457499bbac34e3e148ca2056fc65a1ea9b91e6ceb8de2fd0ca43d5f89

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.yardopts

@@ -0,0 +1,2 @@
+--markup-provider=redcarpet
+--markup=markdown

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in stack_commander.gemspec
+gemspec
+
+gem 'yard'
+gem 'redcarpet'
+gem 'github-markup'

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Michal Cichra
+
+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,110 @@
+# StackCommander
+
+StackCommander takes fresh approach to Command Pattern in Ruby.
+We needed chaining of Commands with benefits of `rescue` and `ensure` which was hard to do without execution stack.
+
+Our use case is mainly to provide rollbacks and finalize blocks for each action so system is not left in unknown state.
+
+When doing prototypes one thing came up: how to share state between commands?
+
+We tried: passing state to the `action` method, passing state to the `initialize` and leaving user to instantiate commands by hand. Unfortunately each one of them had drawbacks and we decided to focus on following behaviour:
+
+* `initialize` is called just before the execution
+  * to prevent mistakes of calling something in initializer that might not be there yet
+  * or worse, it would be evaluated not on the stack, but before
+* `initialize` is called by the stack with explicit parameters instead of whole state object
+  * for easier testing
+  * and not to break Law of Demeter
+* command's `action`, `rescue` and `insurance` are called without state parameter
+* command has internal variable `@scope`
+
+It is not final, so constructive feedback is very much appreciated.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'stack_commander'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install stack_commander
+
+## Usage
+
+```ruby
+require 'stack_commander'
+
+class StackState
+  attr_accessor :other
+
+  def dependency
+    'gotten from somewhere'
+  end
+end
+
+class MyCommand
+  include StackCommander::Command
+
+  def initialize(dependency)
+    @dependency = dependency
+    @scope.other = 'yes, other'
+  end
+
+  def action
+    puts @dependency
+  end
+
+  def insurance
+    puts 'command insurance'
+  end
+end
+
+class MyOtherCommand
+  include StackCommander::Command
+
+
+  def initialize(other)
+    @other = other
+  end
+
+  def action
+    puts @other
+  end
+
+  def insurance
+    puts 'other command insurance'
+  end
+
+  def recover(ex)
+    puts 'recovering exception: ' + ex.to_s
+  end
+end
+
+scope = StackState.new
+stack = StackCommander::Stack.new(scope)
+stack << MyCommand
+stack << MyOtherCommand
+stack.call
+```
+
+outputs:
+
+```
+gotten from somewhere
+yes, other
+other command insurance
+command insurance
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/mikz/stack_commander/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler/gem_tasks'
+

data/lib/stack_commander.rb

@@ -0,0 +1,8 @@
+require 'stack_commander/version'
+
+module StackCommander
+  autoload :Stack, 'stack_commander/stack'
+  autoload :Command, 'stack_commander/command'
+  autoload :BaseCommand, 'stack_commander/base_command'
+  autoload :DependencyInjection, 'stack_commander/dependency_injection'
+end

data/lib/stack_commander/base_command.rb

@@ -0,0 +1,7 @@
+require 'stack_commander'
+
+module StackCommander
+  class BaseCommand
+    include StackCommander::Command
+  end
+end

data/lib/stack_commander/command.rb

@@ -0,0 +1,22 @@
+module StackCommander
+  module Command
+    def call(stack)
+      action
+      stack.call
+    rescue => exception
+      recover(exception)
+      raise
+    ensure
+      insurance
+    end
+
+    def action
+    end
+
+    def recover(exception)
+    end
+
+    def insurance
+    end
+  end
+end

data/lib/stack_commander/dependency_injection.rb

@@ -0,0 +1,32 @@
+module StackCommander
+  class DependencyInjection
+    InvalidScope = Class.new(StandardError)
+
+    def initialize(klass)
+      @klass = klass
+    end
+
+    def initialize_parameters
+      @klass.instance_method(:initialize).parameters
+    end
+
+    def required_parameters
+      _, parameters = initialize_parameters.transpose
+      Array(parameters)
+    end
+
+    def matches?(scope)
+      required_parameters.all? do |param|
+        scope.respond_to?(param)
+      end
+    end
+
+    def extract(scope)
+      raise InvalidScope, scope unless matches?(scope)
+
+      required_parameters.map do |param|
+        scope.public_send(param)
+      end
+    end
+  end
+end

data/lib/stack_commander/stack.rb

@@ -0,0 +1,40 @@
+require 'thread'
+
+module StackCommander
+  class Stack
+    def initialize(scope)
+      @queue = Queue.new
+      @scope = scope
+    end
+
+    def size
+      @queue.length
+    end
+
+    def <<(command)
+      @queue.push(command)
+
+      self # for chaining awesomeness << cmd << cmd2 << cmd3
+    end
+
+    def call
+      return if @queue.empty?
+      command_class = @queue.pop
+
+      run_command(command_class)
+    end
+
+    private
+
+    def run_command(klass)
+      parameters = StackCommander::DependencyInjection.new(klass).extract(@scope)
+
+      command = klass.allocate
+      command.instance_variable_set :@scope, @scope
+      command.__send__(:initialize, *parameters)
+
+      command.call(self)
+    end
+  end
+end
+

data/lib/stack_commander/version.rb

@@ -0,0 +1,3 @@
+module StackCommander
+  VERSION = '0.0.1'
+end

data/spec/base_command_spec.rb

@@ -0,0 +1,8 @@
+require 'spec_helper'
+require 'stack_commander/base_command'
+
+describe StackCommander::BaseCommand do
+  it 'has command module' do
+    expect(subject.class.ancestors).to include(StackCommander::Command)
+  end
+end

data/spec/command_spec.rb

@@ -0,0 +1,56 @@
+require 'spec_helper'
+require 'stack_commander/command'
+
+describe StackCommander::Command do
+  expect_it { to be_a(Module) }
+
+  expect_it { to_not be_a(Class) }
+
+  context 'object including command' do
+    subject(:command) { Class.new{ include StackCommander::Command }.new }
+
+    expect_it { to respond_to(:action) }
+    expect_it { to respond_to(:insurance) }
+    expect_it { to respond_to(:recover).with(1).argument }
+
+
+    let(:stack) { double('stack').as_null_object }
+
+    it 'calls action' do
+      expect(subject).to receive(:action)
+      subject.call(stack)
+    end
+
+    it 'calls stack' do
+      expect(stack).to receive(:call)
+      subject.call(stack)
+    end
+
+    it 'calls insurance' do
+      expect(subject).to receive(:insurance)
+      subject.call(stack)
+    end
+
+    it 'does not call recover' do
+      expect(subject).not_to receive(:recover)
+      subject.call(stack)
+    end
+
+    context 'exception is raised' do
+
+      before do
+        expect(stack).to receive(:call).and_raise(StandardError)
+      end
+
+      it 'still calls insurance' do
+        expect(subject).to receive(:insurance)
+        expect { subject.call(stack) }.to raise_error(StandardError)
+      end
+
+      it 'calls recover' do
+        expect(subject).to receive(:recover).with(an_instance_of(StandardError))
+        expect{ subject.call(stack) }.to raise_error(StandardError)
+      end
+    end
+  end
+end

data/spec/dependency_injection_spec.rb

@@ -0,0 +1,36 @@
+require 'spec_helper'
+require 'stack_commander/dependency_injection'
+
+describe StackCommander::DependencyInjection do
+
+  let(:custom_class) { Class.new { def initialize(one, two); end } }
+  subject(:di) { StackCommander::DependencyInjection.new(custom_class) }
+
+  it 'extracts parameter names from initializer' do
+    expect(di.required_parameters).to eq([:one, :two])
+  end
+
+  context 'scope has required methods' do
+    let(:scope) { double('scope', one: 'one value', two: 'two') }
+
+    it do
+      expect(di.matches?(scope)).to be
+    end
+
+    it do
+      expect(di.extract(scope)).to eq(['one value', 'two'])
+    end
+  end
+
+  context 'scope does not have requried methods' do
+    let(:scope) { double('scope', one: true) }
+
+    it do
+      expect(di.matches?(scope)).not_to be
+    end
+
+    it do
+      expect{ di.extract(scope) }.to raise_error(StackCommander::DependencyInjection::InvalidScope)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,24 @@
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# Require this file using `require "spec_helper"` to ensure that it is only
+# loaded once.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+
+  config.alias_example_to :expect_it
+end
+
+RSpec::Core::MemoizedHelpers.module_eval do
+  alias to should
+  alias to_not should_not
+end

data/spec/stack_spec.rb

@@ -0,0 +1,42 @@
+require 'spec_helper'
+require 'stack_commander/stack'
+
+describe StackCommander::Stack do
+
+  let(:scope) { double('scope') }
+  subject(:stack) { StackCommander::Stack.new(scope) }
+
+  it 'requires scope' do
+    expect { StackCommander::Stack.new }.to raise_error(ArgumentError)
+  end
+
+  it 'enqueues commands' do
+    expect(stack.size).to eq(0)
+    stack << double('command')
+    expect(stack.size).to eq(1)
+  end
+
+  context 'without commands' do
+    it 'runs' do
+      stack.call
+    end
+  end
+
+  context 'with commands' do
+    let(:command) { double('command').as_null_object }
+
+    before do
+      stack << command
+    end
+
+    it 'runs the commands' do
+      expect(command).to receive(:call).with(stack)
+      stack.call
+    end
+
+    it 'initializes the command' do
+      expect(command).to receive(:new).with
+      stack.call
+    end
+  end
+end

data/stack_commander.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'stack_commander/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'stack_commander'
+  spec.version       = StackCommander::VERSION
+  spec.authors       = ['Michal Cichra']
+  spec.email         = %w[michal@3scale.net]
+  spec.summary       = %q{Mix between command pattern and stack execution}
+  spec.description   = %q{Write simple commands that execute on stack}
+  spec.homepage      = ''
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.6'
+  spec.add_development_dependency 'rake'
+
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'yard'
+end

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification
+name: stack_commander
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Michal Cichra
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-05-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Write simple commands that execute on stack
+email:
+- michal@3scale.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .yardopts
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/stack_commander.rb
+- lib/stack_commander/base_command.rb
+- lib/stack_commander/command.rb
+- lib/stack_commander/dependency_injection.rb
+- lib/stack_commander/stack.rb
+- lib/stack_commander/version.rb
+- spec/base_command_spec.rb
+- spec/command_spec.rb
+- spec/dependency_injection_spec.rb
+- spec/spec_helper.rb
+- spec/stack_spec.rb
+- stack_commander.gemspec
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Mix between command pattern and stack execution
+test_files:
+- spec/base_command_spec.rb
+- spec/command_spec.rb
+- spec/dependency_injection_spec.rb
+- spec/spec_helper.rb
+- spec/stack_spec.rb
+has_rdoc: