davidlee-state-fu 0.2.0 → 0.3.1

data/README.textile

@@ -126,6 +126,8 @@ A few of the features which set State-Fu apart for more ambitious work are:
    which means a dynamic, powerful system you can actually use without
    headaches
 
+ * magically generate diagrams of state machines / workflows with graphviz
+
  * fast, lightweight and useful enough to use in any ruby
    project - works with Rails but does not require it.
 
@@ -194,7 +196,9 @@ ActiveSupport (e.g. ActiveRecord), you may have to explicitly
 <code>require 'activesupport'</code> before loading the dependent
 libraries.
 
-
 Also see the "issue tracker":http://github.com/davidlee/state-fu/issues
 
-And the "build monitor":http://runcoderun.com/davidlee/state-fu/
+And the "build monitor":http://runcoderun.com/davidlee/state-fu/
+
+And the "RDoc":http://rdoc.info/projects/davidlee/state-fu/ , which
+needs a bit of love.

data/Rakefile

@@ -38,9 +38,6 @@ rescue LoadError
 end
 
 namespace :spec do
-  desc "Run both units and integration specs"
-  task :both => [:units, :integration]
-
   desc "Run all specs"
   Spec::Rake::SpecTask.new(:all) do |t|
     t.spec_files = FileList["spec/**/*_spec.rb"]
@@ -72,6 +69,21 @@ namespace :spec do
     exec 'autospec'
   end
 
+    def find_last_modified_spec
+    require 'find'
+    specs = []
+    Find.find( File.expand_path(File.join(File.dirname(__FILE__),'spec'))) do |f|
+      next unless f !~ /\.#/ && f =~ /_spec.rb$/
+      specs << f
+    end
+    spec = specs.sort_by { |spec| File.stat( spec ).mtime }.last
+  end
+
+  desc "runs the last modified spec, without mucking about"
+  Spec::Rake::SpecTask.new(:last) do |t|
+    t.spec_opts = ['--options', "\"#{File.dirname(__FILE__)}/spec/spec.opts\""]
+    t.spec_files = FileList[find_last_modified_spec]
+  end
 end
 
 desc 'Runs irb in this project\'s context'
@@ -84,4 +96,13 @@ task :doc do |t|
   exec 'rdoc lib/'
 end
 
+begin
+  require 'cucumber/rake/task'
+
+  Cucumber::Rake::Task.new(:features) do |t|
+      t.cucumber_opts = "--format pretty"
+  end
+rescue LoadError => e
+end
+
 task :default => 'spec:all'

data/lib/no_stdout.rb

@@ -1,10 +1,15 @@
 require 'stringio'
 
+# a module for suppressing or capturing STDOUT or STDERR.
+# useful when shelling out to "noisy" applications or to suppress
+# output during tests.
 module NoStdout
   module InstanceMethods
 
+    # Suppresses or redirects STDOUT inside the given block.
+    # supply an IO of your own to capture STDOUT, otherwise it's put
+    # in a new StringIO object.
     def no_stdout ( to = StringIO.new('','r+'), &block )
-      # supply an IO of your own to capture STDOUT, otherwise it's put in a StringIO
       orig_stdout  = $stdout
       $stdout      = @alt_stdout = to
       result       = yield
@@ -12,21 +17,39 @@ module NoStdout
       result
     end
 
+    # returns the contents of STDOUT from the previous usage of
+    # no_stdout, or nil
     def last_stdout
       return nil unless @alt_stdout
       @alt_stdout.rewind
       @alt_stdout.read
     end
 
+    ## COPIED FROM ABOVE ####
+
+    # Suppresses or redirects STDERR inside the given block.
+    # supply an IO of your own to capture STDERR, otherwise it's put
+    # in a new StringIO object.
+    def no_stderr ( to = StringIO.new('','r+'), &block )
+      orig_stderr  = $stderr
+      $stderr      = @alt_stderr = to
+      result       = yield
+      $stderr      = orig_stderr
+      result
+    end
+
+    # returns the contents of STDERR from the previous usage of
+    # no_stderr, or nil
+    def last_stderr
+      return nil unless @alt_stderr
+      @alt_stderr.rewind
+      @alt_stderr.read
+    end
   end
 
-  # TODO - explain / remember why this has two class_eval blocks -
-  # should one be an extend?
   def self.included klass
     klass.class_eval do
       include InstanceMethods
     end
-    klass.extend InstanceMethods
   end
