motion-state-machine 0.8.1

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+.rvmrc
+build
+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 motion-state-machine.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Sebastian Burkhart
+
+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,145 @@
+# motion-state-machine
+
+Hey, this is `motion-state-machine` — a state machine gem designed for
+[RubyMotion](http://rubymotion.com) for iOS.
+
+## Motivation
+
+Undefined states and visual glitches in applications with complex UIs can
+be a hassle, especially when the UI is animated and the app has to handle
+asynchronous data retrieved in the background.
+
+Well-defined UI state machines avoid these problems while ensuring that
+asynchronous event handling does not lead to undefined results (a.k.a. bugs).
+
+MacRuby and Cocoa don't provide a simple library to address this —
+motion-state-machine should fill the gap for RubyMotion developers.
+
+motion-state-machine comes with a simple and nice-looking syntax to define
+states and transitions:
+
+    fsm = StateMachine::Base.new start_state: :awake
+
+	fsm.when :awake do |state|
+	   state.on_entry { puts "I'm awake, started and alive!" }
+	   state.transition_to :sleeping, on:  :finished_hard_work,
+	   state.die on: :too_hard_work
+	end
+
+It is [Grand Central Dispatch](https://developer.apple.com/library/mac/#documentation/Performance/Reference/GCD_libdispatch_Ref/Reference/reference.html)-aware
+and uses GCD queues for synchronization.
+
+## Installation
+
+1. If not done yet, add `bundler` gem management to your RubyMotion app.
+   See <http://thunderboltlabs.com/posts/using-bundler-with-rubymotion> for
+   an explanation how.
+
+2. Add this line to your application's Gemfile:
+
+		gem 'motion-state-machine',
+		  git: "git://github.com/opyh/motion-state-machine.git"
+
+3. Execute:
+
+		$ bundle
+
+## Usage
+
+The following example shows how to initialize and define a state machine:
+
+	fsm = StateMachine::Base.new start_state: :working, verbose: true
+
+This initializes a state machine. Calling `fsm.start!` would start the
+machine in the defined start state `:working`. Using `:verbose` activates
+debug output on the console.
+
+### Defining states and transitions
+
+After initialization, you can define states and transitions:
+
+	fsm.when :working do |state|
+
+	   state.on_entry { puts "I'm awake, started and alive!" }
+	   state.on_exit { puts "Phew. That was enough work." }
+
+	   state.transition_to :sleeping,
+	     on:      :finished_hard_work,
+	     if:      proc { really_worked_enough_for_now? },
+	     action:  proc { puts "Will go to sleep now." }
+
+	   state.die on: :too_hard_work
+
+	end
+
+This defines…
+
+1. An entry and an exit action block, called when entering/exiting the state
+   :working.
+
+2. a transition from state `:working` to `:sleeping`, happening when calling
+   `fsm.event(:finished_hard_work)`.
+
+   Before the transition is executed, the state machine asks the `:if` guard
+   block if the transition is allowed. Returning `false` in this block would
+   prevent the transition from happening.
+
+   If the transition is executed, the machine calls the given `:action` block.
+
+3. another transition that terminates the state machine when calling
+   `fsm.event(:too_hard_work)`. When terminated, the state machine stops
+   responding to events.
+
+Note that a transition from a state to itself can be _internal_: Entry/exit
+actions are not called on execution in this case.
+
+### Handling events, timeouts and NSNotifications
+
+Transitions can be triggered…
+
+- by calling the state machine's `#event` method (see above).
+
+- automatically after a given timeout:
+
+		fsm.when :sleeping do |state|
+		  state.transition_to :working, after: 20
+		end
+
+  (goes back to `:working` after 20 seconds in state `:sleeping`)
+
+- when a `NSNotification` is posted:
+
+		fsm.when :awake do |state|
+		  state.transition_to :in_background,
+		    on_notification: UIApplicationDidEnterBackgroundNotification
+		end
+
+### How fast is it?
+
+The implementation is designed for general non-performance-intensive purposes
+like managing UI state behavior. It may be too slow for parsing XML, realtime
+signal processing with high sample rates and similar tasks.
+
+Anyways, it should be able to handle several thousand events per second on
+an iOS device.
+
+## Contributing
+
+Feel free to fork the project and send me a pull request if you would
+like me to integrate your bugfix, enhancement, or feature.
+
+You can easily add new triggering mechanisms — they can be
+implemented in few lines by subclassing the `Transition` class (see
+the implementation of `NotificationTransition` for an example).
+
+I'm also open for suggestions regarding the interface design.
+
+To contribute,
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+If the feature has specs, I will probably merge it :)

data/Rakefile

@@ -0,0 +1,31 @@
+#!/usr/bin/env rake
+
+$:.unshift("/Library/RubyMotion/lib")
+
+require 'rubygems'
+require 'rake'
+require 'motion/project'
+require "bundler/gem_tasks"
+
+Bundler.setup
+Bundler.require
+
+Motion::Project::App.setup do |app|
+  app.name = 'testSuite'
+  app.identifier = 'com.screenfashion.motion-state-machine.spec-app'
+  app.specs_dir = './spec/motion-state-machine'
+  app.development do
+    # TODO: How to use module namespacing here?
+    app.delegate_class = 'MotionStateMachineSpecAppDelegate'
+  end
+end
+
+namespace :spec do
+  task :lib do
+    sh "bacon #{Dir.glob("spec/lib/**/*_spec.rb").join(' ')}"
+  end
+
+  task :motion => 'spec'
+
+  task :all => [:lib, :motion]
+end

data/lib/motion-state-machine.rb

@@ -0,0 +1,9 @@
+unless defined?(Motion::Project::Config)
+  raise "This file must be required within a RubyMotion project Rakefile."
+end
+
+Motion::Project::App.setup do |app|
+  Dir.glob(File.join(File.dirname(__FILE__), 'motion-state-machine/*.rb')).each do |file|
+    app.files.unshift(file)
+  end
+end

data/lib/motion-state-machine/base.rb

@@ -0,0 +1,223 @@
+# Hey, this is +motion-state-machine+, a state machine designed for
+# RubyMotion.
+#
+# It comes with a simple syntax to define states and transitions (see
+# {Base#when}). It is aware of Grand Central Dispatch queues and uses
+# them for synchronization.
+#
+# Its home is {https://github.com/opyh/motion-state-machine}.
+#
+# See the {file:README.md} for an overview and introduction.
+#
+# You might also want to look at {Base#when} and {State::TransitionDefinitionDSL}.
+
+module StateMachine
+
+  # Base class of a finite state machine (FSM). See {StateMachine} for
+  # an overview.
+
+  class Base
+
+    # @return [Dispatch::Queue] the GCD queue where the state
+    #   machine was started (or +nil+ if the state machine has
+    #   not been started yet)
+    attr_reader :initial_queue
+
+    # @return [String] Name of the state machine.
+    #   Only used in debug output.
+    attr_reader :name
+
+    # @return [Boolean] Indicates if the machine logs debug output.
+    attr_reader :verbose
+
+    # @return [State] Current {State} (or +nil+ if not in any
+    #   state, e.g. after exiting and before entering a new state)
+    attr_accessor :current_state
+
+
+    # Initializes a new StateMachine.
+    #
+    # @param options [Hash]
+    #   Configuration options for the FSM.
+    #
+    # @option options [Symbol] :start_state
+    #   First state after start
+    #
+    # @option options [String] :name ("State machine")
+    #   Name used in debugging output (optional)
+    #
+    # @option options [Boolean] :verbose (false)
+    #   Indicate if the machine should output log texts to console.
+    #
+    # @example
+    #   fsm = StateMachine::Base.new start_state: :awake
+    #
+    # @return [StateMachine::Base] a new StateMachine object
+
+    def initialize(options)
+      super
+      @name = options[:name] || "State machine"
+      @verbose = !!options[:verbose]
+      @state_symbols_to_states = {}
+
+      waiting_for_start_state = state :waiting_for_start,
+        "waiting for start (internal state)"
+      start_state = options[:start_state].to_sym
+      if start_state.nil?
+        raise ArgumentError, "You have to supply a :start_state option."
+      end
+      state start_state, options[:start_state_name]
+      self.when :waiting_for_start, do |state|
+        state.transition_to start_state, on: :start
+      end
+
+  		@current_state = waiting_for_start_state
+      @current_state.send :enter!
+    end
+
+
+    # Adds defined transitions to the state machine. States that
+    # you refer to with symbols are created automatically, on-the-fly,
+    # so you do not have to define them with an extra statement.
+    #
+    # @param source_state_symbol [Symbol]
+    #   Identifier of the state from which the transitions begins.
+    #
+    # @example Define transitions from a state +:awake+ to other states:
+    #   fsm.when :awake do |state|
+    #      state.transition_to ...
+    #      state.die :on => ...
+    #      state.on_entry { ... }
+    #      state.on_exit { ... }
+    #   end
+    #
+    # @yieldparam [TransitionDefinitionDSL] Call configuration methods
+    #   on this object to define transitions. See
+    #   {TransitionDefinitionDSL} for a list of possible methods.
+    #
+    # @see State::TransitionDefinitionDSL
+
+    def when(source_state_symbol, &block)
+      raise_outside_initial_queue
+      source_state = state source_state_symbol
+      source_state.send :add_transition_map_defined_in, &block
+    end
+
+
+    # @return an array of registered {StateMachine::State} objects.
+
+    def states
+      @state_symbols_to_states.values
+    end
+
+
+    # Starts the finite state machine. The machine will be in its
+    # start state afterwards. For synchronization, it will remember
+    # from which queue/thread it was started.
+
+    def start!
+    	@initial_queue = Dispatch::Queue.current
+      event :start
+    end
+
+
+    # Sends an event to the state machine. If a matching
+    # transition was defined, the transition will be executed. If
+    # no transition matches, the event will just be ignored.
+    #
+    # @note You should call this method from the same queue / thread
+    #   where the state machine was started.
+    #
+    # @param event_symbol [Symbol] The event to trigger on the
+    #   state machine.
+    #
+    # @example
+    #   my_state_machine.event :some_event
+
+    def event(event_symbol)
+      transition = @events[event_symbol]
+      transition.send(:handle_in_source_state) unless transition.nil?
+    end
+
+
+    # @returns [Boolean] +true+ if the machine has been terminated,
+    # +false+ otherwise.
+
+    def terminated?
+      current_state.terminating?
+    end
+
+    # Should stop the machine and clean up memory.
+    # Should call exit actions on the current state, if defined.
+    #
+    # Not yet tested / really implemented yet, so use with care and
+    # make a pull request if you should implement it ;)
+
+    def stop_and_cleanup
+      raise_outside_initial_queue
+      @state_machine.log "Stopping #{self}..." if @verbose
+      @current_state.send :exit!
+      @current_state = nil
+      @state_symbols_to_states.values.each(&:cleanup)
+    end
+
+
+    def inspect
+      # Overridden to avoid debug output overhead
+      # (default output would include all attributes)
+
+      "#<#{self.class}:#{object_id.to_s(16)}>"
+    end
+
+
+    # @api private
+    # Returns a State object identified by the given symbol.
+
+    def state(symbol, name = nil)
+      unless symbol.is_a?(Symbol)
+        raise ArgumentError,
+          "You have to supply a symbol to #state. "\
+          "Maybe you wanted to call #current_state?"
+      end
+      raise_outside_initial_queue
+      name ||= symbol.to_s
+      @state_symbols_to_states[symbol] ||= State.new(self,
+        symbol: symbol,
+        name: name)
+    end
+
+
+    # @api private
+    #
+    # Registers a block that should be called when {#event} is called
+    # with the given symbol as parameter.
+    #
+    # @param event_symbol [Symbol]
+    #   symbol that identifies the block
+    #
+    # @param transition [Transition]
+    #   transition that should be executed when calling {#event} with
+    #   +event_symbol+ as parameter
+
+    def register_event_handler(event_symbol, transition)
+      (@events ||= {})[event_symbol] = transition
+    end
+
+
+    # @api private
+
+    def raise_outside_initial_queue
+      outside = Dispatch::Queue.current.to_s != @initial_queue.to_s
+      if @initial_queue && outside
+        raise RuntimeError,
+          "Can't call this from outside #{@initial_queue} "\
+          "(called from #{Dispatch::Queue.current})."
+      end
+    end
+
+    def log(text)
+      puts text if @verbose
+    end
+
+  end
+end