davidlee-state-fu 0.11.1 → 0.12.0

data/README.textile

@@ -1,49 +1,138 @@
-h1. State-Fu
+h1. StateFu
 
 h2. What is it?
 
-State-Fu is:
+StateFu is another Ruby state machine.
 
- * a generalized, extensible framework for state-oriented,
-   event-driven programming in Ruby.
+h2. What is a state machine?
 
- * a rich DSL for describing workflows, rules engines, behaviours and
-   processes
+Finite state machines are a model for program behaviour; like
+object-oriented programming, they provide an abstract way to think
+about a domain.
 
- * useful both as a Rails plugin, and in standalone ruby programs
-   without any additional dependencies.
+In a finite state machine, there are a number of discrete states. Only
+one state may be occupied at any given time (hence the "finite").
 
-It lets you describe:
+States are linked together by events, and there are rules which govern
+when or how transitions between states can occur. Actions may be fired
+on entry to or exit from a state, or when a certain transition occurs.
 
- * series of discrete states
+h2. Why is StateFu different to the other twenty state machines for Ruby?
 
- * events which allow transitions to occur between states
+State machines are potentially a powerful way to simplify and
+structure a lot of problems. They can be used to:
 
- * rules (requirements) about when these transitions can occur
+ * succinctly define the grammar of a networking protocol or a
+   configuration DSL
 
- * behaviours which occur when they do
+ * clearly and compactly describe complex logic, which might otherwise
+   be difficult to understand by playing "follow the rabbit" through
+   methods thick with implementation details
 
-Which adds up to a surprisingly useful way to skin a lot of
-problems
+ * serialize and process multiple revisions of changing business rules
 
-Other libraries exist for ruby which do some or all of these
-things. "What's different about State-Fu?", you may ask.
+ * provide an abstract representation of program or domain behaviour
+   which can be introspected, edited, queried and executed on the fly,
+   in a high-level and human-readable format
 
-h2. Why StateFu is not your grandmother's state machine
+ * provide a straightforward and easy way to record and validate
+   "status" information, especially when there are rules governing
+   when and how it can be updated
 
-h3. Flippant answer:
+ * reduce proliferation of classes and modules, or easily define and
+   control functionally related groups of objects, by defining
+   behaviours on interacting components of a state machine
 
-Those libraries you've played with are toys. They're made of
-plastic. State-Fu is forged from a reassuringly dense but
-unidentifiable metal which comes only from the rarest of meteorites,
-and it ticks when you hold it up to your ear.[1]
+ * elegantly implement simple building blocks like stacks / queues,
+   parsers, schedulers, automata, etc
 
-State-Fu is elegant, powerful and transparent enough that you can use
+StateFu was written from the ground up with one goal in mind: to be
+over-engineered. It is designed to make truly ambitious use of state
+machines not only viable, but strongly advantageous in many situations.
+
+It is designed in the very opposite vein to the intentional minimalism
+of most ruby state machine projects; it is tasked with taking on a
+great deal of complexity and functionality, and abstracting it behind
+a nice DSL, so that the code which *you* have to maintain is shorter and
+clearer.
+
+StateFu allows you to:
+
+ * give a class any number of machines
+
+ * define behaviours on state entry / exit; before, after or during
+   execution of a particular event; or before / after every transition
+   in a given machine
+
+ * give any object own its own private, "singleton" machines,
+   which are unique to that object and modifiable at runtime.
+
+ * create events with any number of origin or target states
+
+ * define and query guard conditions / transition requirements,
+  to establish rules about when a transition is valid
+
+ * use powerful reflection and logging capabilities to easily expose
+   and debug the operation of your machines
+
+ * automatically and unobtrusively define methods for querying each
+   state and event, and for firing transitions
+
+ * easily find out which transitions are valid at any given time
+
+ * generate descriptive, contextual messages when a transition is
+   invalid
+
+ * halt a transition during execution
+
+ * easily extend StateFu's DSL to match the problem domain
+
+ * fire transitions with a payload of arguments and program context,
+   which is available to guard conditions, event hooks, and
+   requirement messages when they are evaluated
+
+ * use a lovely, simple and flexible API which gives you plenty of
+   choices about how to describe your problem domain; choose (or
+   build) a programming style which suits the task at hand from an
+   expressive range of options
+
+ * store arbitrary meta-data on any component of StateFu - a simple
+   but extremely powerful tool for integration with almost anything.
+
+ * flexible and helpful logging out of the box - will use the Rails
+   logger if you're in a Rails project, or standalone logging to
+   STDOUT or a file. Configurable loglevel and message prefixes help
+   StateFu be a good citizen in a shared application log.
+
+ * automatically generate diagrams of state machines / workflows with graphviz
+
+ * use an ActiveRecord field for state persistence, or a regular
+   attribute - or use both, on the same class, for different
+   machines. If an appropriate ActiveRecord field exists for a
+   machine, it will be used. Otherwise, an attr_accessor will be used
+   (and created, if necessary).
+
+ * customising the persistence mechanism (eg to use a Rails session,
+   or a text file, or your choice of ORM) is usually as easy as
+   defining a getter and setter method for the persistence field, and
+   a rule about when to use it. If you want to use StateFu with a
+   persistence mechanism which is not yet supported, send me a message.
+
+ * StateFu is fast, lightweight and useful enough to use in any ruby
+   project - works with Rails but does not require it.
+
+h2. Still not sold?
+
+StateFu is forged from a reassuringly dense but unidentifiable metal
+which comes only from the rarest of meteorites, and it ticks when you
+hold it up to your ear.[1]
+
+It is elegant, powerful and transparent enough that you can use
 it to drive substantial parts of your application, and actually want
 to do so.
 
 It is designed as a library for authors, as well as users, of
