statesman-events 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2c7a41793f54b53f461686fbe163233c2d268e7d
+  data.tar.gz: 17c393eb70b31a656c7777cbc3d34362cd7d717b
+SHA512:
+  metadata.gz: dcb60ad78a61130a3628f3030ea67a193692705747f721b013aeb5b0685ba7aa20d6901e4523cf3680d1aa2af9c383d2dcfe0ab61befd50b0a7a4cd7188f6175
+  data.tar.gz: c636be370afa76f3871c1f8da47a0863af25a6042c8b444729d8be787891f2ef0bb2673ba3128df275c9ca9bd8b469e703e3c65b4e6e4086b5bb680653810038

data/.gitignore

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

data/.rubocop.yml

@@ -0,0 +1,48 @@
+# For all options see https://github.com/bbatsov/rubocop/tree/master/config
+
+AllCops:
+  Include:
+    - Rakefile
+    - statesman.gemfile
+    - lib/tasks/*.rake
+  Exclude:
+    - vendor/**/*
+    - .*/**
+    - spec/fixtures/**/*
+
+StringLiterals:
+  Enabled: false
+
+Documentation:
+  Enabled: false
+
+SignalException:
+  EnforcedStyle: only_raise
+
+# Avoid methods longer than 15 lines of code
+MethodLength:
+  CountComments: false
+  Max: 15
+
+AbcSize:
+  Max: 25
+
+# Don't require utf-8 encoding comment
+Encoding:
+  Enabled: false
+
+LineLength:
+  Max: 80
+
+GuardClause:
+  Enabled: false
+
+SingleSpaceBeforeFirstArg:
+  Enabled: false
+
+DotPosition:
+  EnforcedStyle: trailing
+
+# Allow class and message or instance raises
+Style/RaiseArgs:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,12 @@
+language: ruby
+
+rvm:
+  - 2.2
+  - 2.1
+  - 2.0
+
+sudo: false
+
+script:
+  - bundle exec rubocop
+  - bundle exec rake

data/CHANGELOG.md

@@ -0,0 +1,2 @@
+## v0.0.1, 5 December 2015
+- Initial release

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Guardfile

