davidlee-state-fu 0.3.1 → 0.10.0

data/lib/state_fu/logger.rb

@@ -1,9 +1,19 @@
+
 require 'logger'
 module StateFu
+  #
+  # TODO - spec coverage
+  #
+  # Provide logging facilities, including the ability to use a shared logger.  
+  # Use Rails' log if running as a rails plugin; allow independent control of 
+  # StateFu log level.
+  
   class Logger
     cattr_accessor :prefix   # prefix for log messages
     cattr_accessor :suppress # set true to send messages to /dev/null
-
+    cattr_accessor :shared
+    cattr_accessor :suppress
+    
     DEBUG   = 0
     INFO    = 1
     WARN    = 2
@@ -14,75 +24,142 @@ module StateFu
     ENV_LOG_LEVEL = 'STATEFU_LOGLEVEL'
     DEFAULT_LEVEL = INFO
 
-    DEFAULT_PREFIX    = nil
-    SHARED_LOG_PREFIX = 'StateFu: '
+    DEFAULT_SHARED_LOG_PREFIX = '[StateFu] '
 
-    @@prefix   = DEFAULT_PREFIX
-    @@logger   = nil
-    @@suppress = false
+    @@prefix    = DEFAULT_SHARED_LOG_PREFIX
+    @@logger    = nil
+    @@suppress  = false
+    @@shared    = false
+    @@log_level = nil
 
-    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 ] )
+    def self.new( logger = $stdout, options={} )
+      self.suppress = false
+      self.logger   = logger, options
+      self
+    end
+
+    def self.initial_log_level
+      if env_level = ENV[ENV_LOG_LEVEL]
+        parse_log_level( env_level )
       else
         DEFAULT_LEVEL
       end
     end
 
-    def self.new( log = $stdout, level = () )
-      self.instance = get_logger( log )
+    def self.level
+      @@log_level ||= initial_log_level
+    end
+
+    def self.level=( new_level )
+      @@log_level = parse_log_level(new_level)
+    end
+
+    def self.shared?
+      !! @@shared
+    end
+
+    def self.prefix
+      shared? ? @@prefix : nil
     end
 
-    def self.instance=( logger )
-      @@logger ||= get_logger
+    def self.logger= logger
+      set_logger logger
     end
 
     def self.instance
-      @@logger ||= get_logger
+      @@logger ||= set_logger(Logger.default_logger)
+    end
+
+    def self.suppress!
+      self.suppress = true
+    end
+
+    def self.suppressed?(severity = DEBUG)
+      suppress == true || severity < level
+    end
+
+    def self.add(severity, message = nil, progname = nil, &block)
+      severity = parse_log_level( severity )
+      return if suppressed?( severity )
+      message = [prefix, (message || (block && block.call) || progname).to_s].compact.join
+      # message = "#{message}\n" unless message[-1] == ?\n
+      instance.add( severity, message )
+    end
+
+    def self.debug   progname = nil, &block; add DEBUG,   progname, &block; end
+    def self.info    progname = nil, &block; add INFO,    progname, &block; end 
+    def self.warn    progname = nil, &block; add WARN,    progname, &block; end 
+    def self.error   progname = nil, &block; add ERROR,   progname, &block; end 
+    def self.fatal   progname = nil, &block; add FATAL,   progname, &block; end 
+    def self.unknown progname = nil, &block; add UNKNOWN, progname, &block; end 
+
+    #
+    # TODO fix these crappy methods
+    #
+    
+    # setter for logger instance
+    def self.set_logger( logger, options = { :shared => false } )
+      case logger
+      when String
+        file     = File.open(logger, File::WRONLY | File::APPEND)        
+        @@logger = Logger.activesupport_logger_available? ? ActiveSupport::BufferedLogger.new(file) : ::Logger.new(file)
+      when ::Logger
+        @@logger = logger
+      when Logger.activesupport_logger_available? && ActiveSupport::BufferedLogger
+        @@logger = logger
+      else
+        raise ArgumentError.new
+      end
+      self.shared = !!options.symbolize_keys![:shared]
+      if shared?
+        @@prefix = options[:prefix] || DEFAULT_SHARED_LOG_PREFIX
+        puts "shared :: #{@@prefix} #{prefix}"
+      end      
+      if lvl = options[:level] || options[:log_level]
+        self.level = lvl
+      end      
+      instance
     end
 
