czar 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 471ebb54150c95923d569f6ce7d32072a17974e8
+  data.tar.gz: 4cf441e9b83e54c5cd5f558fa03018481f6f67a5
+SHA512:
+  metadata.gz: 0362a5ee711c89fa76765e2585ada348990f7d9fa8ce30c5d478e20a4693153c8867d7cf72e0ee4df807ac686bc68feb6c213fcb1b3ba2d2a9d34439829c7893
+  data.tar.gz: fc23abaa9a1d2af589d2ab0515b43fd8a403b3cfb510ab9c00839752385ee38fd6d7187fb34793792b41123613e77613ff55514da08a1b6408964beddeca9416

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.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 czar.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Rahoul Baruah
+
+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,119 @@
+# Czar
+
+Czar is a framework for building applications around the Command
+pattern.  
+
+Everything your application does is a Command of some kind; those
+commands may be simple actions, sequences of actions, sequences with
+decisions within them or series that trigger other commands.  
+
+The advantage of using commands within, for example, a Rails application
+is that you can then make your database model classes *passive* - that
+is they become purely data - and the interesting stuff is all handled by
+commands.  No more fat models with callbacks all over the place.  
+
+Plus using commands makes it easy to ensure that authorisation is done
+correctly (as each command is well-defined) and makes it trivial to add
+in logging and so on.  
+
+Czar can allow commands to be persisted (with a in-memory and a Redis adapter for now).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'czar'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install czar
+
+## Usage
+
+The Command module represents an implementation of the Command pattern
+where each Command has an internal state machine and can optionally spawn child commands.
+At its simplest, a Command will be executed, moving it from "start" state to "complete" state. 
+For example:
+```
+class SimpleCommand
+  include Czar::Command
+
+  def start
+   result = some_complex_calculation
+   mark_as :complete, result: result
+  end
+
+  def some_complex_calculation
+   return :whatever
+  end
+end
+```
+
+To use this, simply call SimpleCommand.new.execute - the command will perform #some_complex_calculation and then be marked as :complete
+
+By itself, this is pretty boring.  However, as we've got a simple state machine in there, we can do more interesting stuff; especially when a command is persistent.
+
+For example:
+
+class DrivesACar
+  include Czar::Command
+
+  def start
+    mark_as :moving
+  end
+
+  def moving
+    move_forward
+    if has_reached_destination?
+      mark_as :complete
+    elsif traffic_light.colour == :green
+      mark_as :driving
+    else 
+      mark_as :stopped
+    end
+  end
+
+  def move_forward
+    :vroom
+  end
+
+  def has_reached_destination?
+    # code goes here
+  end
+end
+
+In this case, we instantiate a DrivesACar command and store it somewhere.  Every now and then (in response to a timer, a cron job or some other trigger) we call execute, which looks at the command's internal state and chooses if it is moving or stopped.  Eventually, when we have reached our destination, the command is marked as complete. Also note, that as we do nothing when stopped, there's no need to define a stopped method.  
+
+Commands can also trigger child commands, and are notified when the child completes.
+
+For example: 
+
+class CourierDeliversAParcel < Struct.new(:pickup_location, :dropoff_location)
+  include Czar::Command
+
+  def start
+    perform CollectsParcel.new(pickup_location)
+    mark_as :waiting_for_pickup
+  end
+
+  def child_task_completed task
+    if self.state == :waiting_for_pickup
+      perform DeliversParcel.new(dropoff_location)
+      mark_as :waiting_for_dropoff
+    elsif self.state == :waiting_for_dropoff
+      mark_as :complete
+    end
+  end
+end
+
+## Contributing
+
+1. Fork it ( http://github.com/<my-github-username>/czar/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 new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+require 'minitest/autorun'
+
+Rake::TestTask.new do |t|
+ t.libs << 'test'
+ t.test_files = Dir["test/**/*_test.rb"]
+end
+
+desc "Run tests"
+task :default => :test

data/czar.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'czar/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "czar"
+  spec.version       = Czar::VERSION
+  spec.authors       = ["Rahoul Baruah"]
+  spec.email         = ["rahoul@3hv.co.uk"]
+  spec.summary       = "A framework for implementing the Command pattern"
+  spec.description   = "Persistent, hierarchical commands"
+  spec.homepage      = "http://passiverecord.com"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  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.5"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "minitest"
+  spec.add_development_dependency "mocha"
+end

data/lib/czar/command.rb

@@ -0,0 +1,53 @@
+module Czar
+  module Command
+
+    def execute
+      self.send self.state if self.respond_to? self.state
+    end
+
+    def result
+      internal[:result]
+    end
+
+    def completed?
+      state == :complete
+    end
+
+    def state
+      @state ||= :start
+    end
+
+    def children
+      @children ||= []
+    end
+
+    protected
+
+    attr_accessor :parent
+
+    def perform child_task
+      child_task.parent = self
+      children << child_task
+      child_task.execute
+    end
+
+    def mark_as state, params = {}
+      @state = state.to_sym
+      @internal_state = params.dup
+      notify_parent if @state == :complete
+    end
+
+    def internal
+      @internal_state ||= {}
+    end
+
+    def notify_parent
+      parent.child_task_completed self unless parent.nil?
+    end
+
+    def child_task_completed child_task
+
+    end
+
+  end
+end

data/lib/czar/version.rb

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

data/lib/czar.rb

@@ -0,0 +1,5 @@
+require "czar/version"
+
+module Czar
+  # Your code goes here...
+end

data/test/czar/command_test.rb

@@ -0,0 +1,151 @@
+require_relative '../../lib/czar/command'
+require 'minitest/autorun'
+require 'mocha/setup'
+
+describe Czar::Command do
+
+  describe "initialisation" do
+    subject { initialiser.new }
+
+    it "is ready to start" do
+      subject.state.must_equal :start
+    end
+
+    let(:initialiser) do
+      Class.new do
+        include Czar::Command
+      end
+    end
+  end
+
+  describe "performing a one stage task" do
+    subject { one_stage_task.new }
+
+    it "executes the start task" do
+      subject.execute
+
+      subject.completed?.must_equal true
+      subject.result.must_equal "DONE"
+    end
+
+    let(:one_stage_task) do
+      Class.new do
+        include Czar::Command
+
+        def start
+          mark_as :complete, result: "DONE"
+        end
+      end
+    end
+  end
+
+  describe "performing a multi stage task" do
+    subject { multi_stage_task.new }
+
+    it "executes the tasks and moves through the states in order" do
+      subject.execute
+      subject.state.must_equal :in_progress
+
+      subject.execute
+      subject.state.must_equal :having_a_rest
+
+      subject.execute
+      subject.state.must_equal :having_a_rest
+
+      subject.execute
+      subject.completed?.must_equal true
+      subject.result.must_equal 'Goodbye'
+    end
+
+    let(:multi_stage_task) do
+      Class.new do
+        include Czar::Command
+
+        def start
+          mark_as :in_progress
+        end
+
+        def in_progress
+          mark_as :having_a_rest, counter: 1
+        end
+
+        def having_a_rest
+          if internal[:counter] == 1 
+            mark_as :having_a_rest, counter: 2
+          else
+            mark_as :complete, result: 'Goodbye'
+          end
+        end
+      end
+    end
+  end
+
+  describe "having states that do nothing" do
+    subject { do_nothing_task.new }
+
+    it "executes the first task and then does nothing" do
+      subject.execute
+      subject.state.must_equal :idle
+      subject.execute
+      subject.state.must_equal :idle
+    end
+
+    let(:do_nothing_task) do
+      Class.new do
+        include Czar::Command
+
+        def start
+          mark_as :idle
+        end
+      end
+    end
+  end
+
+  describe "triggering child commands" do
+    subject { parent_task.new }
+
+    it "starts the child command and is not marked as complete until both it and the child have completed" do
+      subject.execute
+
+      child = subject.children.first
+      child.state.must_equal :in_progress
+      subject.state.must_equal :waiting_for_child_to_complete
+      subject.completed?.wont_equal true
+
+      child.execute
+      child.completed?.must_equal true
+      subject.completed?.must_equal true
+    end
+
+    let(:parent_task) do
+      Class.new do
+        include Czar::Command
+
+        def start
+          perform ChildTask.new
+          mark_as :waiting_for_child_to_complete
+        end
+
+        def waiting_for_child_to_complete
+          sleep 0.1
+        end
+
+        def child_task_completed child_task
+          mark_as :complete
+        end
+
+        class ChildTask
+          include Czar::Command
+
+          def start
+            mark_as :in_progress
+          end
+
+          def in_progress
+            mark_as :complete
+          end
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: czar
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Rahoul Baruah
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-07-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !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: minitest
+  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: mocha
+  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: Persistent, hierarchical commands
+email:
+- rahoul@3hv.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- czar.gemspec
+- lib/czar.rb
+- lib/czar/command.rb
+- lib/czar/version.rb
+- test/czar/command_test.rb
+homepage: http://passiverecord.com
+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.1
+signing_key: 
+specification_version: 4
+summary: A framework for implementing the Command pattern
+test_files:
+- test/czar/command_test.rb