lab42_state_machine 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b9a37c4012f2237fa5f1091a526fdeeede4beae5
-  data.tar.gz: df6284a690961697d3a57c592a1c2518966b44b4
+  metadata.gz: 40cee82db2d88428e2e52f115faa98ccb571020d
+  data.tar.gz: 8a716c44053c53ebbdc2aabfa590c8c9f0543aab
 SHA512:
-  metadata.gz: d1c8f0bffc1f5a0b16104f742d99390cb159df8ba7f4a3b5377b39f8eae5c9df0b36cd9bf1778e3e4b2f4be69ee2235c5a33f2cb2e3cf568874ffdb8d36753d4
-  data.tar.gz: 2671e4029d32fb74b8a7ad887ed28fcb0d61a8068024870984d9b1c4356dcbe7523b2345c6d2c90904d7f518c9a2ce8997e65db5a9c60e2d8073fdc314c7a105
+  metadata.gz: a88d6d79918585acd61f4fed0dd0274cbe61c22cf3fd4900d145fd5844dd36231e2f3ec6cf9cddf8ebc66402e238c363050ace782ae999b11421f943bf798c58
+  data.tar.gz: 9f7dc40f0c3a0cd3e887d9048b1574834d5cccdb85c2d81a778b9882fb823f3aa8df9a49f91cebc301a4c79046ed3c412480cd11215e32ac29af6f24feb59bde

data/README.md

@@ -30,6 +30,17 @@ A counter
   end.run %w{a b c} # ===> 3 (self.subject)
 ```
 
+This simple example demonstrates the following essential rules:
+
+* An easy way to setup the State Machine is by providing a block to its constructor. This block
+is instance evalled and thus has access to the whole API (see below). But of course the public API
+methods can be accessed in a more detached style too:
+    `state\_machine.state :reset do @counter = 0 end`
+
+* The initial state of the State Machine defaults to `:init`
+
+The next example will demonstrate more API methods
+
 ```ruby
       SM = Lab42::StateMachine
 
@@ -73,3 +84,77 @@ A counter
       end.run [true, false, false, true, true, true, false] 
            # ===> { true => [[0,1],[3,6]], false => [[1,3], [6,7]] }
   ```
+
+In particular we are allowed to use instance variables (and their sexier accessor implementations) to transport
+state between the states of the State Machine. This is without danger as the API hides all behind the controller
+and does not contain *any* instance variable (not even `@controller`).
+
+Of course it might be worthwile to consider closing over some local variables like in the following example if appropriate.
+
+```ruby
+   # Sometime is is preferble to use the State Machine with a state implementing object
+   result = SomeObject.new
+   StateMachine.new do
+     before do | input |
+       state = some_function_of input
+     end
+     transition a: :b do | input |
+       result.update from: :a, to: :b, with: :input
+     end
+     teardown do | last_input, old_state |
+       result.update from: old_state, to: result.end, with: last_input
+     end
+   end.run ...
+```
+
+## API
+
+### Setup Methods and Handler Definitions
+
+The following methods can be used inside the constructor block without explicit revceiver, or just invoked on a `StateMachine` instance.
+
+#### after
+
+`after do | input, old_state, new_state |`  will be run after each input record has been processed. As all handlers they will be executed
+in order of definition.
+
+#### before
+
+`before do | input, old_state, new_state |`  will be run before each input record has been processed. As all handlers they will be executed
+in order of definition.
+
+
+#### setup
+
+`setup do |input|` The StateMachine peeks into the lazy enumerator and provides the first value (or nil for empty) as parameter. These handlers are the first to be run before any other and *before* the first input record will be
+fetched. Yet they give access to the Runtime API, notably they allow to set the initial state to something else as `:init` by means of the one parameter form to the state call
+     ```state :new_initial_state```
+
+#### state
+
+This is the (overloaded - for the sake of a slim API) workerbee of the State Machine, it comes in three forms:
+
+##### state querying form (0 params)
+
+Really part of the *Runtime API*
+
+`state` currrent_state of the StateMachine
+
+##### state setter form (1 param)
+
+Really part of the *Runtime API*
+
+`state new_state` You'll never guess what this one does.
+
+##### state handler definition form (1 param and block)
+
+`state some_state do |input, old_state, current_state| ...` These blocks will be called for each input record processed in some\_state
+
+#### teardown
+
+`teardown do | last_input, last_state |` Will be called at the very end of the processing cycle.
+
+
+#### transition
+
+`transition a: :b, b: :c do |input, old_state, new_state|` These are execute when the state changes from :a to :b, or :b to :a. Of course only one transition can be indicated (and mostly will be). These handlers are executed *after* the state handlers fot the new states, that is :b or :c in our case.

data/lib/lab42/state_machine/controller.rb

@@ -26,20 +26,16 @@ module Lab42
         run_state_blocks @befores
       end
 
-      def run_setup_blocks blox
-        blox.each do | block |
-          @sm.instance_exec( @state, &block )
-        end
-      end
-
       def run_state_blocks blox
         blox.each do | block |
           @sm.instance_exec( @current_input, @old_state, @state, &block )
         end
       end
 
-      def run_setups
-        run_setup_blocks @setups
+      def run_setups input
+        @setups.each do | block |
+          @sm.instance_exec( input, &block )
+        end
       end
 
       def run_states
@@ -47,8 +43,10 @@ module Lab42
       end
 
 
-      def run_teardowns
-        run_setup_blocks @teardowns
+      def run_teardowns input
+        @teardowns.each do | teardown |
+          @sm.instance_exec( input, @state, &teardown )
+        end
       end
 
       def run_transitions
@@ -87,12 +85,13 @@ module Lab42
         @old_state = nil
         @state     = :init
 
-        @setups      = []
-        @teardowns   = []
-        @afters      = []
-        @befores     = []
-        @handlers    = mk_ary_hash
-        @transitions = mk_ary_hash
+        @setups       = []
+        @teardowns    = []
+        @afters       = []
+        @befores      = []
+        @before_first = []
+        @handlers     = mk_ary_hash
+        @transitions  = mk_ary_hash
       end
     end # class Controller
   end # class StateMachine

data/lib/lab42/state_machine/version.rb

@@ -1,5 +1,5 @@
 module Lab42
   class StateMachine
-    Version = "0.1.0"
+    Version = "0.1.1"
   end # class StateMachine
 end # module Lab42

data/lib/lab42/state_machine.rb

@@ -6,15 +6,22 @@ module Lab42
     extend Forwarder
     attr_accessor :subject
 
-    forward_all :after, :before, :setup, :state, :step, :teardown, :transition, to: :controller
+    forward_all :after, :before, :setup, :state, :teardown, :transition, to: :controller
+
+    def halt_machine
+      raise StopIteration, "#{self} halted"
+    end
 
     def run input=[]
-      inputs = make_inputs input
-      controller.run_setups
-      inputs.each do | input |
+      inputs = __make_inputs__ input
+      input  = nil
+      
+      controller.run_setups( (inputs.peek rescue nil) )
+      loop do
+        input = inputs.next
         controller.run input
       end
-      controller.run_teardowns
+      controller.run_teardowns input
       subject
     end 
 
@@ -34,10 +41,10 @@ module Lab42
       end
     end
 
-    def make_inputs input
+    def __make_inputs__ input
       case input
       when Enumerable, Enumerator
-        input
+        input.lazy
       else
         raise ArgumentError, "cannot enumerate on object #{input}"
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lab42_state_machine
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Robert Dober
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-09-09 00:00:00.000000000 Z
+date: 2013-09-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: forwarder19