-
 end

data/lib/state-fu.rb

@@ -50,33 +50,37 @@
 #                                         # the author requirement prevented the transition
 #  my_doc.status.name      => :draft      # see? still a draft.
 #  my_doc.author = "Susan"                # so let's satisfy it ...
-#  my_doc.publish!                        # and try again.
+#  my_doc.publish!                        # and try again
 #  "new feed!"                            # aha - our event hook fires!
 #  my_doc.status.name      => :published  # and the state has been updated.
 
 require 'rubygems'
 # require 'activesupport'
 
-require 'state_fu/core_ext'
-require 'state_fu/logger'
-require 'state_fu/helper'
-require 'state_fu/exceptions'
-require 'state_fu/fu_space'
-require 'state_fu/machine'
-require 'state_fu/lathe'
-require 'state_fu/method_factory'
-require 'state_fu/binding'
-require 'state_fu/persistence'
-require 'state_fu/persistence/base'
-require 'state_fu/persistence/active_record'
-require 'state_fu/persistence/attribute'
-require 'state_fu/sprocket'
-require 'state_fu/state'
-require 'state_fu/event'
-require 'state_fu/hooks'
-require 'state_fu/interface'
-require 'state_fu/transition'
-require 'state_fu/mock_transition'
+[ 'core_ext',
+  'logger',
+  'helper',
+  'exceptions',
+  'fu_space',
+  'machine',
+  'lathe',
+  'method_factory',
+  'binding',
+  'persistence',
+  'persistence/base',
+  'persistence/active_record',
+  'persistence/attribute',
+  'persistence/relaxdb',
+  'sprocket',
+  'state',
+  'event',
+  'hooks',
+  'interface',
+  'transition',
+  'mock_transition',
+  'plotter' ].each do |lib|
+  require File.expand_path( File.join( File.dirname(__FILE__), 'state_fu', lib ))
+end
 
 module StateFu
   DEFAULT_MACHINE    = :state_fu

data/lib/state_fu/active_support_lite/misc.rb

@@ -0,0 +1,57 @@
+class Object
+  # Returns +value+ after yielding +value+ to the block. This simplifies the
+  # process of constructing an object, performing work on the object, and then
+  # returning the object from a method. It is a Ruby-ized realization of the K
+  # combinator, courtesy of Mikael Brockman.
+  #
+  # ==== Examples
+  #
+  #  # Without returning
+  #  def foo
+  #    values = []
+  #    values << "bar"
+  #    values << "baz"
+  #    return values
+  #  end
+  #
+  #  foo # => ['bar', 'baz']
+  #
+  #  # returning with a local variable
+  #  def foo
+  #    returning values = [] do
+  #      values << 'bar'
+  #      values << 'baz'
+  #    end
+  #  end
+  #
+  #  foo # => ['bar', 'baz']
+  #  
+  #  # returning with a block argument
+  #  def foo
+  #    returning [] do |values|
+  #      values << 'bar'
+  #      values << 'baz'
+  #    end
+  #  end
+  #  
+  #  foo # => ['bar', 'baz']
+  def returning(value)
+    yield(value)
+    value
+  end
+
+  # Yields <code>x</code> to the block, and then returns <code>x</code>.
+  # The primary purpose of this method is to "tap into" a method chain,
+  # in order to perform operations on intermediate results within the chain.
+  #
+  #   (1..10).tap { |x| puts "original: #{x.inspect}" }.to_a.
+  #     tap    { |x| puts "array: #{x.inspect}" }.
+  #     select { |x| x%2 == 0 }.
+  #     tap    { |x| puts "evens: #{x.inspect}" }.
+  #     map    { |x| x*x }.
+  #     tap    { |x| puts "squares: #{x.inspect}" }
+  def tap
+    yield self
+    self
+  end unless Object.respond_to?(:tap)
+end

data/lib/state_fu/binding.rb

@@ -4,6 +4,14 @@ module StateFu
 
     attr_reader :object, :machine, :method_name, :persister, :transitions, :options
 
+    # 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.#<machine_name>
+    #
     def initialize( machine, object, method_name, options={} )
       @machine       = machine
       @object        = object
@@ -17,7 +25,7 @@ module StateFu
       StateFu::Persistence.prepare_field( object.class, field_name )
       # add a persister
       @persister     = StateFu::Persistence.for( self, field_name )