-    def self.get_logger( log = $stdout )
+    private
+    
+    def self.get_logger( logr = $stdout )
       if Object.const_defined?( "RAILS_DEFAULT_LOGGER" )
-        logger         = RAILS_DEFAULT_LOGGER
-        prefix         = SHARED_LOG_PREFIX
+        set_logger RAILS_DEFAULT_LOGGER, :shared => true
       else
         if Object.const_defined?( 'ActiveSupport' ) && ActiveSupport.const_defined?('BufferedLogger')
-          logger       = ActiveSupport::BufferedLogger.new( log )
+          set_logger( ActiveSupport::BufferedLogger.new( logr ))
         else
-          logger       = ::Logger.new( log )
-          logger.level = state_fu_log_level()
+          set_logger ::Logger.new( logr )
         end
       end
-      logger
     end
 
-    def self.suppress!
-      @@suppress = true
+    def self.activesupport_logger_available?
+      Object.const_defined?( 'ActiveSupport' ) && ActiveSupport.const_defined?('BufferedLogger')
     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]
+    
+    def self.default_logger
+      if Object.const_defined?( "RAILS_DEFAULT_LOGGER" )
+        RAILS_DEFAULT_LOGGER
+      else
+        $stdout
       end
-      instance.send( method_id, *args )
     end
-
+    
+    def self.parse_log_level(input)
+      case input
+      when String, Symbol
+        const_get( input )
+      when 0,1,2,3,4,5
+        input
+      when nil
+        level
+      else
+        raise ArgumentError
+      end
+    end
+    
   end
 end
 
-# StateFu::Logger.info( StateFu::Logger.instance.inspect )

data/lib/state_fu/machine.rb

@@ -1,36 +1,74 @@
 module StateFu
   class Machine
-    include Helper
 
-    # meta-constructor; expects to be called via Klass.machine()
+    def self.BINDINGS
+      @@_bindings ||= {}
+    end
+
+    include Applicable
+    include HasOptions
+    
+    attr_reader :hooks
+
+    #
+    # Class methods
+    #
+
     def self.for_class(klass, name, options={}, &block)
       options.symbolize_keys!
       name = name.to_sym
-      unless machine = StateFu::FuSpace.class_machines[ klass ][ name ]
-        machine = new( name, options, &block )
-        machine.bind!( klass, name, options[:field_name] )
+
+      unless machine = klass.state_fu_machines[ name ]
+        machine = new(options)
+        machine.bind! klass, name, options[:field_name] 
       end
       if block_given?
-        machine.apply!( &block )
+        machine.apply! &block 
       end
       machine
     end
 
+    # make it so that a class which has included StateFu has a binding to
+    # this machine
+    def self.bind!( machine, owner, name, field_name)
+      name = name.to_sym
+      # define an accessor method with the given name
+      if owner.class == Class
+        owner.state_fu_machines[name]    = machine
+        owner.state_fu_field_names[name] = field_name
+        # method_missing to catch NoMethodError for event methods, etc
+        StateFu::MethodFactory.define_once_only_method_missing( owner )
+        unless owner.respond_to?(name)
+          owner.class_eval do
+            define_method name do
+              state_fu( name )
+            end
+          end
+        end
+        # prepare the persistence field
+        StateFu::Persistence.prepare_field owner, field_name 
+      else
+        _binding = StateFu::Binding.new machine, owner, name, :field_name => field_name, :singleton => true 
+        MethodFactory.define_singleton_method(owner, name) { _binding }
+      end
+    end
+
     ##
     ## Instance Methods
     ##
 
     attr_reader :states, :events, :options, :helpers, :named_procs, :requirement_messages, :tools
 
-    def initialize( name, options={}, &block )
-      # TODO - name isn't actually used anywhere yet - remove from constructor
-      @states  = [].extend( StateArray  )
-      @events  = [].extend( EventArray  )
-      @helpers = [].extend( HelperArray )
-      @tools   = [].extend( ToolArray   )
+    def initialize( options={}, &block )
+      @states               = [].extend( StateArray  )
+      @events               = [].extend( EventArray  )
+      @helpers              = [].extend( HelperArray )
+      @tools                = [].extend( ToolArray   )
       @named_procs          = {}
       @requirement_messages = {}
       @options              = options
