aquam 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 756ccfa62e8a668e3f79a7a14d86a3d754a1f9fe
+  data.tar.gz: ddcad78f959438aecdba5ceab40e851b8dbcd95e
+SHA512:
+  metadata.gz: 3c30391f82ffa5d1291a9d54ac0d76ca3dadbbbadec02e6a9ac1e369b406534ae968b2901c8650fa401d6391eec81089d7abb249d5e529d520959038dac824f6
+  data.tar.gz: 134d43c549081bd25537ee095fabb793843d4d859ac33ca17014a4c64e37888a30dfee6d02dca0cf03b42d0c56cdb2dc676b7fbda2e195b1eeeea93740d93be8

data/README.md

@@ -0,0 +1 @@
+# aquam

data/aquam.gemspec

@@ -0,0 +1,19 @@
+Gem::Specification.new do |s|
+  s.name        = 'aquam'
+  s.version     = '0.0.1'
+  s.date        = Time.now.strftime('%Y-%m-%d')
+  s.summary     = 'DSL to define State Machines'
+  s.description = 'Aquam adds a DSL and validations to define a State Machine'
+  s.authors     = ['Emiliano Mancuso']
+  s.email       = ['emiliano.mancuso@gmail.com']
+  s.homepage    = 'http://github.com/emancu/aquam'
+  s.license     = 'MIT'
+
+  s.files = Dir[
+    'README.md',
+    'rakefile',
+    'lib/**/*.rb',
+    '*.gemspec'
+  ]
+  s.test_files = Dir['test/*.*']
+end

data/lib/aquam.rb

@@ -0,0 +1,7 @@
+require_relative 'aquam/errors'
+require_relative 'aquam/machine'
+require_relative 'aquam/state'
+
+module Aquam
+  VERSION = '0.0.1'
+end

data/lib/aquam/errors.rb

@@ -0,0 +1,14 @@
+module Aquam
+  class InvalidStateError < StandardError; end
+  class InvalidEventError < StandardError; end
+  class InvalidTransitionError < StandardError; end
+  class InvalidStateMachineError < StandardError; end
+
+  class FailedTransitionError < StandardError
+    attr_reader :errors
+
+    def initialize(errors = {})
+      @errors = errors
+    end
+  end
+end

data/lib/aquam/event_transitions.rb

@@ -0,0 +1,13 @@
+module Aquam
+  class EventTransitions
+    def initialize(machine, event_name, &block)
+      @machine    = machine
+      @event_name = event_name
+      instance_eval(&block)
+    end
+
+    def transition(from:, to:)
+      @machine.transition(from, to, @event_name)
+    end
+  end
+end

data/lib/aquam/machine.rb

@@ -0,0 +1,48 @@
+require_relative 'machine_class_methods'
+
+module Aquam
+  class Machine
+    extend Aquam::MachineClassMethods
+
+    attr_accessor :object
+
+    def initialize(object)
+      @object = object
+    end
+
+    def valid_state?
+      self.class.valid_state? attribute
+    end
+
+    def valid_event?(event)
+      self.class.valid_event? event
+    end
+
+    def valid_transition?(event)
+      self.class.events[event].key? attribute
+    end
+
+    def current_state
+      fail Aquam::InvalidStateError unless valid_state?
+
+      self.class.states[attribute].new object
+    end
+
+    def trigger(event, *args)
+      state = current_state
+
+      fail Aquam::InvalidEventError unless valid_event? event
+      fail Aquam::InvalidTransitionError unless valid_transition? event
+
+      state.send event, *args
+
+      current_state
+    end
+
+    private
+
+    def attribute
+      object.send(self.class.attribute.to_sym).to_sym
+    end
+  end
+end

data/lib/aquam/machine_class_methods.rb

@@ -0,0 +1,39 @@
+require_relative 'event_transitions'
+
+module Aquam
+  module MachineClassMethods
+    def attribute(name = nil)
+      name ? @attribute = name : @attribute ||= :state
+    end
+
+    def states
+      @states ||= {}
+    end
+
+    def events
+      @event ||= Hash.new { |hash, key| hash[key] = {} }
+    end
+
+    def state(name, klass)
+      states[name] = klass
+    end
+
+    def event(name, &block)
+      Aquam::EventTransitions.new self, name, &block
+    end
+
+    def transition(from, to, event_name)
+      fail Aquam::InvalidStateError if !valid_state?(from) || !valid_state?(to)
+
+      events[event_name][from] = to
+    end
+
+    def valid_state?(state)
+      states.keys.include? state
+    end
+
+    def valid_event?(event)
+      events.keys.include? event
+    end
+  end
+end