-libraries: State-Fu goes to great lengths to impose very few limits on
+libraries: StateFu goes to great lengths to impose very few limits on
 your ability to introspect, manipulate and extend the core features.
 
 It is also delightfully elegant and easy to use for simple things:
@@ -97,124 +186,7 @@ It is also delightfully elegant and easy to use for simple things:
 
 </code></pre>
 
-h3. Feature Comparison and Detailed Answer
-
-A few of the features which set State-Fu apart for more ambitious work are:
-
- * a lovely, simple and flexible API gives you plenty of choices about
-   how to describe your problem domain.
-
- * define any number of workflows on the same object / model;
-   workflows (Machines) can be entirely separate, or interact with
-   each other. Re-use machines across multiple classes, serialize them
-   to a database, or build them on the fly.
-
- * events can transition from / to any number of states
-
- * drive application behaviour with a rich set of event hooks
-
- * define behaviour as methods on your objects, or keep it all in the
-   state machine itself
-
- * requirements determine at runtime whether a particular state
-   transition can occur, and if not, can tell a user (or developer)
-   what they must do to satisfy the requirements.
-
- * requirement failure messages can be generated at runtime, making
-   use of whatever application and state-machine context they need
-
- * transitions can be halted mid-execution, and you can actually
-   determine why, and where from
-
- * in every event hook, requirement filter, and other method calls,
-   you have complete and consistent access to your classes, its
-   StateFu::Machines, and any Transition context. Use real ruby code
-   anywhere, without breathing through a straw!
-
- * extend State-Fu (with Lathe#helper) Binding and Transition
-   instances for your Machine to define your a DSL customized for your
-   problem domain, and to keep your class definitions clean. Helper
-   methods have easy access to all the context associated with your
-   object instance, its StateFu::Machines and any Transition in
-   progress.
-
- * extend a State-Fu Lathe (with Lathe#tool) to keep your Machine
-   definitions DRY
-
- * store arbitrary meta-data on any component of State-Fu - a simple
-   but extremely powerful tool for integration with almost anything.
-
- * designed for transparency, introspection and ease of debugging,
-   which means a dynamic, powerful system you can actually use without
-   headaches.
-
- * flexible and helpful logging out of the box - will use the Rails
-   logger if you're in a Rails project, or standalone logging to
-   STDOUT or a file. Configurable loglevel and message prefixes help
-   StateFu be a good citizen in a shared application log.
-
- * magically generate diagrams of state machines / workflows with graphviz
-
- * "magically" use an ActiveRecord field for state persistence, or just an
-   attribute - or use both, on the same class, for different
-   workflows. If an ActiveRecord field exists for a machine's
-   field_name (by default, the machine's name suffixed with '_field';
-   the default machine name is 'state_fu', so if you don't explicitly
-   name a machine it will look for 'state_fu_field' in your
-   ActiveRecord columns (if ActiveRecord is included) and use
-   that. Otherwise, an attr_accessor will be used (and created, if
-   necessary).
-
- * customising the persistence mechanism (eg to use a Rails session,
-   or a text file, or your choice of ORM) is usually as easy as
-   defining a getter and setter method for the persistence field, and
-   a rule about when to use it. If you want to use StateFu with a
-   persistence mechanism which is not yet supported, I'd like to hear
-   about it.
-
- * fast, lightweight and useful enough to use in any ruby
-   project - works with Rails but does not require it.
-
-State-Fu works with any modern Ruby ( 1.8.6, 1.8.7, and 1.9.1)
-
-fn1. No disrespect intended to the authors of other similar libraries
-- some of whom I've borrowed an idea or two, and some useful criticism,
-from. They're stand-up guys, all of them. It's the truth though.
-
-I'd like to thank Ryan Allen in particular for his Workflow library,
-which I previously forked, piled hundreds of lines of code into and renamed
-Stateful (now deprecated). Some of his ideas (for example the ability to store metadata
-easily on *everything* ) have been instrumental in State-Fu's design.
-
-I'd also like to tip my hat at John Barnette, who's own
-(coincidentally named) Stateful set a very high standard with an
-exceptionally elegant API.
-
-h3. StateFu is not a complete BPM (Business Process Management) platform
-
-It's worth noting that StateFu is at it's core a state machine, which
-strives to be powerful enough to be able to drive many kinds of
-application behaviour.
-
-It is not, however, a "proper" workflow engine on par with Ruote. In
-StateFu the basic units with which "workflows" are built are states
-and events; Ruote takes a higher level view, dealing with processes
-and participants. As a result, it's capable of directly implementing
-these design patterns:
-
-http://openwferu.rubyforge.org/patterns.html
-
-Whereas StateFu cannot, for example, readily model forking / merging
-of processes (nor does it handles scheduling, process management, etc.
-
-The author of Ruote, the Ruby Workflow Engine, outlines the difference
-pretty clearly here:
-
-http://jmettraux.wordpress.com/2009/07/03/state-machine-workflow-engine/
-
-If your application can be described with StateFu, you'll likely find
-it simpler to get running and work with; if not, you may find Ruote,
-or a combination of the two, suits your needs perfectly.
+StateFu works with any modern Ruby ( 1.8.6, 1.8.7, and 1.9.1)
 
 h2. Getting started
 
@@ -276,6 +248,7 @@ dependent libraries.
 So if you plan to use ActiveSupport in a stand-alone project with
 StateFu, you should require it before StateFu.
 
+
 h3. Addditional Resources
 
 Also see the "issue tracker":http://github.com/davidlee/state-fu/issues
@@ -284,10 +257,36 @@ And the "build monitor":http://runcoderun.com/davidlee/state-fu/
 
 And the "RDoc":http://rdoc.info/projects/davidlee/state-fu
 
+
+h3. StateFu is not a complete BPM (Business Process Management) platform
+
+It's worth noting that StateFu is at it's core a state machine, which
+strives to be powerful enough to be able to drive many kinds of
+application behaviour.
+
+It is not, however, a classical workflow engine on par with Ruote. In
+StateFu the basic units with which "workflows" are built are states
+and events; Ruote takes a higher level view, dealing with processes
+and participants. As a result, it's capable of directly implementing
+these design patterns:
+
+http://openwferu.rubyforge.org/patterns.html
+
+Whereas StateFu cannot, for example, readily model forking / merging
+of processes (nor does it handles scheduling, process management, etc.
+
+The author of Ruote, the Ruby Workflow Engine, outlines the difference
+pretty clearly here:
+
+http://jmettraux.wordpress.com/2009/07/03/state-machine-workflow-engine/
+
+If your application can be described with StateFu, you'll likely find
+it simpler to get running and work with; if not, you may find Ruote,
+or a combination of the two, suits your needs perfectly.
+
 h3. Thanks
 
- * dsturnbull, for helping w/ a patch to stop an error being raised
-   when an activerecord model has no database table
+ * dsturnbull, for patches
 
  * lachie, benkimball for pointing out README bugs / typos
 

data/lib/binding.rb

@@ -3,13 +3,12 @@ module StateFu
 
     attr_reader :object, :machine, :method_name, :field_name, :persister, :transitions, :options, :target
 
-
     # the constructor should not be called manually; a binding is
     # returned when an instance of a class with a StateFu::Machine
     # calls:
     #
     # instance.#state_fu (for the default machine which is called :state_fu),
-    # instance.#state_fu( :<machine_name> ) ,or
+    # instance.#state_fu(:<machine_name>) ,or
     # instance.#<machine_name>
     #
     def initialize( machine, object, method_name, options={} )
@@ -18,13 +17,18 @@ module StateFu
       @method_name   = method_name
       @transitions   = []
       @options       = options.symbolize_keys!
-      @target        = singleton? ? object : object.class
-      @field_name    = options[:field_name] || @target.state_fu_field_names[method_name]
-      @persister     = Persistence.for( self )
+      if options[:singleton]
+        @target      = object
+      else 
+        @target      = object.class
+        @options     = @target.state_fu_options[@method_name].merge(options)
+      end 
+      @field_name    = @options[:field_name] || raise("No field_name supplied in #{@options.inspect}")      
+      @persister     = Persistence.for self
 
       # define event methods on this binding and its @object
-      MethodFactory.new( self ).install!
-      @machine.helpers.inject_into( self )
+      MethodFactory.new(self).install!
+      @machine.helpers.inject_into self 
     end
 
     alias_method :o,             :object
@@ -60,26 +64,26 @@ module StateFu
 
     #
     # These methods are called from methods defined by MethodFactory.
-    # 
-    
+    #
+
     # event_name [target], *args
     #
     def find_transition(event, target=nil, *args)
-      target ||= args.last[:to].to_sym rescue nil      
+      target ||= args.last[:to].to_sym rescue nil
       query = transitions.for_event(event).to(target).with(*args)
-      query.find || query.valid.singular || nil 
+      query.find || query.valid.singular || nil
     end
 
     # event_name? [target], *args
     #
     def can_transition?(event, target=nil, *args)
       begin
-        if t = find_transition(event, target, *args) 
+        if t = find_transition(event, target, *args)
           t.valid?(*args)
         end
       rescue IllegalTransition, UnknownTarget
         nil
-      end      
+      end
     end
 
     # event_name! [target], *args
@@ -100,7 +104,7 @@ module StateFu
     end
     alias_method :events_from_current_state,  :events
 
-    # all states which can be reached from the current_state. 
+    # all states which can be reached from the current_state.
     # Does not check transition requirements, etc.
     def next_states
       events.map(&:targets).compact.flatten.uniq.extend StateArray
@@ -125,11 +129,11 @@ module StateFu
     def valid_events(*args)
       valid_transitions(*args).events
     end
-    
+
     def invalid_events(*args)
       (events - valid_events(*args)).extend StateArray
     end
-    
+
 
     # initializes a new Transition to the given destination, with the
     # given *args (to be passed to requirements and hooks).
@@ -139,17 +143,17 @@ module StateFu
     def transition( event_or_array, *args, &block )
       return transitions.with(*args, &block).find(event_or_array)
     end
-    
+
     #
     # next_transition and friends: when there's exactly one valid move
     #
-    
+
     # if there is exactly one legal & valid transition which can be fired with
     # the given (optional) arguments, return it.
     def next_transition( *args, &block )
       transitions.with(*args, &block).next
     end
-    
+
     # as above but ignoring any transitions whose origin and target are the same
     def next_transition_excluding_cycles( *args, &block )
       transitions.not_cyclic.with(*args, &block).next
@@ -158,7 +162,7 @@ module StateFu
     # if there is exactly one state reachable via a transition which
     # is valid with the given optional arguments, return it.
     def next_state(*args, &block)
-      transitions.with(*args, &block).next_state 
+      transitions.with(*args, &block).next_state
     end
 
     # if there is exactly one event which is valid with the given
@@ -166,7 +170,7 @@ module StateFu
     def next_event( *args )
       transitions.with(*args, &block).next_event
     end
-    
+
     # if there is a next_transition, create, fire & return it
     # otherwise raise an IllegalTransition
     def next!( *args, &block )
@@ -179,7 +183,7 @@ module StateFu
     alias_method :next_transition!, :next!
     alias_method :next_event!, :next!
     alias_method :next_state!, :next!
-  
+
     # if there is a next_transition, return true / false depending on
     # whether its requirements are met
     # otherwise, nil
@@ -222,6 +226,14 @@ module StateFu
       end
     end
 
+    # next! without the raise if there's no next transition
+    # TODO SPECME
+    def update!( *args, &block )
+      if t = next_transition( *args, &block )
+        t.fire!
+      end
+    end
+
     #
     # misc
     #
@@ -260,7 +272,7 @@ module StateFu
       options[:singleton]
     end
 
-    # SPECME DOCME OR KILLME 
+    # SPECME DOCME OR KILLME
     def reload()
       if persister.is_a?( Persistence::ActiveRecord )
         object.reload
@@ -272,13 +284,13 @@ module StateFu
     def inspect
       s = self.to_s
       s = s[0,s.length-1]
-      s << " object=#{object}" 
-      s << " current_state=#{current_state.to_sym.inspect rescue nil}" 
-      s << " events=#{events.map(&:to_sym).inspect rescue nil}" 
-      s << " machine=#{machine.to_s}" 
+      s << " object=#{object}"
+      s << " current_state=#{current_state.to_sym.inspect rescue nil}"
+      s << " events=#{events.map(&:to_sym).inspect rescue nil}"
+      s << " machine=#{machine.to_s}"
       s << ">"
       s
     end
-    
+
   end
 end

data/lib/event.rb

@@ -65,7 +65,7 @@ module StateFu
     end
     
     def cycle?
-      origin && origin == target
+      origin && (origin == target)
     end
 
     # *adds to* the origin states given a list of symbols / States

data/lib/executioner.rb

@@ -3,17 +3,7 @@ module StateFu
   # delegator class for evaluation methods / procs in the context of
   # your object.
   #
-  
-  # There's a bug in ruby 1.8.x where lambda {}.arity == -1 instead of 0
-  # To get around this, turn it into a proc if conditions are dangerous.
-  def self.get_effective_arity
-    if RUBY_VERSION[0,3] == "1.8" && proc.arity == -1
-      proc.to_proc.arity
-    else
-      proc.arity
-    end    
-  end
-  
+    
   class Executioner
 
     # give us a blank slate
@@ -29,8 +19,6 @@ module StateFu
       self
     end
 
-    # delegate :self, :to => :__target__
-
     delegate :origin,  :to => :transition, :prefix => true # transition_origin
     delegate :target,  :to => :transition, :prefix => true # transition_target
     delegate :event,   :to => :transition, :prefix => true # transition_event
@@ -45,10 +33,10 @@ module StateFu
 
     attr_reader :transition, :__target__, :__self__
 
-    alias_method :t,                  :transition
-    alias_method :current_transition, :transition
-    alias_method :context,            :transition
-    alias_method :ctx,                :transition
+    alias_method :t,                    :transition
+    alias_method :current_transition,   :transition
+    alias_method :context,              :transition
+    alias_method :ctx,                  :transition
 
     alias_method :arguments,            :args
     alias_method :transition_arguments, :args
@@ -112,7 +100,7 @@ module StateFu
     private
 
     # Forwards any missing method call to the \target.
-    # TODO / FIXME / NOTE: we don't (can't ?) handle block arguments ...    
+    # TODO / NOTE: we don't (can't ?) handle block arguments ...    
     def method_missing(method_name, *args)
       if __target__.respond_to?(method_name, true)
         begin
@@ -126,13 +114,7 @@ module StateFu
       end
       
     end
-
-    # # Forwards any missing constant references to the \target.
-    # def self.const_missing(const_name)
-    #   unless __target__.class.const_defined?(const_name, true)
-    #     super(const_name)
-    #   end
-    #   __target__.class.const_get(const_name)
-    # end
+    
+    # NOTE: const_missing is not handled.
   end
 end

data/lib/interface.rb

@@ -2,21 +2,19 @@ module StateFu
   module Interface
     module SoftAlias
 
-      # define aliases that won't clobber existing methods - 
-      # so we can be liberal with them.
-      def soft_alias(x)
-        aliases  = [ x.to_a[0] ].flatten
-        original = aliases.shift
+      def soft_alias(hash)
         existing_method_names = (self.instance_methods | self.protected_instance_methods | self.private_instance_methods).map(&:to_sym)
-        taken, ok = aliases.partition { |a| existing_method_names.include?(a.to_sym) }
-        StateFu::Logger.debug("#{self.to_s} alias for ## #{original} already taken: #{taken.inspect}")  unless taken.empty?
-        ok.each { |a| alias_method a, original}
-      end
-      
+        hash.each do |original, aliases|
+          aliases.
+            reject { |a| existing_method_names.include?(a.to_sym) }.
+            each { |a| alias_method a, original}
+        end
+      end      
     end
 
     module Aliases
-
+      # define aliases that won't clobber existing methods - 
+      # so we can be liberal with them.
       def self.extended(base)
         base.extend SoftAlias
         base.class_eval do
@@ -70,8 +68,8 @@ module StateFu
       end
       alias_method :machine, :state_fu_machine
 
-      def state_fu_field_names
-        @_state_fu_field_names ||= {}
+      def state_fu_options
+        @_state_fu_options ||= {}
       end
 
       def state_fu_machines
@@ -97,7 +95,7 @@ module StateFu
       # can access a StateFu::Machine, the object's current state, the
       # methods which trigger event transitions, etc.
 
-      def state_fu_binding( name = DEFAULT )
+      def state_fu_binding(name = DEFAULT)
         name = name.to_sym 
         if machine = self.class.state_fu_machines[name]
           state_fu_bindings[name] ||= StateFu::Binding.new( machine, self, name )