composable_state_machine 1.0.2

data/Rakefile

@@ -0,0 +1,19 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'yard'
+
+desc 'Default: run the specs'
+task :default do
+  system('bundle exec rspec')
+end
+
+desc 'Run the specs'
+task :spec => :default
+
+desc 'Open an irb session preloaded with this library'
+task :console do
+  exec 'irb -rubygems -I lib -r composable_state_machine.rb'
+end
+
+YARD::Rake::YardocTask.new do |_|
+end

data/assets/class-diagram.yuml

@@ -0,0 +1,24 @@
+// composable_state_machine class diagram
+[≺≺interface≻≻;ICallbackRunner||run_state_machine_callback(callback){bg:green}]
+[≺≺interface≻≻;ICallable||call(*)]
+[≺≺interface≻≻;IMachine||trigger(event);==(other_state){bg:orange}]
+[Machine|state|{bg:orange}]
+[Model|initial_state|transition(event...);run_callbacks();run_callbacks_for(){bg:red}]
+[Transitions||on(event...);transition(event...){bg:blue}]
+[Behaviors||on(behavior...){bg:green}]
+[Callbacks||on(trigger...){bg:green}]
+[≺≺interface≻≻;ICallable]^-.-[Behaviors]
+[≺≺interface≻≻;ICallable]^-.-[Callbacks]
+[≺≺interface≻≻;ICallbackRunner]-.-> called[≺≺interface≻≻;ICallable]
+[≺≺interface≻≻;ICallbackRunner]^-.-[≺≺mixin≻≻;CallbackRunner{bg:green}]
+[≺≺interface≻≻;ICallbackRunner]^-.-[DefaultCallbackRunner{bg:green}]
+[≺≺interface≻≻;IMachine]^-.-[MachineWithExternalState]
+[Model]-1> default runner[≺≺interface≻≻;ICallbackRunner]
+[Model]-1>[Transitions]
+[Model]-1>[Behaviors]
+[Behaviors]-*> by behavior[Callbacks]
+[Callbacks]-*> by trigger[≺≺interface≻≻;ICallable]
+[MachineWithExternalState{bg:orange}]^[Machine]
+[MachineWithExternalState]-1>[Model]
+[MachineWithExternalState]-1>[≺≺interface≻≻;ICallbackRunner]
+[MachineWithExternalState]-2> state reader/writer[≺≺interface≻≻;ICallable]

data/composable_state_machine.gemspec

@@ -0,0 +1,35 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'composable_state_machine/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'composable_state_machine'
+  spec.version       = ComposableStateMachine::VERSION
+  spec.authors       = ['Simeon Simeonov']
+  spec.email         = ['sim@swoop.com']
+  spec.description   = %q{Small, fast and flexible state machines using composition.}
+  spec.summary       = %q{The composition patterns in this implementation make it easy to circumvent the limitations of other state machine gems. A single state machine model can be shared across thousands of machine instances without the usual overhead. An object can have more than one state machine. States and events can be any objects, not just strings or symbols. Events can take optional parameters. Different state machine models can fire different types of callbacks. Adding new types of callbacks takes a couple of lines of code. Explicit callback runners enable easy decoration for logging, caching or other purposes. No external dependencies and 100% code coverage.}
+  spec.homepage      = 'https://github.com/swoop-inc/composable_state_machine'
+  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 = %w(lib)
+
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'coveralls'
+  spec.add_development_dependency 'awesome_print'
+  spec.add_development_dependency 'yard'
+  spec.add_development_dependency 'redcarpet'
+
+  if RUBY_PLATFORM =~ /darwin/ && RUBY_VERSION =~ /^2/
+    spec.add_development_dependency 'guard'
+    spec.add_development_dependency 'guard-rspec'
+    spec.add_development_dependency 'growl'
+  end
+end

data/lib/composable_state_machine.rb