data/lib/aquam/state.rb

@@ -0,0 +1,46 @@
+module Aquam
+  class State
+    # I have to use a class variable because it **must** be the same value
+    # across all the children calsses.
+    #
+    # Also I need it defined always
+    @@state_machine = nil
+
+    def self.state_machine(state_machine = nil)
+      if state_machine && !@@state_machine
+        validate_state_machine state_machine
+
+        @@state_machine = state_machine
+        define_event_methods
+      end
+
+      @@state_machine
+    end
+
+    def initialize(object)
+      @object = object
+    end
+
+    def state_machine
+      self.class.state_machine || fail(Aquam::InvalidStateMachineError)
+    end
+
+    private
+
+    def self.define_event_methods
+      state_machine.events.keys.each do |event|
+        define_method event do
+          fail Aquam::InvalidTransitionError
+        end
+      end
+    end
+    private_class_method :define_event_methods
+
+    def self.validate_state_machine(state_machine)
+      unless state_machine.ancestors.include? Aquam::Machine
+        fail Aquam::InvalidStateMachineError
+      end
+    end
+    private_class_method :validate_state_machine
+  end
+end

data/rakefile

@@ -0,0 +1,8 @@
+task :default => :test
+
+desc 'Run tests'
+task :test do
+  require File.expand_path("./test/helper", File.dirname(__FILE__))
+
+  Dir["test/**/*_test.rb"].each { |file| load file }
+end

data/test/door_state_machine.rb

@@ -0,0 +1,43 @@
+require 'aquam'
+
+class DoorState < Aquam::State; end
+
+class OpenedDoorState < DoorState
+  def close
+    @object.state = :closed
+  end
+end
+
+class ClosedDoorState < DoorState
+  def open
+    @object.state = :opened
+  end
+end
+
+class DoorStateMachine < Aquam::Machine
+  state :opened, OpenedDoorState
+  state :closed, ClosedDoorState
+
+  event :open do
+    transition from: :closed, to: :opened
+  end
+
+  event :close do
+    transition from: :opened, to: :closed
+  end
+
+  event :knock do
+    transition from: :opened, to: :opened
+    transition from: :closed, to: :closed
+  end
+end
+
+class Door
+  attr_accessor :state
+  attr_reader :machine
+
+  def initialize
+    @state = :closed
+    @machine = DoorStateMachine.new self
+  end
+end

data/test/helper.rb

@@ -0,0 +1,8 @@
+$LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__) + '/../lib'))
+
+require 'minitest/autorun'
+require 'aquam'
+
+def deny(condition, message = 'Expected condition to be unsatisfied')
+  assert !condition, message
+end

data/test/machine_class_methods_test.rb

