davidlee-state-fu 0.2.0 → 0.3.1

data/lib/state_fu/helper.rb

@@ -79,10 +79,12 @@ module StateFu
     # is there exactly one possible event to fire, with a single
     # target event?
     def next?
+      raise NotImplementedError
     end
 
     # if next?, return the state
     def next
+      raise NotImplementedError
     end
 
   end
@@ -104,10 +106,12 @@ module StateFu
     # is there exactly one possible event to fire, with a single
     # target event?
     def next?
+      raise NotImplementedError
     end
 
     # if next?, return the event
     def next
+      raise NotImplementedError
     end
 
   end
@@ -117,7 +121,9 @@ module StateFu
       self.map do |h|
         case h
         when String, Symbol
-          Object.const_get( h.to_s.classify )
+          mod_name = h.to_s.split('/').inject(Object) do |mod, part|
+            mod = mod.const_get( part.camelize )
+          end
         when Module
           h
         else
@@ -182,11 +188,14 @@ module StateFu
     end
   end  # OrderedHash
 
+  # satanic incantations we use for evaluating blocks conditionally,
+  # massaging their arguments and managing execution context.
   module ContextualEval
+    # :nodoc:
     module InstanceMethods
 
       # if we use &block syntax it stuffs the arity up, so we have to
-      # pass it as a normal argument
+      # pass it as a normal argument. Ruby bug!
       def limit_arguments( block, *args )
         case block.arity
         when -1, 0
@@ -225,8 +234,21 @@ module StateFu
       def evaluate_named_proc_or_method( name, *args )
         if (name.is_a?( Proc ) && proc = name) || proc = machine.named_procs[ name ]
           evaluate( *args, &proc )
-        else
+        elsif self.respond_to?( name )
+          if method(name).arity == 0
+            send(name)
+          else
+            send(name, *args )
+          end
+          # evaluate( *args, &method(name) )
+        elsif object.respond_to?( name )
           call_on_object_with_optional_args( name, *args )
+        else # method is not defined
+          if name.to_s =~ /^not_(.*)$/
+            !evaluate_named_proc_or_method( $1, *args )
+          else
+            raise NoMethodError.new("#{name} is not defined on #{object} or #{self} or as a named proc in #{machine}")
+          end
         end
       end
 

data/lib/state_fu/hooks.rb

@@ -1,5 +1,8 @@
 module StateFu