@@ -0,0 +1,45 @@
+Dir['lib/composable_state_machine/**/*.rb'].each { |f| require File.expand_path(f) }
+
+# @author {https://github.com/ssimeonov Simeon Simeonov}, {http://swoop.com Swoop, Inc.}
+#
+# For examples, see the {file:README.html README}.
+module ComposableStateMachine
+
+  # Creates a state machine model.
+  #
+  # State machine models are immutable and can be shared across many state machine instances.
+  #
+  # @param [Hash] options the options to create a model with.
+  # @option options [Hash, Transitions] :transitions State machine transitions. A {Transitions} object will be created if a Hash is provided.
+  # @option options [Hash, Behaviors] :behaviors State machine behaviors. A {Behaviors} object will be created if a Hash is provided. If omitted, a high-performance behaviors stub will be used.
+  # @option options [Object] :callback_runner (DefaultCallbackRunner) Object whose #run_state_machine_callback method will be used to execute behavior callbacks. {DefaultCallbackRunner} simply calls a Proc's #call method.
+  # @option options [Object] :initial_state (nil) Default initial state for the machine. This can be overriden by a machine instance.
+  # @option options [Object] :model_factory (Model) The object whose #new method will be called to create a model.
+  def self.model(options)
+    options = options.dup
+    unless options[:transitions].respond_to?(:transition)
+      options[:transitions] = Transitions.new(options[:transitions] || {})
+    end
+    unless options[:behaviors].respond_to?(:call)
+      options[:behaviors] = Behaviors.new(options[:behaviors] || {})
+    end
+    (options[:model_factory] || Model).new(options)
+  end
+
+  # Creates a state machine from a model.
+  #
+  # The variable number of arguments is driven by the difference in initialization APIs between different machines.
+  #
+  # The last argument must be an options Hash. It may have at least the following options:
+  #
+  # - :callback_runner [Object] (DefaultCallbackRunner) Object whose #run_state_machine_callback method will be used to execute behavior callbacks. {DefaultCallbackRunner} simply calls a Proc's #call method. When you want to execute callbacks in the context of an object, include the {CallbackRunner} mixin in the object and then pass the object as the callback runner here.
+  # - :state [Object] (model#initial_state) State the machine is in.
+  # - :model_factory [Object] ({Machine}) The object whose #new method will be called to create the machine.
+  #
+  # @param [Model, ...] model the state machine model.
+  # @param [any] args additional arguments passed to the model.
+  def self.machine(model, *args)
+    options = args.last
+    (options[:machine_factory] || Machine).new(model, *args)
+  end
+end

data/lib/composable_state_machine/behaviors.rb

@@ -0,0 +1,48 @@
+module ComposableStateMachine
+
+  # Defines the behaviors of a state machine.
+  class Behaviors
+    # Creates a {Behaviors} object.
+    #
+    # @param [Hash<behavior, Hash<trigger, callback>>] behaviors triggers and callbacks per behavior. The triggers and callbacks can be provided as an object the responds to #call or they can be provided as a Hash<trigger, callback>. In the latter case, the callbacks factory will be used to create an object that would manage the callbacks for the behavior.
+    # @param [Object] callbacks_factory object whose #new method will be called with a Hash<trigger, callback>.
+    def initialize(behaviors = {}, callbacks_factory = Callbacks)
+      @callbacks_factory = callbacks_factory
+      @behaviors = behaviors.reduce({}) do |memo, (behavior, value)|
+        handler = value.respond_to?(:call) ? value : @callbacks_factory.new(value)
+        memo[behavior] = handler
+        memo
+      end
+    end
+
+    # Adds callbacks for a behavior.
+    #
+    # Selects the callback manager for the behavior and forwards to its #on method.
+    #
+    # @param [Object] behavior the behavior
+    # @param [Array<Object>] args parameters to pass to the callback manager's #on method.
+    #
+    # @return [self] for chaining
+    def on(behavior, *args, &block)
+      (@behaviors[behavior] ||= @callbacks_factory.new).on(*args, &block)
+      self
+    end
+
+    # Runs callbacks for a behavior with a runner.
+    #
+    # Selects the callback manager for the behavior and forwards to its #call method.
+    #
+    # @param [Object] runner the runner
+    # @param [Object] behavior the behavior
+    # @param [Array<Object>] args parameters to pass to the callback manager's #call method.
+    #
+    # @return [self] for chaining
+    def call(runner, behavior, *args)
+      @behaviors[behavior].tap do |handler|
+        handler.call(runner, *args) if handler
+      end
+      self
+    end
+  end
+
+end