@@ -0,0 +1,144 @@
+require_relative 'helper'
+require_relative 'door_state_machine'
+
+describe Aquam::MachineClassMethods do
+  describe 'attribute' do
+    it 'uses :state as default' do
+      assert_equal :state, DoorStateMachine.attribute
+    end
+
+    it 'defines the proper attribute to access the state name' do
+      class NewStateMachine < Aquam::Machine
+        attribute :state_name
+      end
+
+      assert_equal :state_name, NewStateMachine.attribute
+
+      Object.send(:remove_const, :NewStateMachine)
+    end
+  end
+
+  describe 'states' do
+    it 'returns a hash with all the states as keys' do
+      assert_equal [:opened, :closed], DoorStateMachine.states.keys
+    end
+
+    it 'returns a hash with all the states defined' do
+      assert_equal OpenedDoorState, DoorStateMachine.states[:opened]
+      assert_equal ClosedDoorState, DoorStateMachine.states[:closed]
+    end
+
+    it 'checks if it is a valid state' do
+      assert DoorStateMachine.valid_state? :opened
+      deny DoorStateMachine.valid_state? :not_a_valid_state
+    end
+  end
+
+  describe 'events' do
+    it 'returns a hash with the events as keys' do
+      assert_equal [:open, :close, :knock], DoorStateMachine.events.keys
+    end
+
+    it 'returns a hash with the transitions of each event' do
+      close = { opened: :closed }
+      open =  { closed: :opened }
+      knock = { opened: :opened, closed: :closed }
+
+      assert_equal close, DoorStateMachine.events[:close]
+      assert_equal open,  DoorStateMachine.events[:open]
+      assert_equal knock, DoorStateMachine.events[:knock]
+    end
+
+    it 'checks if it is a valid event' do
+      assert DoorStateMachine.valid_event? :open
+      deny DoorStateMachine.valid_event? :not_a_valid_event
+    end
+  end
+
+  describe 'state' do
+    before do
+      class AState < Aquam::State; end
+      class StateMachine < Aquam::Machine; end
+    end
+
+    after do
+      Object.send(:remove_const, :AState)
+      Object.send(:remove_const, :StateMachine)
+    end
+
+    it 'defines a new state into the Machine' do
+      assert_equal [], StateMachine.states.keys
+
+      StateMachine.state :a, AState
+
+      assert_equal [:a], StateMachine.states.keys
+      assert_equal AState, StateMachine.states[:a]
+    end
+  end
+
+  describe 'event' do
+    before do
+      class AState < Aquam::State; end
+      class BState < Aquam::State; end
+
+      class StateMachine < Aquam::Machine
+        state :a, AState
+        state :b, BState
+      end
+    end
+
+    after do
+      Object.send(:remove_const, :AState)
+      Object.send(:remove_const, :BState)
+      Object.send(:remove_const, :StateMachine)
+    end
+
+    it 'defines an event with transitions' do
+      assert_equal [], StateMachine.events.keys
+
+      StateMachine.event :toggle do
+        transition from: :a, to: :b
+        transition from: :b, to: :a
+      end
+
+      assert_equal [:toggle], StateMachine.events.keys
+    end
+  end
+
+  describe 'transition' do
+    before do
+      class AState < Aquam::State; end
+      class BState < Aquam::State; end
+
+      class StateMachine < Aquam::Machine
+        state :a, AState
+        state :b, BState
+      end
+    end
+
+    after do
+      Object.send(:remove_const, :AState)
+      Object.send(:remove_const, :BState)
+      Object.send(:remove_const, :StateMachine)
+    end
+
+    it 'fails defining a transition between invalid states' do
+      assert_raises Aquam::InvalidStateError do
+        StateMachine.transition :undefined, :b, :event
+      end
+
+      assert_raises Aquam::InvalidStateError do
+        StateMachine.transition :a, :undefined, :event
+      end
+    end
+
+    it 'defines a new transition' do
+      assert_equal Hash.new, StateMachine.events[:event]
+
+      StateMachine.transition :a, :b, :event
+      expected_transition = { a: :b }
+
+      assert_equal expected_transition, StateMachine.events[:event]
+    end
+  end
+end

data/test/machine_test.rb

@@ -0,0 +1,68 @@
+require_relative 'helper'
+require_relative 'door_state_machine'
+
+describe Aquam::Machine do
+  before do
+    @door = Door.new
+    @machine = @door.machine
+  end
+
+  describe 'valid_*? methods' do
+    it 'returns a boolean if is a valid state' do
+      assert @machine.valid_state?
+
+      @door.state = :wrong_state
+
+      deny @machine.valid_state?
+    end
+
+    it 'returns a boolean if is a valid event' do
+      assert @machine.valid_event? :open
+      deny @machine.valid_event? :lock
+    end
+
+    it 'returns a boolean if is a valid transition from the current state' do
+      deny @machine.valid_transition? :close
+      assert @machine.valid_transition? :open
+    end
+  end
+
+  describe 'current_state' do
+    it 'returns an instance of the current state object' do
+      assert @machine.current_state.instance_of? ClosedDoorState
+
+      @door.state = :opened
+
+      assert @machine.current_state.instance_of? OpenedDoorState
+    end
+
+    it 'fails if the current state was not defined into the machine' do
+      assert_raises Aquam::InvalidStateError do
+        @door.state = :must_fail
+        @machine.current_state
+      end
+    end
+  end
+
+  describe 'trigger' do
+    it 'fires the event and returns the new state' do
+      assert @machine.current_state.instance_of? ClosedDoorState
+
+      new_state = @machine.trigger(:open)
+
+      assert new_state.instance_of? OpenedDoorState
+    end
+
+    it 'fails if is not a valid event' do
+      assert_raises Aquam::InvalidEventError do
+        @machine.trigger :lock
+      end
+    end
+
+    it 'fails if is not a valid transition' do
+      assert_raises Aquam::InvalidTransitionError do
+        @machine.trigger :close
+      end
+    end
+  end
+end