-      Logger.info( "Persister (#{@persister.class}) added: #{method_name} as field #{field_name}" )
+      Logger.debug( "Persister (#{@persister.class}) added: #{method_name} as field #{field_name}" )
 
       # define event methods on self( binding ) and @object
       StateFu::MethodFactory.new( self ).install!
@@ -33,10 +41,12 @@ module StateFu
     alias_method :workflow,      :machine
     alias_method :state_machine, :machine
 
+    # the perister's field_name (a symbol)
     def field_name
       persister.field_name
     end
 
+    # the current_state, as maintained by the persister.
     def current_state
       persister.current_state
     end
@@ -44,6 +54,7 @@ module StateFu
     alias_method :now,   :current_state
     alias_method :state, :current_state
 
+    # the name, as a Symbol, of the binding's current_state
     def current_state_name
       begin
         current_state.name.to_sym
@@ -55,19 +66,22 @@ module StateFu
     alias_method :state_name, :current_state_name
     alias_method :to_sym,     :current_state_name
 
-    # a list of events which can fire from the current_state
+    # returns a list of StateFu::Events which can fire from the current_state
     def events
       machine.events.select {|e| e.complete? && e.from?( current_state ) }.extend EventArray
     end
     alias_method :events_from_current_state,  :events
 
     # the subset of events() whose requirements for firing are met
+    # (with the arguments supplied, if any)
     def valid_events( *args )
       return nil unless current_state
       return [] unless current_state.exitable_by?( self, *args )
       events.select {|e| e.fireable_by?( self, *args ) }.extend EventArray
     end
 
+    # the subset of events() whose requirements for firing are NOT met
+    # (with the arguments supplied, if any)
     def invalid_events( *args )
       ( events - valid_events( *args ) ).extend StateArray
     end
@@ -84,6 +98,7 @@ module StateFu
       vt && vt.values.flatten.uniq.extend( StateArray )
     end
 
+    #
     def next_states
       events.map(&:targets).compact.flatten.uniq.extend StateArray
     end
@@ -101,7 +116,11 @@ module StateFu
       h
     end
 
-    # initialize a new transition
+    # initializes a new Transition to the given destination, with the
+    # given *args (to be passed to requirements and hooks).
+    #
+    # If a block is given, it yields the Transition or is executed in
+    # its evaluation context, depending on the arity of the block.
     def transition( event_or_array, *args, &block )
       event, target = parse_destination( event_or_array )
       StateFu::Transition.new( self, event, target, *args, &block )
@@ -112,17 +131,24 @@ module StateFu
     alias_method :trigger_event,    :transition
     alias_method :begin_transition, :transition
 
+    # return a MockTransition to nowhere and passes it the given
+    # *args. Useful for evaluating requirements in spec / test code.
     def blank_mock_transition( *args, &block )
       StateFu::MockTransition.new( self, nil, nil, *args, &block )
     end
 
+    # return a MockTransition; otherwise the same as #transition
     def mock_transition( event_or_array, *args, &block )
       event, target = nil
       event, target = parse_destination( event_or_array )
       StateFu::MockTransition.new( self, event, target, *args, &block )
     end
 
-    # sanitize args for fire! and fireable?
+    # sanitizes / extracts destination from *args for other methods.
+    #
+    # takes a single, simple (one target only) event,
+    # or an array of [event, target],
+    # or one of the above with symbols in place of the objects themselves.
     def parse_destination( event_or_array )
       case event_or_array
       when StateFu::Event, Symbol
@@ -138,7 +164,8 @@ module StateFu
       [event, target]
     end
 
-    # check that the event and target are "valid" (all requirements met)
+    # check that the event and target are valid (all requirements are
+    # met) with the given (optional) arguments
     def fireable?( event_or_array, *args )
       event, target = parse_destination( event_or_array )
       begin
@@ -176,47 +203,17 @@ module StateFu
     # and its arity - see helper.rb (ContextualEval) for the smarts
 
     # TODO - enable requirement block / method to know the target
-    def evaluate_requirement( name )
-      puts "DEPRECATED: evaluate_requirement #{name}"
-      evaluate_requirement_with_args( name )
-    end
 
     def evaluate_requirement_with_args( name, *args )
       t = blank_mock_transition( *args )
       evaluate_named_proc_or_method( name, t )
     end
+    # alias_method :evaluate_requirement, :evaluate_requirement_with_args
 
-    def evaluate_requirement_with_transition( name, t )
-      evaluate_named_proc_or_method( name, t )
-    end
+    alias_method :evaluate_requirement_with_transition, :evaluate_named_proc_or_method
 
