simple_states 0.0.1 → 0.0.2

data/README.md

@@ -1,5 +1,68 @@
 # simple\_states
 
-A super-slim (~200 loc) statemachine-like support library focussed on use in Travis CI.
+A super-slim (~200 loc) statemachine-like support library focussed on use in
+Travis CI.
 
-More docs coming soon, checkout the tests.
+## Usage
+
+Define states and events like this:
+
+    class Foo
+      include SimpleStates
+
+      states :created, :started, :finished
+
+      event :start,  :from => :created, :to => :started,  :if => :startable?
+      event :finish, :to => :finished, :after => :cleanup
+
+      attr_accessor :state
+
+      def start
+        # start foo
+      end
+    end
+
+Including the SimpleStates module to your class is currently required. We'll add
+hooks for ActiveRecord etc later.
+
+SimpleStates expects your model to support attribute accessors for `:state`.
+
+Event options have the following well-known meanings:
+
+    :from   # valid states to transition from
+    :to     # target state to transition to
+    :if     # only proceed if the given method returns true
+    :unless # only proceed if the given method returns false
+    :before # run the given method before running `super` and setting the new state
+    :after  # run the given method at the very end
+
+All of these options except for `:to` can be given as a single symbol or string or
+as an Array of symbols or strings.
+
+Calling `event` will effectively add methods to a proxy module which is
+included to the singleton class of your class' instances. E.g. declaring `event
+:start` in the example above will add a method `start` to a module included to
+the singleton class of instances of `Foo`.
+
+This method will
+
+1. check if `:if`/`:except` conditions apply (if given) and just return from the method otherwise
+2. check if the object currently is in a valid `:from` state (if given) and raise an exception otherwise
+3. run `:before` callbacks (if given)
+4. call `super` if Foo defines the current method (i.e. call `start` but not `finish` in the example above)
+5. add the object's current state to its `past_states` history
+6. set the object's `state` to the target state given as `:to`
+7. set the object's `[state]_at` attribute to `Time.now` if the object defines a writer for it
+8. run `:after` callbacks (if given)
+
+You can define options for all events like so:
+
+    event :finish, :to => :finished, :after => :cleanup
+    event :all, :after => :notify
+
+This will call :cleanup first and then :notify on :finish.
+
+If no target state was given for an event then SimpleStates will try to derive
+it from the states list. I.e. for an event `start` it will check the states
+list for a state `started` and use it. If it can not find a target state this
+way then it will raise an exception.

data/lib/simple_states/event.rb

@@ -43,16 +43,12 @@ module SimpleStates
       def skip?(object, args)
         result = false
         result ||= !send_methods(object, options.if, args) if options.if?
-        result ||= send_methods(object, options.except, args) if options.except?
+        result ||= send_methods(object, options.unless, args) if options.unless?
         result
       end
 
       def can_transition?(object)
-        object.state && Array(options.from).include?(object.state)
-      end
-
-      def raise_invalid_transition(object)
-        raise TransitionException, "#{object.inspect} can not receive event #{name.inspect} while in state #{object.state.inspect}."
+        !options.from || object.state && Array(options.from).include?(object.state)
       end
 
       def run_callbacks(object, type, args)
@@ -60,7 +56,7 @@ module SimpleStates
       end
 
       def set_state(object)
-        if state = options.to
+        if state = target_state(object)
           object.past_states << object.state if object.state
           object.state = state.to_sym
           object.send(:"#{state}_at=", Time.now) if object.respond_to?(:"#{state}_at=")
@@ -68,6 +64,12 @@ module SimpleStates
         end
       end
 
+      def target_state(object)
+        options.to || :"#{name}ed".tap do |state|
+          raise_unknown_target_state(object) unless object.class.states.include?(state)
+        end
+      end
+
       def send_methods(object, methods, args)
         Array(methods).inject(false) { |result, method| result | send_method(object, method, args) } if methods
       end
@@ -83,5 +85,13 @@ module SimpleStates
       def arity(object, method)
         object.class.instance_method(method).arity rescue 0
       end
+
+      def raise_invalid_transition(object)
+        raise TransitionException, "#{object.inspect} can not receive event #{name.inspect} while in state #{object.state.inspect}."
+      end
+
+      def raise_unknown_target_state(object)
+        raise TransitionException, "can not find target state for #{object.inspect} for event #{name.inspect}."
+      end
   end
 end

data/lib/simple_states/version.rb

@@ -1,3 +1,3 @@
 module SimpleStates
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: simple_states
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2011-08-04 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &70306211479800 !ruby/object:Gem::Requirement
+  requirement: &70366831755540 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70306211479800
+  version_requirements: *70366831755540
 - !ruby/object:Gem::Dependency
   name: hashr
-  requirement: &70306211479060 !ruby/object:Gem::Requirement
+  requirement: &70366831754780 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: 0.0.10
   type: :runtime
   prerelease: false
-  version_requirements: *70306211479060
+  version_requirements: *70366831754780
 - !ruby/object:Gem::Dependency
   name: test_declarative
-  requirement: &70306211478360 !ruby/object:Gem::Requirement
+  requirement: &70366831754080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70306211478360
+  version_requirements: *70366831754080
 - !ruby/object:Gem::Dependency
   name: mocha
-  requirement: &70306211477140 !ruby/object:Gem::Requirement
+  requirement: &70366831752860 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,7 +54,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70306211477140
+  version_requirements: *70366831752860
 description: ! '[description]'
 email: svenfuchs@artweb-design.de
 executables: []