data/test/state_test.rb

@@ -0,0 +1,82 @@
+require_relative 'helper'
+require_relative 'door_state_machine'
+
+describe Aquam::State do
+  after do
+    DoorState.class_variable_set :@@state_machine, nil
+  end
+
+  describe 'state_machine class method' do
+    it 'fails if it is not a valid Aquam::Machine class' do
+      assert_raises Aquam::InvalidStateMachineError do
+        DoorState.state_machine String
+      end
+    end
+
+    it 'defines the state machine that will be used in the entire hierarchy' do
+      assert_equal nil, DoorState.state_machine
+
+      DoorState.state_machine DoorStateMachine
+
+      assert_equal DoorStateMachine, DoorState.state_machine
+    end
+
+    it 'defines the state machine for every sublcass' do
+      class OpenedDoorState < DoorState; end
+
+      DoorState.state_machine DoorStateMachine
+
+      assert_equal DoorStateMachine, OpenedDoorState.state_machine
+      assert_equal DoorStateMachine, OpenedDoorState.new(nil).state_machine
+    end
+
+    it 'defines the state machine only once' do
+      class WindowStateMachine < Aquam::Machine; end
+
+      DoorState.state_machine DoorStateMachine
+      DoorState.state_machine WindowStateMachine
+
+      assert_equal DoorStateMachine, DoorState.state_machine
+
+      Object.send(:remove_const, :WindowStateMachine)
+    end
+
+    it 'defines all the events as methods' do
+      DoorState.state_machine DoorStateMachine
+
+      assert DoorState.instance_methods.include? :open
+      assert DoorState.instance_methods.include? :close
+      assert DoorState.instance_methods.include? :knock
+    end
+
+    it 'fails by default on every event method' do
+      DoorState.state_machine DoorStateMachine
+
+      assert_raises Aquam::InvalidTransitionError do
+        DoorState.new(nil).open
+      end
+
+      assert_raises Aquam::InvalidTransitionError do
+        DoorState.new(nil).close
+      end
+
+      assert_raises Aquam::InvalidTransitionError do
+        DoorState.new(nil).knock
+      end
+    end
+  end
+
+  describe 'state_machine instance method' do
+    it 'returns the state machine class defined' do
+      DoorState.state_machine DoorStateMachine
+
+      assert_equal DoorStateMachine, DoorState.new(nil).state_machine
+    end
+
+    it 'fails if the state machine was not defined' do
+      assert_raises Aquam::InvalidStateMachineError do
+        DoorState.new(nil).state_machine
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: aquam
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Emiliano Mancuso
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-01-15 00:00:00.000000000 Z
+dependencies: []
+description: Aquam adds a DSL and validations to define a State Machine
+email:
+- emiliano.mancuso@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- aquam.gemspec
+- lib/aquam.rb
+- lib/aquam/errors.rb
+- lib/aquam/event_transitions.rb
+- lib/aquam/machine.rb
+- lib/aquam/machine_class_methods.rb
+- lib/aquam/state.rb
+- rakefile
+- test/door_state_machine.rb
+- test/helper.rb
+- test/machine_class_methods_test.rb
+- test/machine_test.rb
+- test/state_test.rb
+homepage: http://github.com/emancu/aquam
+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.4.5
+signing_key: 
+specification_version: 4
+summary: DSL to define State Machines
+test_files:
+- test/door_state_machine.rb
+- test/helper.rb
+- test/machine_class_methods_test.rb
+- test/machine_test.rb
+- test/state_test.rb