-    # TODO SPECME HACKERY CRUFT FIXME THISSUCKS and needs *args
-    # def evaluate_requirement_message( name, dest )
-    #   # puts "#{name} #{dest}"
-    #   msg = machine.requirement_messages[name]
-    #   if [String, NilClass].include?( msg.class )
-    #     return msg
-    #   else
-    #     if dest.is_a?( StateFu::Transition )
-    #       t = dest
-    #     else
-    #       event, target = parse_destination( event_or_array )
-    #       t = transition( event, target )
-    #     end
-    #     case msg
-    #     when Symbol, Proc
-    #       puts t.class
-    #       evaluate_named_proc_or_method( msg, t )
-    #     # when Proc
-    #     #   t.evaluate &msg
-    #     end
-    #   end
-    # end
-
-    # if there is one simple event, return a transition for it
-    # else return nil
-    # TODO - not convinced about the method name / aliases - but next
-    # is reserved :/
+    # if there is exactly one legal transition which can be fired with
+    # the given (optional) arguments, return it.
     def next_transition( *args, &block )
       vts = valid_transitions( *args )
       return nil if vts.nil?
@@ -229,11 +226,15 @@ module StateFu
       end
     end
 
+    # if there is exactly one state reachable via a transition which
+    # is valid with the given optional arguments, return it.
     def next_state( *args )
       nt = next_transition( *args )
       nt && nt.target
     end
 
+    # if there is exactly one event which is valid with the given
+    # optional arguments, return it
     def next_event( *args )
       nt = next_transition( *args )
       nt && nt.event
@@ -294,6 +295,13 @@ module StateFu
       end
     end
 
+    # change the current state of the binding without any
+    # requirements or other sanity checks, or any hooks firing.
+    # Useful for test / spec scenarios, and abusing the framework.
+    def teleport!( target )
+      persister.current_state=( machine.states[target] )
+    end
+
     # display something sensible that doesn't take up the whole screen
     def inspect
       '|<= ' + self.class.to_s + ' ' +
@@ -305,9 +313,11 @@ module StateFu
         map {|x| x.join('=') }.join( " " ) + ' =>|'
     end
 
+    # let's be == the current_state_name as a symbol.
+    # a nice little convenience.
     def == other
-      if other.respond_to?(:to_sym) && current_state_name.is_a?(Symbol)
-        other.to_sym == current_state_name || super( other )
+      if other.respond_to?( :to_sym ) && current_state
+        current_state_name == other.to_sym || super( other )
       else
         super( other )
       end

data/lib/state_fu/core_ext.rb

@@ -1,15 +1,16 @@
 require 'rubygems'
-
-class Symbol
+# ruby1.9 style symbol comparability for ruby1.8
+class Symbol  # :nodoc:
   unless instance_methods.include?(:'<=>')
-    # Logger.log ..
     def <=> other
       self.to_s <=> other.to_s
     end
   end
 end
 
-unless Object.const_defined?('ActiveSupport')
+# if ActiveSupport is absent, install a very small subset of it for
+# some convenience methods
+unless Object.const_defined?('ActiveSupport') # :nodoc:
   Dir[File.join(File.dirname( __FILE__), 'active_support_lite','**' )].sort.each do |lib|
     next unless File.file?( lib )
     require lib

data/lib/state_fu/event.rb

@@ -3,67 +3,93 @@ module StateFu
 
     attr_reader :origins, :targets, :requirements
 
-    #
-    # TODO - event guards
-    #
-
+    # called by Lathe when a new event is constructed
     def initialize(machine, name, options={})
       @requirements = [].extend ArrayWithSymbolAccessor
       super( machine, name, options )
     end
 
+    # the names of all possible origin states
     def origin_names
       origins ? origins.map(&:to_sym) : nil
     end
 
+    # the names of all possible target states
     def target_names
       targets ? targets.map(&:to_sym) : nil
     end
 
+    # tests if a state or state name is in the list of targets
     def to?( state )
       target_names.include?( state.to_sym )
     end
 
+    # tests if a state or state name is in the list of origins
     def from?( state )
       origin_names.include?( state.to_sym )
     end
 