-  module Hooks
+
+  # TODO document structure / sequence of hooks elsewhere
+
+  module Hooks # :nodoc:
 
     ALL_HOOKS = [[:event,  :before],   # good place to start a transaction, etc
                  [:origin, :exit],     # say goodbye!

data/lib/state_fu/interface.rb

@@ -6,9 +6,8 @@ module StateFu
 
       # TODO:
       # take option :alias => false (disable aliases) or :alias
-      # => :foo (use foo as class & instance accessor)
+      # => :foo (add :foo as class & instance accessor methods)
 
-      #
       # Given no arguments, return the default machine (:state_fu) for the
       # class, creating it if it did not exist.
       #
@@ -35,10 +34,9 @@ module StateFu
       alias_method :stfu,          :machine
       alias_method :state_fu,      :machine
       alias_method :workflow,      :machine
+      alias_method :stateful,      :machine
       alias_method :statefully,    :machine
       alias_method :state_machine, :machine
-      alias_method :stateful,      :machine
-      alias_method :workflow,      :machine
       alias_method :engine,        :machine
 
       # return a hash of :name => StateFu::Machine for your class.
@@ -49,22 +47,25 @@ module StateFu
           machine( *args, &block)
         end
       end
-      alias_method :machines,     :machines
-      alias_method :workflows,    :machines
-      alias_method :engines,      :machines
+      alias_method :stfus,     :machines
+      alias_method :state_fus, :machines
+      alias_method :workflows, :machines
+      alias_method :engines,   :machines
 
       # return the list of machines names for this class
       def machine_names()
         StateFu::FuSpace.class_machines[self].keys
       end
-      alias_method :machine_names,       :machine_names
-      alias_method :workflow_names,      :machine_names
-      alias_method :engine_names,        :machine_names
+      alias_method :stfu_names,     :machine_names
+      alias_method :state_fu_names, :machine_names
+      alias_method :workflow_names, :machine_names
+      alias_method :engine_names,   :machine_names
     end
 
-    # Give the gift of state to your objects. These methods
-    # grant access to StateFu::Binding objects, which are bundles of
-    # context linking a StateFu::Machine to an object / instance.
+    # These methods grant access to StateFu::Binding objects, which
+    # are bundles of context encapsulating a StateFu::Machine, an instance
+    # of a class, and its current state in the machine.
+
     # Again, plenty of aliases are provided so you can use whatever
     # makes sense to you.
     module InstanceMethods
@@ -73,16 +74,11 @@ module StateFu
         @_state_fu ||= {}
       end
 
-      # A StateFu::Binding comes into being, linking your object and a
-      # machine, when you first call yourobject.binding() for that
-      # machine.
-      #
-      # Like the class method .machine(), calling it without any arguments
-      # is equivalent to passing :om.
-      #
-      # Essentially, this is the accessor method through which an instance
-      # can see and change its state, interact with events, etc.
+      # A StateFu::Binding comes into being when it is first referenced.
       #
+      # This is the accessor method through which an object instance (or developer)
+      # can access a StateFu::Machine, the object's current state, the
+      # methods which trigger event transitions, etc.
       public
       def _binding( name=StateFu::DEFAULT_MACHINE )
         name = name.to_sym
@@ -97,9 +93,9 @@ module StateFu
       alias_method :stateful,    :_binding
       alias_method :workflow,    :_binding
       alias_method :engine,      :_binding
+      alias_method :machine,     :_binding # not strictly accurate
       alias_method :context,     :_binding
 
-
       # Gain awareness of all bindings (state contexts) this object
       # has contemplated into being.
       # Returns a Hash of { :name => <StateFu::Binding>, ... }
@@ -114,7 +110,7 @@ module StateFu
       alias_method :workflows,    :_bindings
       alias_method :engines,      :_bindings
       alias_method :bindings,     :_bindings
-      alias_method :machines,     :_bindings # not strictly accurate, but makes sense sometimes
+      alias_method :machines,     :_bindings # not strictly accurate
       alias_method :contexts,     :_bindings
 
       # Instantiate bindings for all machines defined for this class.

data/lib/state_fu/lathe.rb

@@ -1,10 +1,17 @@
 module StateFu
+  # A Lathe parses and a Machine definition and returns a freshly turned
+  # Machine.
+  #
+  # It provides the means to define the arrangement of StateFu objects
+  # ( eg States and Events) which comprise a workflow, process,
+  # lifecycle, circuit, syntax, etc.
   class Lathe
 
     # NOTE: Sprocket is the abstract superclass of Event and State
 
     attr_reader :machine, :sprocket, :options
 
+    # you don't need to call this directly.
     def initialize( machine, sprocket = nil, options={}, &block )
       @machine  = machine
       @sprocket = sprocket
@@ -141,7 +148,7 @@ module StateFu
       if child? && sprocket.is_a?( StateFu::State ) # in state block
         targets  = options.delete(:to)
         evt      = define_event( name, options, &block )
-        evt.from sprocket unless evt.origins
+        evt.from sprocket unless sprocket.nil?
         evt.to( targets ) unless targets.nil?
         evt
       else # in master lathe
@@ -225,11 +232,38 @@ module StateFu
       sprocket.to( *args, &block )
     end
 
+    #
+    # define chained events and states succinctly
+    # usage: chain 'state1 -event1-> state2 -event2-> state3'
+    def chain (string)
+      rx_word    = /([a-zA-Z0-9_]+)/
+      rx_state   = /^#{rx_word}$/
+      rx_event   = /^-#{rx_word}->$/
+      previous   = nil
+      string.split.each do |chunk|
+        case chunk
+        when rx_state
+          current = state($1)
+          if previous.is_a?( StateFu::Event )
+            previous.to( current )
+          end
+        when rx_event
+          current = event($1)
+          if previous.is_a?( StateFu::State )
+            current.from( previous )
+          end
+        else
+          raise ArgumentError, "'#{chunk}' is not a valid token"
+        end
+        previous = current
+      end
+    end
+
     #
     # do something with all states / events
     #
     def each_sprocket( type, *args, &block)
-      require_no_sprocket()
+
       options = args.extract_options!.symbolize_keys!
       if args == [:ALL] || args == []
         args = machine.send("#{type}s").except( options.delete(:except) )
@@ -238,12 +272,14 @@ module StateFu
     end
 
     def states( *args, &block )
+      require_no_sprocket()
       each_sprocket( 'state', *args, &block )
     end
     alias_method :all_states, :states
     alias_method :each_state, :states
 
     def events( *args, &block )
+      require_sprocket( NilClass, StateFu::State )
       each_sprocket( 'event', *args, &block )
     end
     alias_method :all_events, :events

data/lib/state_fu/logger.rb

@@ -1,10 +1,88 @@
 require 'logger'
-
 module StateFu
-  if Object.const_defined?( "RAILS_DEFAULT_LOGGER" )
-    Logger       = RAILS_DEFAULT_LOGGER
-  else
-    Logger       = ::Logger.new( STDOUT )
-    Logger.level = ::Logger.const_get( (ENV["ZEN_LOGLEVEL"] || 'WARN').upcase )
+  class Logger
+    cattr_accessor :prefix   # prefix for log messages
+    cattr_accessor :suppress # set true to send messages to /dev/null
+
+    DEBUG   = 0
+    INFO    = 1
+    WARN    = 2
+    ERROR   = 3
+    FATAL   = 4
+    UNKNOWN = 5
+
+    ENV_LOG_LEVEL = 'STATEFU_LOGLEVEL'
+    DEFAULT_LEVEL = INFO
+
+    DEFAULT_PREFIX    = nil
+    SHARED_LOG_PREFIX = 'StateFu: '
+
+    @@prefix   = DEFAULT_PREFIX
+    @@logger   = nil
+    @@suppress = false
+
+    def self.level=( new_level )
+      instance.level = case new_level
+                       when String, Symbol
+                         const_get( new_level )
+                       when Fixnum
+                         new_level
+                       else
+                         state_fu_log_level()
+                       end
+    end
+
+    def self.state_fu_log_level
+      if ENV[ ENV_LOG_LEVEL ]
+        const_get( ENV[ ENV_LOG_LEVEL ] )
+      else
+        DEFAULT_LEVEL
+      end
+    end
+
+    def self.new( log = $stdout, level = () )
+      self.instance = get_logger( log )
+    end
+
+    def self.instance=( logger )
+      @@logger ||= get_logger
+    end
+
+    def self.instance
+      @@logger ||= get_logger
+    end
+
+    def self.get_logger( log = $stdout )
+      if Object.const_defined?( "RAILS_DEFAULT_LOGGER" )
+        logger         = RAILS_DEFAULT_LOGGER
+        prefix         = SHARED_LOG_PREFIX
+      else
+        if Object.const_defined?( 'ActiveSupport' ) && ActiveSupport.const_defined?('BufferedLogger')
+          logger       = ActiveSupport::BufferedLogger.new( log )
+        else
+          logger       = ::Logger.new( log )
+          logger.level = state_fu_log_level()
+        end
+      end
+      logger
+    end
+
+    def self.suppress!
+      @@suppress = true
+    end
+
+    # method_missing is usually a last resort
+    # but i don't see it causing any headaches here.
+    def self.method_missing( method_id, *args )
+      return if @@suppress
+      if [:debug, :info, :warn, :error, :fatal].include?( method_id ) &&
+          args[0].is_a?(String) && @@prefix
+        args[0] = @@prefix + args[0]
+      end
+      instance.send( method_id, *args )
+    end
+
   end
 end
+
+# StateFu::Logger.info( StateFu::Logger.instance.inspect )

data/lib/state_fu/machine.rb

@@ -149,5 +149,8 @@ module StateFu
       "#<#{self.class} ##{__id__} states=#{state_names.inspect} events=#{event_names.inspect} options=#{options.inspect}>"
     end
 
+    def graphviz
+      @graphviz ||= Plotter.new(self).output
+    end
   end
 end

data/lib/state_fu/method_factory.rb

@@ -78,14 +78,14 @@ module StateFu
         # obj.event_name?( target )
         # true if the event is fireable? (ie, requirements met)
         method_name = "#{event.name}?"
-        define_method_on_metaclass( obj, method_name ) do |target|
-          _binding.fireable?( [event, target] )
+        define_method_on_metaclass( obj, method_name ) do |target, *args|
+          _binding.fireable?( [event, target], *args )
         end
 
         # obj.event_name!( target, *args )
         # creates, fires and returns a transition
         method_name = "#{event.name}!"
-        define_method_on_metaclass( obj, method_name ) do |target,*args|
+        define_method_on_metaclass( obj, method_name ) do |target, *args|
           _binding.fire!( [event, target], *args )
         end
 

data/lib/state_fu/persistence/active_record.rb

@@ -4,6 +4,7 @@ module StateFu
 
       def self.prepare_field( klass, field_name )
         _field_name = field_name
+        Logger.debug("Preparing ActiveRecord field #{klass}.#{field_name}")
         klass.send :before_save, :state_fu!
         # validates_presence_of _field_name
       end
@@ -14,11 +15,12 @@ module StateFu
       # Attribute version, so just do the simplest thing we can.
 
       def read_attribute
+        Logger.debug "Read attribute #{field_name}, got #{object.send(:read_attribute,field_name)} for #{object.inspect}"
         object.send( :read_attribute, field_name )
       end
 
       def write_attribute( string_value )
-        # Logger.warn(" :write_attribute,#{ field_name},#{ string_value} \n=========================================================")
+        Logger.debug "Write attribute #{field_name} to #{string_value} for #{object.inspect}"
         object.send( :write_attribute, field_name, string_value )
       end
 

data/lib/state_fu/persistence/attribute.rb

@@ -5,7 +5,7 @@ module StateFu
       def self.prepare_field( klass, field_name )
         # ensure getter exists
         unless klass.instance_methods.map(&:to_sym).include?( field_name.to_sym )
-          Logger.info "Adding attr_reader :#{field_name} for #{klass}"
+          Logger.debug "Adding attr_reader :#{field_name} for #{klass}"
           _field_name = field_name
           klass.class_eval do
             private
@@ -15,7 +15,7 @@ module StateFu
 
         # ensure setter exists
         unless klass.instance_methods.map(&:to_sym).include?( :"#{field_name}=" )
-          Logger.info "Adding attr_writer :#{field_name}= for #{klass}"
+          Logger.debug "Adding attr_writer :#{field_name}= for #{klass}"
           _field_name = field_name
           klass.class_eval do
             private
@@ -31,13 +31,13 @@ module StateFu
 
       def read_attribute
         string = object.send( field_name )
-        Logger.info "Read attribute #{field_name}, got #{string.inspect} for #{object.inspect}"
+        Logger.debug "Read attribute #{field_name}, got #{string.inspect} for #{object.inspect}"
         string
       end
 
       def write_attribute( string_value )
         writer_method = "#{field_name}="
-        Logger.info "Writing attribute #{field_name} -> #{string_value.inspect} for #{object.inspect}"
+        Logger.debug "Writing attribute #{field_name} -> #{string_value.inspect} for #{object.inspect}"
         object.send( writer_method, string_value )
       end
 

data/lib/state_fu/persistence/base.rb

@@ -34,11 +34,11 @@ module StateFu
         @current_state = find_current_state()
 
         if current_state.nil?
-          Logger.info("Object has an undefined state: #{object}")
-          Logger.info("Machine has no states: #{machine}") if machine.states.empty?
+          Logger.warn("undefined state for binding #{binding} on #{object} with field_name #{field_name.inspect}")
+          Logger.warn("Machine for #{object} has no states: #{machine}") if machine.states.empty?
         else
           persist!
-          # Logger.debug("Object #{object} resuming #{binding.method_name} at #{current_state.name}: #{object.inspect}")
+          Logger.debug("#{object} resumes #{binding.method_name} at #{current_state.name}")
         end
       end
 

data/lib/state_fu/persistence/relaxdb.rb

@@ -0,0 +1,23 @@
+module StateFu
+  module Persistence
+    class RelaxDB < StateFu::Persistence::Base
+
+      def self.prepare_field( klass, field_name )
+        _field_name = field_name
+        #puts "relaxdb.before_save?"
+      end
+
+      private
+
+      def read_attribute
+        object.send( field_name )
+      end
+
+      def write_attribute( string_value )
+        object.send( "#{field_name}=", string_value )
+      end
+
+    end
+  end
+end
+

data/lib/state_fu/persistence.rb

@@ -2,27 +2,18 @@ module StateFu
   module Persistence
     DEFAULT_FIELD_NAME_SUFFIX = '_field'
 
-    def self.prepare_class( klass )
-      return if ( klass.instance_methods + klass.private_methods + klass.protected_methods ).map(&:to_sym).include?( :method_missing_before_state_fu )
-      alias_method :method_missing_before_state_fu, :method_missing
-      klass.class_eval do
-        def method_missing( method_name, *args, &block )
-          args.unshift method_name
-          if @state_fu_initialized
-            method_missing_before_state_fu( *args, &block )
-          else
-            state_fu!
-            if respond_to?(method_name)
-              send( *args, &block )
-            else
-              method_missing_before_state_fu( *args, &block )
-            end
-          end
-        end # method_missing
-      end # class_eval
-    end # prepare_class
-
+    # checks to see if the field_name for persistence is a
+    # RelaxDB attribute.
+    # Safe to use if RelaxDB is not included.
+    def self.relaxdb_document_property?( klass, field_name )
+      Object.const_defined?('RelaxDB') &&
+        klass.ancestors.include?( ::RelaxDB::Document ) &&
+        klass.properties.map(&:to_s).include?( field_name.to_s )
+    end
 
+    # checks to see if the field_name for persistence is an
+    # ActiveRecord column.
+    # Safe to use if ActiveRecord is not included.
     def self.active_record_column?( klass, field_name )
       Object.const_defined?("ActiveRecord") &&
         ::ActiveRecord.const_defined?("Base") &&
@@ -30,20 +21,24 @@ module StateFu
         klass.columns.map(&:name).include?( field_name.to_s )
     end
 
-    def self.for( binding, field_name )
-      if active_record_column?( binding.object.class, field_name )
-        self::ActiveRecord.new( binding, field_name )
+    # returns the appropriate persister class for the given class & field name.
+    def self.class_for( klass, field_name )
+      if active_record_column?( klass, field_name )
+        self::ActiveRecord
+      elsif relaxdb_document_property?( klass, field_name )
+        self::RelaxDB
       else
-        self::Attribute.new( binding, field_name )
+        self::Attribute
       end
     end
 
+    # returns a persister appropriate to the given binding and field_name
+    def self.for( binding, field_name )
+      class_for( binding.object.class, field_name ).new( binding, field_name )
+    end
+
     def self.prepare_field( klass, field_name )
-      if active_record_column?( klass, field_name )
-        self::ActiveRecord.prepare_field( klass, field_name )
-      else
-        self::Attribute.prepare_field( klass, field_name )
-      end
+      class_for( klass, field_name ).prepare_field( klass, field_name )
     end
 
   end

data/lib/state_fu/plotter.rb

@@ -0,0 +1,63 @@
+require File.join(File.dirname(__FILE__),'../vizier')
+require 'tempfile'
+
+module StateFu
+  class Plotter
+    attr_reader :machine, :dot, :graph, :states, :events
+
+    OUTPUT_HELPER = Module.new do
+
+      def save!
+        Tempfile.new(['state_fu_graph','.dot']) do |fh|
+          fh.write( self )
+        end.path
+      end
+
+      def save_as( filename )
+        File.open(filename, 'w') { |fh| fh.write( self ) }
+      end
+
+      def save_png(filename)
+        raise NotImplementedError
+        # dot graph.dot -Tpng -O
+      end
+
+    end
+
+    def output
+      generate
+    end
+
+    def initialize( machine, options={} )
+      raise RuntimeError, machine.class.to_s unless machine.is_a?(StateFu::Machine)
+      @machine = machine
+      @options = options.symbolize_keys!
+      @states  = {}
+      @events  = {}
+      # generate
+    end
+
+    def generate
+      @dot ||= generate_dot!.extend( OUTPUT_HELPER )
+    end
+
+    def generate_dot!
+      @graph = Vizier::Graph.new(:state_machine) do |g|
+        g.node :shape => 'doublecircle'
+        machine.state_names.map.each do |s|
+          @states[s] = g.add_node(s.to_s)
+        end
+        machine.events.map.each do |e|
+          e.origins.map(&:name).each do |from|
+            e.targets.map(&:name).each do |to|
+              g.connect( @states[from], @states[to], :label => e.name.to_s )
+            end
+          end
+          # @events[s] = g.add_node(s.to_s)
+        end
+      end
+      @graph.generate!
+    end
+
+  end
+end

data/lib/state_fu/sprocket.rb

@@ -26,6 +26,18 @@ module StateFu
       raise NotImeplementedError # abstract
     end
 
+    def to_s
+      "#<#{self.class}::#{self.object_id} @name=#{name.inspect}>"
+    end
+
+    def []v
+      options[v]
+    end
+
+    def []=v,k
+      options[v]=k
+    end
+
   end
 end
 

data/lib/state_fu/state.rb

@@ -41,5 +41,27 @@ module StateFu
     def === other
       self.to_sym === other.to_sym
     end
+
+    # display nice and short
+    def inspect
+      s = self.to_s
+      s = s[0,s.length-1]
+      display_hooks = hooks.dup
+      display_hooks.each do |k,v|
+        display_hooks.delete(k) if v.empty?
+      end
+      unless display_hooks.empty?
+        s << " hooks=#{display_hooks.inspect}"
+      end
+      unless entry_requirements.empty?
+        s << " entry_requirements=#{entry_requirements.inspect}"
+      end
+      unless exit_requirements.empty?
+        s << " exit_requirements=#{exit_requirements.inspect}"
+      end
+      s << ">"
+      s
+    end
+
   end
 end