data/lib/composable_state_machine/callback_runner.rb

@@ -0,0 +1,19 @@
+module ComposableStateMachine
+
+  # Mixin module that runs callbacks with self pointing to the object the module is included in.
+  module CallbackRunner
+    # Runs a callback with self pointing to the object the module is included in.
+    #
+    # @param [Proc, Method, UnboundMethod, ...] callback the callback. Unbound methods will be bound to the object the mixin is included in.
+    # @param [Array<Object>] args parameters to pass to the callback.
+    #
+    # @return [Object] the result of the callback
+    def run_state_machine_callback(callback, *args)
+      if callback.respond_to?(:bind)
+        callback = callback.bind(self)
+      end
+      instance_exec(*args, &callback)
+    end
+  end
+
+end

data/lib/composable_state_machine/callbacks.rb

@@ -0,0 +1,56 @@
+module ComposableStateMachine
+
+  # Manages callbacks for a behavior.
+  class Callbacks
+    # Creates a {Callbacks} object.
+    #
+    # @param [Hash<trigger, callback(s)>] callbacks maps triggers to zero or more callbacks.
+    def initialize(callbacks = {})
+      @callbacks = Hash.new { |hash, key| hash[key] = [] }
+      callbacks.each_pair do |trigger, proc|
+        if proc.respond_to?(:each)
+          proc.each do |callback|
+            on(trigger, callback)
+          end
+        else
+          on(trigger, proc)
+        end
+      end
+    end
+
+    # Adds a callback for a trigger.
+    #
+    # @param [Object] trigger the callback trigger
+    # @param [Proc, Method, ...] proc an object responding to #call. If non-nil, it will be given precedence to #block
+    # @param [block] block an optional block implementing the callback
+    #
+    # @return [self] for chaining
+    def on(trigger, proc = nil, &block)
+      @callbacks[trigger] << (proc || block)
+      self
+    end
+
+    # Runs the callbacks for a trigger with a runner.
+    #
+    # Runs the callbacks for the :any trigger for every trigger.
+    #
+    # @param [Object] runner the runner
+    # @param [Object] trigger the callback trigger
+    # @param [Array<Object>] args parameters to pass to the callbacks' #call methods.
+    #
+    # @return [self] for chaining
+    def call(runner, trigger, *args)
+      if trigger == :any
+        raise InvalidTrigger.new(':any is not a valid trigger')
+      end
+      @callbacks[trigger].each do |callback|
+        runner.run_state_machine_callback(callback, *args)
+      end
+      @callbacks[:any].each do |callback|
+        runner.run_state_machine_callback(callback, *args)
+      end
+      self
+    end
+  end
+
+end

data/lib/composable_state_machine/default_callback_runner.rb

@@ -0,0 +1,16 @@
+module ComposableStateMachine
+
+  # Default callback runner that executes callbacks in their current binding.
+  class DefaultCallbackRunner
+    # Runs a callback in its current binding.
+    #
+    # @param [Proc, Method, ...] callback the callback, which must respond to #call.
+    # @param [Array<Object>] args parameters to pass to the callback.
+    #
+    # @return [Object] the result of the callback
+    def self.run_state_machine_callback(callback, *args)
+      callback.call(*args)
+    end
+  end
+
+end

data/lib/composable_state_machine/invalid_event.rb