@@ -0,0 +1,14 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard :rspec, all_on_start: true, cmd: 'bundle exec rspec --color' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end
+
+guard :rubocop, all_on_start: true, cli: ['--format', 'clang'] do
+  watch(%r{.+\.rb$})
+  watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }
+  watch(%r{(?:.+/)?\rubocop-todo\.yml$}) { |m| File.dirname(m[0]) }
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Grey Baker
+
+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,86 @@
+Event support for [Statesman](https://github.com/gocardless/statesman).
+
+## TL;DR Usage
+
+```ruby
+class TaskStateMachine
+  include Statesman::Machine
+  include Statesman::Events
+
+  state :unstarted, initial: true
+  state :started
+  state :finished
+  state :cancelled
+
+  event :start do
+    transition from: :unstarted,  to: :started
+  end
+
+  event :finish do
+    transition from: :started,    to: :finished
+  end
+
+  event :cancel do
+    transition from: :unstarted,  to: :cancelled
+    transition from: :started,    to: :cancelled
+  end
+
+  event :restart do
+    transition from: :finished,   to: :started
+    transition from: :cancelled,  to: :started
+  end
+end
+
+class Task < ActiveRecord::Base
+  delegate :current_state, :trigger, :available_events, to: :state_machine
+
+  def state_machine
+    @state_machine ||= TaskStateMachine.new(self)
+  end
+end
+
+task = Task.new
+
+task.current_state          # => "unstarted"
+task.trigger(:start)        # => true/false
+task.current_state          # => "started"
+task.available_events       # => [:finish, :cancel]
+```
+
+## Class methods
+
+#### `Events.event`
+```ruby
+ExampleMachine.event(:some_event) do
+  transition from: :some_state,       to: :another_state
+  transition from: :some_other_state, to: :yet_another_state
+end
+```
+Define an event rule. When triggered, the first available transition from the
+current state will be called.
+
+## Instance methods
+
+#### `Event#trigger`
+```ruby
+instance.trigger(:some_event)
+```
+Triggers the passed event, returning `true` on success. Returns false on
+failure.
+
+#### `Event#trigger!`
+```ruby
+instance.trigger(:some_event)
+```
+Triggers the passed event, returning `true` on success. Raises
+`Statesman::GuardFailedError` or `Statesman::TransitionFailedError` on failure.
+
+#### `Event#available_events`
+```ruby
+instance.available_events
+```
+Returns an array of events you can `trigger` from the current state.
+
+---
+
+GoCardless ♥ open source. If you do too, come [join us](https://gocardless.com/jobs#software-engineer).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/statesman/event_transitions.rb

@@ -0,0 +1,32 @@
+module Statesman
+  class EventTransitions
+    attr_reader :machine, :event_name
+
+    def initialize(machine, event_name, &block)
+      @machine    = machine
+      @event_name = event_name
+      instance_eval(&block)
+    end
+
+    def transition(from: nil, to: nil)
+      from = to_s_or_nil(from)
+      to = array_to_s_or_nil(to)
+
+      machine.transition(from: from, to: to)
+
+      machine.events[event_name] ||= {}
+      machine.events[event_name][from] ||= []
+      machine.events[event_name][from] += to
+    end
+
+    private
+
+    def to_s_or_nil(input)
+      input.nil? ? input : input.to_s
+    end
+
+    def array_to_s_or_nil(input)
+      Array(input).map { |item| to_s_or_nil(item) }
+    end
+  end
+end

data/lib/statesman/events.rb

@@ -0,0 +1,51 @@
+require_relative "event_transitions"
+
+# Adds support for events when `extend`ed into state machine classes
+module Statesman
+  module Events
+    def self.included(base)
+      unless base.respond_to?(:states)
+        raise "Statesman::Events included before/without Statesman::Machine"
+      end
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def events
+        @events ||= {}
+      end
+
+      def event(name, &block)
+        EventTransitions.new(self, name, &block)
+      end
+    end
+
+    def trigger!(event_name, metadata = {})
+      transitions = self.class.events.fetch(event_name) do
+        raise Statesman::TransitionFailedError,
+              "Event #{event_name} not found"
+      end
+
+      new_state = transitions.fetch(current_state) do
+        raise Statesman::TransitionFailedError,
+              "State #{current_state} not found for Event #{event_name}"
+      end
+
+      transition_to!(new_state.first, metadata)
+      true
+    end
+
+    def trigger(event_name, metadata = {})
+      self.trigger!(event_name, metadata)
+    rescue Statesman::TransitionFailedError, Statesman::GuardFailedError
+      false
+    end
+
+    def available_events
+      state = current_state
+      self.class.events.select do |_, transitions|
+        transitions.key?(state)
+      end.map(&:first)
+    end
+  end
+end

data/lib/statesman/events/version.rb

@@ -0,0 +1,5 @@
+module Statesman
+  module Events
+    VERSION = "0.0.1"
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+require "statesman"
+require "statesman/events"
+require "rspec/its"
+
+RSpec.configure do |config|
+  config.raise_errors_for_deprecations!
+  config.mock_with(:rspec) { |mocks| mocks.verify_partial_doubles = true }
+  config.order = "random"
+end

data/spec/statesman/events_spec.rb

@@ -0,0 +1,167 @@
+require "spec_helper"
+
+describe Statesman::Events do
+  let(:machine) do
+    Class.new do
+      include Statesman::Machine
+      include Statesman::Events
+    end
+  end
+  let(:my_model) { Class.new { attr_accessor :current_state }.new }
+
+  describe "inclusion" do
+    context "after Statesman::Machine" do
+      let(:machine) do
+        Class.new do
+          include Statesman::Machine
+          include Statesman::Events
+        end
+      end
+
+      specify { expect { machine.events }.to_not raise_error }
+    end
+
+    context "without Statesman::Machine" do
+      let(:machine) { Class.new { include Statesman::Events } }
+
+      it "raises a descriptive error" do
+        expect { machine.events }.to raise_error(/without Statesman::Machine/)
+      end
+    end
+
+    context "before Statesman::Machine" do
+      let(:machine) do
+        Class.new do
+          include Statesman::Events
+          include Statesman::Machine
+        end
+      end
+
+      it "raises a descriptive error" do
+        expect { machine.events }.to raise_error(/without Statesman::Machine/)
+      end
+    end
+  end
+
+  describe "#event" do
+    before do
+      machine.class_eval do
+        state :x, initial: true
+        state :y
+        state :z
+
+        event :event_1 do
+          transition from: :x, to: :y
+        end
+
+        event :event_2 do
+          transition from: :y, to: :z
+        end
+      end
+    end
+
+    let(:instance) { machine.new(my_model) }
+
+    context "when the state cannot be transitioned to" do
+      it "raises an error" do
+        expect { instance.trigger!(:event_2) }.
+          to raise_error(Statesman::TransitionFailedError)
+      end
+    end
+
+    context "when the state can be transitioned to" do
+      it "changes state" do
+        instance.trigger!(:event_1)
+        expect(instance.current_state).to eq("y")
+      end
+
+      it "creates a new transition object" do
+        expect { instance.trigger!(:event_1) }.
+          to change(instance.history, :count).by(1)
+
+        expect(instance.history.first).
+          to be_a(Statesman::Adapters::MemoryTransition)
+        expect(instance.history.first.to_state).to eq("y")
+      end
+
+      it "sends metadata to the transition object" do
+        meta = { "my" => "hash" }
+        instance.trigger!(:event_1, meta)
+        expect(instance.history.first.metadata).to eq(meta)
+      end
+
+      it "sets an empty hash as the metadata if not specified" do
+        instance.trigger!(:event_1)
+        expect(instance.history.first.metadata).to eq({})
+      end
+
+      it "returns true" do
+        expect(instance.trigger!(:event_1)).to eq(true)
+      end
+
+      context "with a guard" do
+        let(:result) { true }
+        # rubocop:disable UnusedBlockArgument
+        let(:guard_cb) { ->(*args) { result } }
+        # rubocop:enable UnusedBlockArgument
+        before { machine.guard_transition(from: :x, to: :y, &guard_cb) }
+
+        context "and an object to act on" do
+          let(:instance) { machine.new(my_model) }
+
+          it "passes the object to the guard" do
+            expect(guard_cb).to receive(:call).once.
+              with(my_model, instance.last_transition, {}).and_return(true)
+            instance.trigger!(:event_1)
+          end
+        end
+
+        context "which passes" do
+          it "changes state" do
+            expect { instance.trigger!(:event_1) }.
+              to change { instance.current_state }.to("y")
+          end
+        end
+
+        context "which fails" do
+          let(:result) { false }
+
+          it "raises an exception" do
+            expect { instance.trigger!(:event_1) }.
+              to raise_error(Statesman::GuardFailedError)
+          end
+        end
+      end
+    end
+  end
+
+  describe "#available_events" do
+    before do
+      machine.class_eval do
+        state :x, initial: true
+        state :y
+        state :z
+
+        event :event_1 do
+          transition from: :x, to: :y
+        end
+
+        event :event_2 do
+          transition from: :y, to: :z
+        end
+
+        event :event_3 do
+          transition from: :x, to: :y
+          transition from: :y, to: :x
+        end
+      end
+    end
+
+    let(:instance) { machine.new(my_model) }
+    it "should return list of available events for the current state" do
+      expect(instance.available_events).to eq([:event_1, :event_3])
+      instance.trigger!(:event_1)
+      expect(instance.available_events).to eq([:event_2, :event_3])
+    end
+  end
+end

data/statesman-events.gemspec

@@ -0,0 +1,26 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'statesman/events/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "statesman-events"
+  spec.version       = Statesman::Events::VERSION
+  spec.authors       = ["Grey Baker"]
+  spec.email         = ["developers@gocardless.com"]
+  spec.description   = %q{Event support for Statesman}
+  spec.summary       = spec.description
+  spec.homepage      = "https://github.com/gocardless/statesman-events"
+  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_dependency             "statesman",     ">= 1.3"
+
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec",         "~> 3.1"
+  spec.add_development_dependency "rspec-its",     "~> 1.1"
+  spec.add_development_dependency "rubocop",       "~> 0.30.0"
+end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: statesman-events
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Grey Baker
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-12-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: statesman
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !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: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rspec-its
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.30.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.30.0
+description: Event support for Statesman
+email:
+- developers@gocardless.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rubocop.yml
+- .travis.yml
+- CHANGELOG.md
+- Gemfile
+- Guardfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/statesman/event_transitions.rb
+- lib/statesman/events.rb
+- lib/statesman/events/version.rb
+- spec/spec_helper.rb
+- spec/statesman/events_spec.rb
+- statesman-events.gemspec
+homepage: https://github.com/gocardless/statesman-events
+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: Event support for Statesman
+test_files:
+- spec/spec_helper.rb
+- spec/statesman/events_spec.rb