state-fu 0.11.1

data/lib/machine.rb

@@ -0,0 +1,184 @@
+module StateFu
+  class 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 = klass.state_fu_machines[ name ]
+        machine = new(options)
+        machine.bind! klass, name, options[:field_name] 
+      end
+      if block_given?
+        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( 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
+    # a lathe for the machine.
+    def apply!( &block )
+      StateFu::Lathe.new( self, &block )
+    end
+    alias_method :lathe, :apply!
+
+    def helper_modules
+      helpers.modules
+    end
+
+    def inject_helpers_into( obj )
+      helpers.inject_into( obj )
+    end
+
+    def inject_tools_into( obj )
+      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
+    # hooks, or in general use of StateFu.
+    #
+    # They can be supplied as a string/symbol (as per rails controller
+    # helpers), or a Module.
+    #
+    # To do this globally, just duck-punch StateFu::Machine /
+    # StateFu::Binding.
+    def helper *modules_to_add
+      modules_to_add.each { |mod| helpers << mod }
+    end
+
+    # 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!( owner, name= DEFAULT, field_name = nil )
+      field_name ||= Persistence.default_field_name( name )
+      self.class.bind!(self, owner, name, field_name)
+    end
+
+    def empty?
+      states.empty?
+    end
+
+    def initial_state=( s )
+      case s
+      when Symbol, String, StateFu::State
+        unless init_state = states[ s.to_sym ]
+          init_state = StateFu::State.new( self, s.to_sym )
+          states << init_state
+        end
+        @initial_state = init_state
+      else
+        raise( ArgumentError, s.inspect )
+      end
+    end
+
+    def initial_state()
+      @initial_state ||= states.first
+    end
+
+    def state_names
+      states.map(&:name)
+    end
+
+    def event_names
+      events.map(&:name)
+    end
+
+    # given a messy bunch of symbols, find or create a list of
+    # matching States.
+    def find_or_create_states_by_name( *args )
+      args = args.compact.flatten
+      raise ArgumentError.new( args.inspect ) unless args.all? { |a| [Symbol, StateFu::State].include? a.class }
+      args.map do |s|
+        unless state = states[s.to_sym]
+          # TODO clean this line up
+          state = s.is_a?( StateFu::State ) ? s : StateFu::State.new( self, s )
+          self.states << state
+        end
+        state
+      end
+    end
+
+    # Marshal, the poor man's X-Ray photocopier.
+    # TODO: a version which will not break its teeth on procs
+    def deep_clone
+      Marshal::load(Marshal.dump(self))
+    end
+    alias_method :deep_copy, :deep_clone
+
+    def inspect
+      "#<#{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/method_factory.rb

@@ -0,0 +1,243 @@
+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
+    attr_accessor :method_definitions
+    attr_reader   :binding
+    
+    # An instance of MethodFactory is created to define methods on a specific StateFu::Binding, and
+    # on the object it is bound to.
+    
+    def initialize( _binding )
+      @binding                      = _binding  
+      simple_events, complex_events = @binding.machine.events.partition(&:simple?)
+      @method_definitions           = {}
+      
+      # simple event methods
+      # all arguments are passed into the transition / transition query
+      
+      simple_events.each do |event|
+        method_definitions["#{event.name}"]      = lambda do |*args| 
+          _binding.find_transition(event, event.target, *args) 
+        end
+        
+        method_definitions["can_#{event.name}?"] = lambda do |*args|
+          _binding.can_transition?(event, event.target, *args)
+        end
+
+        method_definitions["#{event.name}!"]     = lambda do |*args|
+          _binding.fire_transition!(event, event.target, *args)
+        end
+      end
+
+      # complex event methods
+      # the first argument is the target state
+      # any remaining arguments are passed into the transition / transition query
+
+      # object.event_name [:target], *arguments
+      #
+      # returns a new transition. Will raise an IllegalTransition if 
+      # it is not given arguments which result in a valid combination
+      # of event and target state being deducted.
+      #
+      # object.event_name [nil] suffices if the event has only one valid 
+      # target (ie only one transition which would not raise a 
+      # RequirementError if fired) 
+      
+      # object.event_name! [:target], *arguments
+      #
+      # as per the method above, except that it also fires the event
+
+      # object.can_event_name? [:target], *arguments
+      #
+      # tests that calling event_name or event_name! would not raise an error
+      # ie, the transition is legal and is valid with the arguments supplied
+      
+      complex_events.each do |event|
+        method_definitions["#{event.name}"]      = lambda do |target, *args|
+          _binding.find_transition(event, target, *args) 
+        end
+        
+        method_definitions["can_#{event.name}?"] = lambda do |target, *args|
+          begin 
+            t = _binding.find_transition(event, target, *args) 
+            t.valid?
+          rescue IllegalTransition
+            false
+          end
+        end
+
+        method_definitions["#{event.name}!"]     = lambda do |target, *args|
+          _binding.fire_transition!(event, target, *args)
+        end
+      end
+      
+      # methods dedicated to a combination of event and target
+      # all arguments are passed into the transition / transition query
+      
+      (simple_events + complex_events).each do |event|
+        event.targets.each do |target|
+          method_definitions["#{event.name}_to_#{target.name}"]      = lambda do |*args| 
+            _binding.find_transition(event, target, *args) 
+          end
+
+          method_definitions["can_#{event.name}_to_#{target.name}?"] = lambda do |*args|
+            _binding.can_transition?(event, target, *args)
+          end
+
+          method_definitions["#{event.name}_to_#{target.name}!"]     = lambda do |*args|
+            _binding.fire_transition!(event, target, *args)
+          end          
+        end unless event.targets.nil?
+      end
+      
+      @binding.machine.states.each do |state|
+        method_definitions["#{state.name}?"] = lambda do 
+         _binding.current_state == state
+        end
+      end
+      
+    end 
+          
+
+    #
+    # 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 )
+      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 # define_once_only_method_missing
+
+    # 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 )
+      method_definitions.each do |method_name, method_body|
+        define_singleton_method( obj, method_name, &method_body)
+      end
+    end # define_event_methods_on
+
+    def define_singleton_method( object, method_name, &block )
+      MethodFactory.define_singleton_method object, method_name, &block
+    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.
+
+    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
+    
+  end # class MethodFactory
+end # module StateFu
+
+

data/lib/persistence.rb

@@ -0,0 +1,116 @@
+module StateFu
+
+  # the persistence module has a few simple tests which help decide which
+  # persistence mechanism to use
+
+  # TODO add event hooks (on_change etc) ...
+  # after benchmarking
+
+  # To create your own custom persistence mechanism,
+  # subclass StateFu::Persistence::Base
+  # and define prepare_field, read_attribute and write_attribute:
+
+
+  #  class StateFu::Persistence::MagneticCarpet < StateFu::Persistence::Base
+  #    def prepare_field
+  #
+  #
+  #    def read_attribute
+  #      object.send "magnetised_#{field_name}"
+  #    end
+  #
+  #    def write_attribute( string_value )
+  #      Logger.debug "magnetising ( #{field_name} => #{string_value} on #{object.inspect}"
+  #      object.send "magnetised_#{field_name}=", string_value
+  #    end
+  #  end
+
+  module Persistence
+    DEFAULT_SUFFIX    = '_field'
+    @@class_for       = {}
+    @@fields_prepared = {}
+
+    #
+    # Class Methods
+    #
+
+    def self.default_field_name( machine_name )
+      machine_name == DEFAULT ? DEFAULT_FIELD : "#{machine_name.to_s.underscore.tr(' ','_')}#{DEFAULT_SUFFIX}"
+    end
+
+    # returns the appropriate persister class for the given class & field name.
+    def self.class_for( klass, field_name )
+      raise ArgumentError if [klass, field_name].any?(&:nil?)
+      @@class_for[klass] ||= {}
+      @@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
+        end
+    end
+
+    def self.for_class( klass, binding, field_name )
+      persister_class = class_for klass, field_name
+      prepare_field( klass, field_name, persister_class)
+      returning persister_class.new( binding, field_name ) do |persister|
+        Logger.debug( "#{persister_class}: method #{binding.method_name} as field #{persister.field_name}" )
+      end
+    end
+
+    def self.for_instance( binding, field_name )
+      metaclass = class << binding.object; self; end
+      for_class( metaclass, binding, field_name )
+    end
+
+    # returns a new persister appropriate to the given binding and field_name
+    # also ensures the persister class method :prepare_field has been called
+    # once for the given class & field name so the field can be set up; eg an
+    # attr_accessor or a before_save hook defined
+    def self.for( binding )
+      field_name = binding.field_name.to_sym
+      if binding.singleton?
+        for_instance( binding, field_name )
+      else
+        for_class( binding.target, binding, field_name )
+      end
+    end
+
+    # ensures that <persister_class>.prepare_field is called only once
+    def self.prepare_field(klass, field_name, persister_class=nil)
+      @@fields_prepared[klass] ||= []
+      unless @@fields_prepared[klass].include?(field_name)
+        persister_class ||= class_for(klass, field_name)
+        persister_class.prepare_field( klass, field_name )
+        @@fields_prepared[klass] << field_name
+      end
+    end
+
+    #
+    # Heuristics - simple test methods to determine which persister to use
+    #
+
+    # checks to see if the field_name for persistence is a
+    # RelaxDB attribute.
+    # Safe to use (skipped) 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 (skipped) if ActiveRecord is not included.
+    def self.active_record_column?( klass, field_name )
+      Object.const_defined?("ActiveRecord") &&
+        ::ActiveRecord.const_defined?("Base") &&
+        klass.ancestors.include?( ::ActiveRecord::Base ) &&
+        klass.table_exists? &&
+        klass.columns.map(&:name).include?( field_name.to_s )
+    end
+
+  end
+end