@@ -0,0 +1,7 @@
+module ComposableStateMachine
+
+  # Raised when an invalid event is passed into {Transitions#transition}.
+  class InvalidEvent < NoMethodError
+  end
+
+end

data/lib/composable_state_machine/invalid_transition.rb

@@ -0,0 +1,7 @@
+module ComposableStateMachine
+
+  # Raised in {Transitions} when nil is a state to transition to.
+  class InvalidTransition < StandardError
+  end
+
+end

data/lib/composable_state_machine/invalid_trigger.rb

@@ -0,0 +1,7 @@
+module ComposableStateMachine
+
+  # Raised in {Callbacks} when :any is received as an explicit trigger.
+  class InvalidTrigger < StandardError
+  end
+
+end

data/lib/composable_state_machine/machine.rb

@@ -0,0 +1,21 @@
+require_relative 'machine_with_external_state'
+
+module ComposableStateMachine
+
+  # Machine with its own state.
+  class Machine < MachineWithExternalState
+    attr_reader :state
+
+    # Creates a machine. Delegates to {MachineWithExternalState#initialize} passing method(:state) & method(:state=) as the state reader and writer.
+    def initialize(model, options = {})
+      super(model, method(:state), method(:state=), options)
+    end
+
+    private
+
+    def state=(new_state)
+      @state = new_state
+    end
+  end
+
+end

data/lib/composable_state_machine/machine_with_external_state.rb

@@ -0,0 +1,41 @@
+module ComposableStateMachine
+
+  # State machine instance that manages its state via a reader and writer objects.
+  class MachineWithExternalState
+    # Creates an instance.
+    #
+    # @param [Model, ...] model the model for the machine
+    # @param [Proc, Method, ...] state_reader object whose #call method will return the current state
+    # @param [Proc, Method, ...] state_writer object whose #call method will be called with the new state after a transition
+    # @param [Hash] options the options to create the machine with.
+    # @option options [Object] :state (model#initial_state) State of the machine.
+    # @option options [Object] :callback_runner (model#callback_runner) Object whose #run_state_machine_callback method will be used to execute behavior callbacks.
+    def initialize(model, state_reader, state_writer, options = {})
+      @model = model
+      @state_reader = state_reader
+      @state_writer = state_writer
+      @callback_runner = options[:callback_runner] || model.callback_runner
+      initial_state = options[:state] || model.initial_state
+      @state_writer.call(initial_state)
+    end
+
+    # Executes the transition and behaviors associated with an event.
+    #
+    # @param [Object] event the event
+    # @param [Array<Object>] args event arguments
+    #
+    # @return [Object, nil] the result of model#transition
+    def trigger(event, *args)
+      current_state = @state_reader.call
+      @model.transition(current_state, event, args, @callback_runner, &@state_writer)
+    end
+
+    # Checks whether the state of the machine is equal to another state
+    #
+    # @return [TrueClass, FalseClass]
+    def ==(other_state)
+      @state_reader.call == other_state
+    end
+  end
+
+end

data/lib/composable_state_machine/model.rb