-    def origins=( *args )
-      if [args].flatten == [:ALL]
-        @origins = machine.states
-      else
-        @origins = machine.find_or_create_states_by_name( *args.flatten ).extend( StateArray )
+    # internal method which accumulates states into an instance
+    # variable with successive invocations.
+    # ensures that calling #from multiple times adds to, rather than
+    # clobbering, the list of origins / targets.
+    def update_state_collection( ivar_name, *args)
+      new_states = if [args].flatten == [:ALL]
+            machine.states
+          else
+            machine.find_or_create_states_by_name( *args.flatten )
+          end
+      unless new_states.is_a?( Array )
+        new_states = [new_states]
       end
+      existing  = instance_variable_get( ivar_name )
+      # return existing if new_states.empty?
+      new_value = ((existing || [] ) + new_states).flatten.compact.uniq.extend( StateArray )
+      instance_variable_set( ivar_name, new_value )
+    end
+
+    # *adds to* the origin states given a list of symbols / States
+    def origins=( *args )
+      update_state_collection( '@origins', *args )
     end
 
+    # *adds to* the target states given a list of symbols / States
     def targets=( *args )
-      if [args].flatten == [:ALL]
-        @targets = machine.states
-      else
-        @targets = machine.find_or_create_states_by_name( *args.flatten ).extend( StateArray )
-      end
+      update_state_collection( '@targets', *args )
     end
 
-    # complete?(:origins) # do we have an origins?
-    # complete?          # do we have an origins and targets?
+
+    # used internally
+    #
+    # <tt>complete?(:origins) # do we have origins?<tt>
+    # <tt>complete?           # do we have origins and targets?<tt>
     def complete?( field = nil )
       ( field && [field] ||  [:origins, :targets] ).
         map{ |s| send(s) }.
         all?{ |f| !(f.nil? || f.empty?) }
     end
 
+    # if there is a single state in #origins, returns it
     def origin
       origins && origins.length == 1 && origins[0] || nil
     end
 
+    # if there is a single state in #origins, returns it
     def target
       targets && targets.length == 1 && targets[0] || nil
     end
 
+    # a simple event has exactly one target, and any number of
+    # origins. It's simple because it can be triggered without
+    # supplying a target name - ie, <tt>go!<tt> vs <tt>go!(:home)<tt>
     def simple?
       !! ( origins && target )
     end
 
+    # generally called from a Lathe. Sets the origin(s) and optionally
+    # target(s) - that is, if you supply the :to option, or a single element
+    # hash of origins => targets ) of the event. Both origins= and
+    # targets= are accumulators.
     def from *args
       options = args.extract_options!.symbolize_keys!
       args.flatten!
@@ -81,6 +107,7 @@ module StateFu
       end
     end
 
+    # sets the target states for the event.
     def to *args
       options = args.extract_options!.symbolize_keys!
       args.flatten!
@@ -88,11 +115,19 @@ module StateFu
       self.targets= *args
     end
 
+    # is the event legal for the given binding, with the given
+    # (optional) arguments?
     def fireable_by?( binding, *args )
       requirements.reject do |r|
         binding.evaluate_requirement_with_args( r, *args )
       end.empty?
     end
 
+    # adds an event requirement.
+    # TODO MOREDOC
+    def requires( *args, &block )
+      lathe.requires( *args, &block )
+    end
+
   end
 end

data/lib/state_fu/exceptions.rb

@@ -8,6 +8,11 @@ module StateFu
     attr_reader :transition
     DEFAULT_MESSAGE = "The transition was halted"
 
+    # SPECME
+    def unmet_requirements
+      transition.unmet_requirements
+    end
+
     def initialize( transition, message=DEFAULT_MESSAGE, options={})
       @transition = transition
       @options    = options

data/lib/state_fu/fu_space.rb

@@ -5,11 +5,12 @@ module StateFu
   class FuSpace
     cattr_reader :named_machines, :class_machines, :field_names
 
-    # class_machines[ Class ][ method_name ] # => a StateFu::Machine
-    # class_machines[ Klass ][ nil ]         # => the Klass's default Machine
-    # field_names[ Class ][ method_name ] # => name of attribute / db field
-
     # return the default machine, or an empty hash, given a missing index.
+    #
+    # * class_machines[ Class ][ method_name ] # => a StateFu::Machine
+    # * class_machines[ Klass ][ nil ]         # => the Klass's default Machine
+    # * field_names[ Class ][ method_name ]    # => name of attribute / db field
+    #
     LAZY_HASH = lambda do |h, k|
       if k.nil?
         self[ StateFu::DEFAULT_MACHINE ]