+      @hooks                = Hooks.for( self )
+      apply!( &block ) if block_given?
     end
 
     # merge the commands in &block with the existing machine; returns
@@ -52,6 +90,10 @@ module StateFu
       tools.inject_into( obj )
     end
 
+    def inject_methods_into( obj )
+      #puts 'inject_methods_into'
+    end
+
     # the modules listed here will be mixed into Binding and
     # Transition objects for this machine. use this to define methods,
     # references or data useful to you during transitions, event
@@ -66,32 +108,17 @@ module StateFu
       modules_to_add.each { |mod| helpers << mod }
     end
 
-    # same deal but for extending Lathe
+    # same as helper, but for extending Lathes rather than the Bindings / Transitions.
+    # use this to extend the Lathe DSL to suit your problem domain.
     def tool *modules_to_add
       modules_to_add.each { |mod| tools << mod }
     end
 
     # make it so a class which has included StateFu has a binding to
     # this machine
-    def bind!( klass, name=StateFu::DEFAULT_MACHINE, field_name = nil )
-      field_name ||= name.to_s.underscore.tr(' ', '_') + StateFu::Persistence::DEFAULT_FIELD_NAME_SUFFIX
-      field_name   = field_name.to_sym
-      StateFu::FuSpace.insert!( klass, self, name, field_name )
-      # define an accessor method with the given name
-      unless name == StateFu::DEFAULT_MACHINE
-        klass.class_eval do
-          define_method name do
-            state_fu( name )
-          end
-        end
-      end
-
-      # method_missing to catch NoMethodError for event methods, etc
-      StateFu::MethodFactory.prepare_class( klass )
-
-      # prepare the persistence field
-      StateFu::Persistence.prepare_field( klass, field_name )
-      true
+    def bind!( owner, name= DEFAULT, field_name = nil )
+      field_name ||= Persistence.default_field_name( name )
+      self.class.bind!(self, owner, name, field_name)
     end
 
     def empty?
@@ -152,5 +179,6 @@ module StateFu
     def graphviz
       @graphviz ||= Plotter.new(self).output
     end
+
   end
 end

data/lib/state_fu/method_factory.rb

@@ -1,95 +1,203 @@
 module StateFu
+  # This class is responsible for defining methods at runtime.
+  #
+  # TODO: all events, simple or complex, should get the same method signature
+  # simple events will be called as:  event_name! nil,    *args
+  # complex events will be called as: event_name! :state, *args
+  
   class MethodFactory
 
+    # An instance of MethodFactory is created to define methods on a specific StateFu::Binding, and
+    # the object it is bound to.
+    #
+    # During the initializer, it will call define_event_methods_on(the binding), which installs
+    #
     def initialize( _binding )
-      @binding = _binding
-      define_event_methods_on( _binding )
-    end
+      # store @binding in a local variable so it's accessible within
+      # the closures below (for define_singleton_method ).
 
-    def install!
-      define_event_methods_on( @binding.object )
+      # i.e, we're embedding a reference to @binding inside the method
+      @binding = _binding      
+      @defs    = {}
+
+      @binding.machine.states.each do |state|
+        @defs[:"#{state.name}?"] = lambda { _binding.current_state.name == state.name }
+      end
+      
+      # method definitions for simple events (only one possible target)
+      @binding.machine.events.each do |event|
+        @defs[event.name]           = lambda \
+        {|*args| _binding._event_method :get_transition,   event, args.shift, *args }
+        @defs[:"can_#{event.name}?"] = lambda \
+          {|*args| _binding._event_method :query_transition, event, args.shift, *args }
+        @defs[:"#{event.name}!"]     = lambda \
+          {|*args| _binding._event_method :fire_transition,  event, args.shift, *args }
+        
+        #if !event.targets.blank? # && event.targets.length > 1
+        event.targets.each do |target_state|
+          method_name = "#{event.name}_to_#{target_state.name}"
+
+          # object.event_name [:target], *arguments
+          #
+          # returns a new transition. Will raise an InvalidTransition if 
+          # it is not given arguments which result in a valid combination
+          # of event and target state being deducted.
+          #
+          # object.event_name suffices without any arguments if the event 
+          # has only one possible target, or only one valid target for 
+          
+          # object.event_name! [:target], *arguments
+          #
+          # as per the method above, except that it also
+          
+          @defs[method_name.to_sym]     = lambda \
+            {|*args| _binding._event_method :get_transition,   event, target_state, *args }
+            
+          # object.event_name! [:]
+          @defs[:"can_#{method_name}?"] = lambda \
+            {|*args| _binding._event_method :query_transition, event, target_state, *args }
+            
+          @defs[:"#{method_name}!"]     = lambda \
+            {|*args| _binding._event_method :fire_transition,  event, target_state, *args }          
+            
+        end unless event.targets.nil?
+      end    
     end
 