@@ -0,0 +1,55 @@
+module ComposableStateMachine
+
+  # An immutable state machine model that can be shared across many instances.
+  class Model
+    attr_reader :initial_state
+    attr_reader :callback_runner
+
+    # Creates a state machine model.
+    #
+    # @param [Hash] options the options to create a model with.
+    # @option options [Hash, Transitions] :transitions State machine transitions. A {Transitions} object will be created if a Hash is provided.
+    # @option options [Hash, Behaviors] :behaviors State machine behaviors. A {Behaviors} object will be created if a Hash is provided. If omitted, a high-performance behaviors stub will be used.
+    # @option options [Object] :initial_state (nil) Default initial state for the machine. This can be overriden by a machine instance.
+    # @option options [Object] :callback_runner (DefaultCallbackRunner) Object whose #run_state_machine_callback method will be used to execute behavior callbacks. {DefaultCallbackRunner} simply calls a Proc's #call method.
+    def initialize(options = {})
+      @initial_state = options[:initial_state]
+      @transitions = options[:transitions]
+      @behaviors = options[:behaviors] || proc {}
+      @callback_runner = options[:callback_runner] || DefaultCallbackRunner
+    end
+
+    # Performs a transition of the machine, executing behaviors as needed.
+    #
+    # @param current_state [Object] the current state of the machine
+    # @param event [Object] the event the machine has received
+    # @param arguments [Enumerable] ([]) any arguments related to the event.
+    # @param callback_runner [Object] ({Model#callback_runner}) the runner with which to execute callbacks
+    #
+    # @yield [Object] the new state of the machine, if a transition happened
+    #
+    # @return [Object] the new state of the machine, if a transition happened
+    # @return [nil] if no transition happened
+    def transition(current_state, event, arguments = [], callback_runner = nil)
+      @transitions.transition(current_state, event).tap do |new_state|
+        if new_state && new_state != current_state
+          callback_runner ||= @callback_runner
+          run_callbacks(callback_runner, current_state, event, new_state, arguments)
+          yield new_state if block_given?
+        end
+      end
+    end
+
+    # Runs the callbacks for all behaviors for a state transition
+    def run_callbacks(callback_runner, current_state, event, new_state, arguments, &block)
+      run_callbacks_for(callback_runner, :enter, new_state,
+                        current_state, event, new_state, *arguments)
+    end
+
+    # Runs the callbacks for one behavior for a start transition
+    def run_callbacks_for(callback_runner, behavior, *args)
+      @behaviors.call(callback_runner, behavior, *args)
+    end
+  end
+
+end

data/lib/composable_state_machine/transitions.rb

@@ -0,0 +1,73 @@
+module ComposableStateMachine
+
+  # Defines the transitions a state machine can make.
+  class Transitions
+    # Creates a {Transitions} object.
+    #
+    # @note While nil is a valid state to transition from, it is not a valid state to transition to.
+    #
+    # @param (Hash<event, Hash<from_state, to_state>>) transitions transitions Hash mapping events to a Hash from -> to state transitions
+    def initialize(transitions = {})
+      @transitions_for = transitions
+      validate_transitions
+    end
+
+    # Adds to the transitions for an event.
+    #
+    # @param [Object] event event causing the transition
+    # @param [Hash<from_state, to_state>] transitions transitions to the added to the transitions for the event.
+    #
+    # @return [self] for chaining
+    def on(event, transitions)
+      (@transitions_for[event] ||= {}).tap do |transitions_for_event|
+        transitions_for_event.merge!(transitions)
+        validate_transitions_for_event(event, transitions_for_event)
+      end
+      self
+    end
+
+    # Checks the transition map for a valid transition from a state given an event
+    #
+    # @param [Object] state the state the machine is in
+    # @param [Object] event event causing the transition
+    #
+    # @return [Object] new state for the machine, if a transition can occur
+    # @return [nil] if a transition cannot happen with this event
+    #
+    # @raise [InvalidEvent] if an unknown event is provided
+    def transition(state, event)
+      transitions_for_event = @transitions_for[event]
+      unless transitions_for_event
+        raise InvalidEvent.new("invalid event", event, state)
+      end
+      transitions_for_event[state]
+    end
+
+    # @return [Array<Object>] events for the machine
+    def events
+      @transitions_for.keys
+    end
+
+    # @return [Array<Object>] the states of the machine
+    def states
+      events.map { |e| @transitions_for[e].to_a }.flatten.uniq
+    end
+
+    private
+
+    def validate_transitions
+      @transitions_for.each_pair do |event, transitions|
+        validate_transitions_for_event(event, transitions)
+      end
+    end
+
+    def validate_transitions_for_event(event, transitions)
+      transitions.each_pair do |from, to|
+        if to.nil?
+          raise InvalidTransition.new("transition to nil from #{from.inspect} for #{event.inspect} event")
+        end
+      end
+    end
+  end
+
+end