-    # ensure the methods are available before calling state_fu
+    #
+    # Class Methods
+    #
+
+    # This should be called once per class using StateFu. It aliases and redefines
+    # method_missing for the class.
+    #
+    # Note this happens when a machine is first bound to the class,
+    # not when StateFu is included.
+
     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 )
-      klass.class_eval do
-        alias_method :method_missing_before_state_fu, :method_missing
-
-        def method_missing( method_name, *args, &block )
-          if @state_fu_initialized
-            method_missing_before_state_fu( method_name, *args, &block )
-          else
-            state_fu!
-            if respond_to?( method_name )
-              send( method_name, *args, &block )
-            else
-              method_missing_before_state_fu( method_name, *args, &block )
-            end
+      raise caller.inspect
+      self.define_once_only_method_missing( klass )
+    end # prepare_class
+
+    # When triggered, method_missing will first call state_fu!,
+    # instantating all bindings & installing their attendant
+    # MethodFactories, then check if the object now responds to the
+    # missing method name; otherwise it will call the original
+    # method_missing.
+    #
+    # method_missing will then revert to its original implementation.
+    #
+    # The purpose of all this is to allow dynamically created methods
+    # to be called, without worrying about whether they have been
+    # defined yet, and without incurring the expense of loading all
+    # the object's StateFu::Bindings before they're likely to be needed.
+    #
+    # Note that if you redefine method_missing on your StateFul
+    # classes, it's best to either do it before you include StateFu,
+    # or thoroughly understand what's happening in
+    # MethodFactory#define_once_only_method_missing.
+
+    def self.define_once_only_method_missing( klass )
+      raise ArgumentError.new(klass.to_s) unless klass.is_a?(Class)      
+      
+      klass.class_eval do                
+        return false if @_state_fu_prepared
+        @_state_fu_prepared = true
+
+        alias_method(:method_missing_before_state_fu, :method_missing) # if defined?(:method_missing, true)
+
+        def method_missing(method_name, *args, &block)
+          # invoke state_fu! to ensure event, etc methods are defined
+          begin            
+            state_fu! unless defined? initialize_state_fu!            
+          rescue NoMethodError => e
+            raise e
+          end
+          
+          # reset method_missing for this instance
+          class << self; self; end.class_eval do
+            alias_method :method_missing, :method_missing_before_state_fu              
+          end
+        
+          # call the newly defined method, or the original method_missing
+          if respond_to?(method_name, true) 
+            # it was defined by calling state_fu!, which instantiated bindings
+            # for its state machines, which defined singleton methods for its
+            # states & events when it was constructed.
+            __send__( method_name, *args, &block )
+          else 
+            # call the original method_missing (method_missing_before_state_fu)
+            method_missing( method_name, *args, &block )
           end
         end # method_missing
       end # class_eval
-    end # prepare_class
+    end # define_once_only_method_missing
 
-    def define_method_on_metaclass( object, method_name, &block )
-      return false if object.respond_to?( method_name )
-      metaclass   = class << object; self; end
-      metaclass.class_eval do
-        define_method( method_name, &block )
-      end
+    # Define the same helper methods on the StateFu::Binding and its
+    # object.  Any existing methods will not be tampered with, but a
+    # warning will be issued in the logs if any methods cannot be defined.
+    def install!
+      define_event_methods_on( @binding )
+      define_event_methods_on( @binding.object )
     end
 
+    #
+    # For each event, on the given object, define three methods.
+    # - The first method is the same as the event name.
+    #   Returns a new, unfired transition object.
+    # - The second method has a "?" suffix.
+    #   Returns true if the event can be fired.
+    # - The third method has a "!" suffix.
+    #   Creates a new Transition, fires and returns it once complete.
+    #
+    # The arguments expected depend on whether the event is "simple" - ie,
+    # has only one possible target state.
+    #
+    # All simple event methods pass their entire argument list
+    # directly to transition.  These arguments can be accessed inside
+    # event hooks, requirements, etc by calling Transition#args.
+    #
+    # All complex event methods require their first argument to be a
+    # Symbol containing a valid target State's name, or the State
+    # itself.  The remaining arguments are passed into the transition,
+    # as with simple event methods.
+    #
     def define_event_methods_on( obj )
-      _binding        = @binding
-      simple, complex = @binding.machine.events.partition(&:simple? )
+      @defs.each do |method_name, method_body|
+        define_singleton_method( obj, method_name, &method_body)
+      end
+    end # define_event_methods_on
 
-      # method definitions for simple events (only one possible target)
-      simple.each do |event|
-        # obj.event_name( *args )
-        # returns a new transition
-        method_name = event.name
-        define_method_on_metaclass( obj, method_name ) do |*args|
-          _binding.transition( event, *args )
-        end
+    def define_singleton_method( object, method_name, &block )
+      MethodFactory.define_singleton_method object, method_name, &block
+    end
 
-        # obj.event_name?()
-        # true if the event is fireable? (ie, requirements met)
-        method_name = "#{event.name}?"
-        define_method_on_metaclass( obj, method_name ) do
-          _binding.fireable?( event )
-        end
+    # define a a method on the metaclass of the given object. The
+    # resulting "singleton method" will be unique to that instance,
+    # not shared by other instances of its class.
+    #
+    # This allows us to embed a reference to the instance's unique
+    # binding in the new method.
+    #
+    # existing methods will never be overwritten.
 
-        # obj.event_name!( *args )
-        # creates, fires and returns a transition
-        method_name = "#{event.name}!"
-        define_method_on_metaclass( obj, method_name ) do |*args|
-          _binding.fire!( event, *args )
+    def self.define_singleton_method( object, method_name, options={}, &block )
+      if object.respond_to?(method_name, true) 
+        msg = !options[:force]
+        Logger.info "Existing method #{method(method_name) rescue [method_name].inspect} "\
+          "for #{object.class} #{object} "\
+          "#{options[:force] ? 'WILL' : 'won\'t'} "\
+          "be overwritten."
+      else
+        metaclass = class << object; self; end
+        metaclass.class_eval do
+          define_method( method_name, &block )
         end
       end
+    end
+    alias_method :define_singleton_method, :define_singleton_method
 
-      # method definitions for complex events (target must be specified)
-      complex.each do |event|
-        # obj.event_name( target, *args )
-        # returns a new transition
-        define_method_on_metaclass( obj, event.name ) do |target, *args|
-          _binding.transition( [event, target], *args )
-        end
-
-        # 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, *args|
-          _binding.fireable?( [event, target], *args )
-        end
+  end # class MethodFactory
+end # module StateFu
 
-        # 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|
-          _binding.fire!( [event, target], *args )
-        end
 
-      end
-    end
-  end
-end

data/lib/state_fu/methodical.rb

@@ -0,0 +1,17 @@
+module StateFu
+  module Methodical
+
+    def self.__define_method( method_name, &block )
+      self.class.class_eval do
+        define_method method_name, &block
+      end
+    end
+
+    def __define_singleton_method( method_name, &block )
+      (class << object; self; end).class_eval do
+        define_method method_name, &block
+      end
+    end
+
+  end
+end

data/lib/state_fu/persistence/active_record.rb

@@ -5,7 +5,12 @@ 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!
+
+        # this adds a before_save hook to ensure that the field is initialized 
+        # (and the initial state set) before create.
+        klass.send :before_create, :state_fu!
+                
+        # it's usually a good idea to do this:
         # validates_presence_of _field_name
       end
 

data/lib/state_fu/persistence/attribute.rb

@@ -24,6 +24,7 @@ module StateFu
         end
       end
 
+  def b; binding; end
       private
 
       # Read / write our strings to a plain old instance variable