example.rb features/logging_and_feedback.feature lib/state_fu/arrays.rb lib/state_fu/context.rb lib/state_fu/contextual_eval.rb lib/state_fu/helpers/applicable.rb lib/state_fu/helpers/arrays.rb lib/state_fu/helpers/contextual_eval.rb lib/state_fu/helpers/helper.rb lib/state_fu/helpers/transitive.rb spec/BDD/refactor_sanity_spec.rb @@ -8,3 +8,6 @@ *.gz pkg doc +.rake_tasks +*.fail +tmtags .gitignore @@ -55,7 +55,7 @@ namespace :spec do end desc "Run all specs, except especially slow ones" - task :run => [:skip_slow, :all] + task :quick => [:skip_slow, :all] desc "Run all specs with profiling & backtrace" Spec::Rake::SpecTask.new(:prof) do |t| @@ -95,5 +95,5 @@ begin rescue LoadError => e end -task :default => 'spec:run' +task :default => 'spec:all' task :all => 'spec:all' Rakefile @@ -1,4 +1,4 @@ --- :major: 0 -:minor: 3 -:patch: 1 +:minor: 4 +:patch: 0 VERSION.yml @@ -1,2 +1,2 @@ -# rails plugin +# rails plugin startup: just require 'state-fu' require File.join( File.dirname( __FILE__ ), 'lib', 'state-fu' ) init.rb @@ -59,7 +59,11 @@ require 'rubygems' [ 'core_ext', 'logger', - 'helper', + 'helpers/applicable', + 'helpers/contextual_eval', + 'helpers/transitive', + 'helpers/arrays', + 'context', 'exceptions', 'fu_space', 'machine', lib/state-fu.rb @@ -1,8 +1,8 @@ module StateFu - class Binding - include ContextualEval + class Binding < Context - attr_reader :object, :machine, :method_name, :persister, :transitions, :options + 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 @@ -18,19 +18,13 @@ module StateFu @method_name = method_name @transitions = [] @options = options.symbolize_keys! - field_name = StateFu::FuSpace.field_names[object.class][@method_name] - raise( ArgumentError, "No field_name" ) unless field_name - # ensure state field is set up (in case we created this binding - # manually, instead of via Machine.bind!) - StateFu::Persistence.prepare_field( object.class, field_name ) - # add a persister - @persister = StateFu::Persistence.for( self, field_name ) - Logger.debug( "Persister (#{@persister.class}) added: #{method_name} as field #{field_name}" ) - - # define event methods on self( binding ) and @object + @target = object.class + @field_name = options[:field_name] || StateFu::FuSpace.field_names[@target][method_name] + @persister = StateFu::Persistence.for( self ) + + # define event methods on this binding and its @object StateFu::MethodFactory.new( self ).install! - machine.helpers.inject_into( self ) - # StateFu::Persistence.prepare_field( @object.class, field_name ) + @machine.helpers.inject_into( self ) end alias_method :o, :object alias_method :obj, :object @@ -41,10 +35,10 @@ module StateFu alias_method :workflow, :machine alias_method :state_machine, :machine - def object=( reference ) - raise ArgumentError.new( reference ) unless object == reference - @object = reference - end + # def object=( reference ) + # raise ArgumentError.new( reference ) unless object == reference + # @object = reference + # end def reload() if persister.is_a?( Persistence::ActiveRecord ) @@ -54,11 +48,6 @@ module StateFu self end - # 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 lib/state_fu/binding.rb @@ -1,4 +1,5 @@ require 'rubygems' + # ruby1.9 style symbol comparability for ruby1.8 class Symbol # :nodoc: unless instance_methods.include?(:'<=>') @@ -19,5 +20,4 @@ unless Object.const_defined?('ActiveSupport') # :nodoc: class Hash #:nodoc: include ActiveSupport::CoreExtensions::Hash::Keys end - end lib/state_fu/core_ext.rb @@ -29,25 +29,6 @@ module StateFu origin_names.include?( state.to_sym ) end - # 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 ) @@ -58,17 +39,6 @@ module StateFu update_state_collection( '@targets', *args ) end - - # 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 @@ -86,6 +56,32 @@ module StateFu !! ( origins && target ) 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 + + # <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 + + # + # Lathe methods + # + + # adds an event requirement. + # TODO MOREDOC + def requires( *args, &block ) + lathe.requires( *args, &block ) + 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 @@ -115,19 +111,26 @@ 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 + private + + # 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 end end lib/state_fu/event.rb @@ -20,7 +20,7 @@ module StateFu end def inspect - "<StateFu::RequirementError #{message} #{@transition.origin.name}=[#{@transition.event.name}]=>#{transition.target.name}" + "<StateFu::RequirementError #{message} #{@transition.origin.name}=[#{@transition.event.name}]=>#{transition.target.name}>" end end lib/state_fu/exceptions.rb @@ -3,12 +3,12 @@ module StateFu # In most cases you won't need to access it directly, though # calling reset! before each of your tests/specs can be helpful. class FuSpace - cattr_reader :named_machines, :class_machines, :field_names + cattr_reader :machines, :field_names # 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 + # * machines[ Klass ][ nil ] # => Klass's default Machine + # * machines[ Klass ][ :status ] # => Klass's :status Machine # * field_names[ Class ][ method_name ] # => name of attribute / db field # LAZY_HASH = lambda do |h, k| @@ -19,33 +19,56 @@ module StateFu end end - # Add a machine to StateFu::FuSpace and register it with a given class, by a given name. - def self.insert!( klass, machine, name, field_name ) - name = name.to_sym - field_name = field_name.to_sym - existing_machine = @@class_machines[klass][name] - if existing_machine && !existing_machine.empty? - raise("#{klass} already knows a non-empty Machine #{machine} by the name #{name}.") - else - @@class_machines[klass][name] = machine - @@field_names[klass][name] = field_name - end + def self.machines + @@machines end - class << self - alias_method :insert, :insert! + + # make it so that a class which has included StateFu has a binding to + # this machine + def self.bind!( machine, owner, name, field_name) + insert!( owner, machine, name, field_name ) + # method_missing to catch NoMethodError for event methods, etc + StateFu::MethodFactory.prepare_class( owner ) + + # define an accessor method with the given name + if owner.class == Class + 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 + # singleton machines + raise NotImplementedError, "StateFu::FuSpace doesn't support singleton machines yet" + # + # prepare the eigenclass ? + # + end end + # Add a machine to StateFu::FuSpace and register it with a given class, by a given name. + # Binds a machine to a class, with a given name and field_name + def self.insert!( owner, machine, name, field_name ) + name = name.to_sym + @@machines[owner][name] = machine + @@field_names[owner][name] = field_name.to_sym + end + # Clears all machines and their bindings to classes. # Also initializes the hashes we use to store our references. - def self.beginners_mind! - @@named_machines = Hash.new - @@class_machines = Hash.new( &LAZY_HASH ) + def self.reset! + @@machines = Hash.new( &LAZY_HASH ) @@field_names = Hash.new( &LAZY_HASH ) end class << self - alias_method :reset!, :beginners_mind! - alias_method :forget!, :beginners_mind! - end - beginners_mind! + alias_method :init!, :reset! + end + + init! + end end lib/state_fu/fu_space.rb @@ -1,5 +1,5 @@ module StateFu - + # Utilities and snippets module Helper @@ -38,236 +38,4 @@ module StateFu end - # Stuff shared between StateArray and EventArray - module ArrayWithSymbolAccessor - # Pass a symbol to the array and get the object with that .name - # [<Foo @name=:bob>][:bob] - # => <Foo @name=:bob> - def []( idx ) - begin - super( idx ) - rescue TypeError => e - if idx.respond_to?(:to_sym) - self.detect { |i| i == idx || i.respond_to?(:name) && i.name == idx.to_sym } - else - raise e - end - end - end - - # so we can go Machine.states.names - # mildly helpful with irb + readline - def names - map(&:name) - end - - # SPECME - def except *syms - reject {|el| syms.flatten.compact.map(&:to_sym).include?(el.to_sym) } #.extend ArrayWithSymbolAccessor - end - - def only *syms - select {|el| syms.flatten.compact.map(&:to_sym).include?(el.to_sym) } #.extend ArrayWithSymbolAccessor - end - - end - - # Array extender. Used by Machine to keep a list of states. - module StateArray - include ArrayWithSymbolAccessor - - # 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 - - # Array extender. Used by Machine to keep a list of events. - module EventArray - include ArrayWithSymbolAccessor - - # return all events transitioning from the given state - def from( origin ) - select { |e| e.respond_to?(:from?) && e.from?( origin ) } - end - - # return all events transitioning to the given state - def to( target ) - select { |e| e.respond_to?(:to?) && e.to?( target ) } - end - - # 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 - - module ModuleRefArray - def modules - self.map do |h| - case h - when String, Symbol - mod_name = h.to_s.split('/').inject(Object) do |mod, part| - mod = mod.const_get( part.camelize ) - end - when Module - h - else - raise ArgumentError.new( h.class.inspect ) - end - end - end # modules - - def inject_into( obj ) - metaclass = class << obj; self; end - mods = self.modules() - metaclass.class_eval do - mods.each do |mod| - include( mod ) - end - end - end - end - - # Array extender. Used by Machine to keep a list of helpers to mix into - # context objects. - module HelperArray - include ModuleRefArray - end - - module ToolArray - include ModuleRefArray - end - - # Extend an Array with this. It's a fairly compact implementation, - # though it won't be super fast with lots of elements. - # items. Internally objects are stored as a list of - # [:key, 'value'] pairs. - module OrderedHash - # if given a symbol / string, treat it as a key - def []( index ) - begin - super( index ) - rescue TypeError - ( x = self.detect { |i| i.first == index }) && x[1] - end - end - - # hash-style setter - def []=( index, value ) - begin - super( index, value ) - rescue TypeError - ( x = self.detect { |i| i.first == index }) ? - x[1] = value : self << [ index, value ].extend( OrderedHash ) - end - end - - # poor man's Hash.keys - def keys - map(&:first) - end - - # poor man's Hash.values - def values - map(&:last) - 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. Ruby bug! - def limit_arguments( block, *args ) - case block.arity - when -1, 0 - nil - else - args[0 .. (block.arity - 1) ] - end - end - - def evaluate( *args, &proc ) - if proc.arity > 0 - args = limit_arguments( proc, *args ) - object.instance_exec( *args, &proc ) - else - instance_eval( &proc ) - end - end - - def call_on_object_with_optional_args( name, *args ) - if meth = object.method( name ) - args = limit_arguments( meth, *args ) - if args.nil? - object.send( name ) - else - object.send( name, *args ) - end - else - raise NoMethodError.new( "undefined method #{name} for #{object.inspect}" ) - end - end - - def call_on_object_with_self( name ) - call_on_object_with_optional_args( name, self ) - end - - def evaluate_named_proc_or_method( name, *args ) - if (name.is_a?( Proc ) && proc = name) || proc = machine.named_procs[ name ] - evaluate( *args, &proc ) - 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 - - def find_event_target( evt, tgt ) - case tgt - when StateFu::State - tgt - when Symbol - binding && binding.machine.states[ tgt ] # || raise( tgt.inspect ) - when NilClass - evt.respond_to?(:target) && evt.target - else - raise ArgumentError.new( "#{tgt.class} is not a Symbol, StateFu::State or nil (#{evt})" ) - end - end - end - - def self.included( klass ) - klass.send :include, InstanceMethods - end - end end lib/state_fu/helper.rb @@ -42,7 +42,7 @@ module StateFu # return a hash of :name => StateFu::Machine for your class. def machines( *args, &block ) if args.empty? && !block_given? - StateFu::FuSpace.class_machines[self] + StateFu::FuSpace.machines[self] else machine( *args, &block) end @@ -54,7 +54,7 @@ module StateFu # return the list of machines names for this class def machine_names() - StateFu::FuSpace.class_machines[self].keys + StateFu::FuSpace.machines[self].keys end alias_method :stfu_names, :machine_names alias_method :state_fu_names, :machine_names @@ -82,7 +82,7 @@ module StateFu public def _binding( name=StateFu::DEFAULT_MACHINE ) name = name.to_sym - if mach = StateFu::FuSpace.class_machines[self.class][name] + if mach = StateFu::FuSpace.machines[self.class][name] _state_fu[name] ||= StateFu::Binding.new( mach, self, name ) end end lib/state_fu/interface.rb @@ -8,6 +8,8 @@ module StateFu class Lathe # NOTE: Sprocket is the abstract superclass of Event and State + # @sprocket can be either nil (the main Lathe for a Machine) + # or contain a State or Event (a child lathe for a nested block) attr_reader :machine, :sprocket, :options @@ -36,7 +38,9 @@ module StateFu end end - private + # + # utility methods + # # a 'child' lathe is created by apply_to, to deal with nested # blocks for states / events ( which are sprockets ) @@ -49,82 +53,14 @@ module StateFu !child? end + # get the top level Lathe for the machine def master_lathe machine.lathe end - # instantiate a child lathe and apply the given block - def apply_to( sprocket, options, &block ) - StateFu::Lathe.new( machine, sprocket, options, &block ) - sprocket - end - - # require that the current sprocket be of a given type - def require_sprocket( *valid_types ) - raise ArgumentError.new("Lathe is for a #{sprocket.class}, not one of #{valid_types.inspect}") unless valid_types.include?( sprocket.class ) - end - - # ensure this is not a child lathe - def require_no_sprocket() - require_sprocket( NilClass ) - end - - # abstract method for defining states / events - def define_sprocket( type, name, options={}, &block ) - name = name.to_sym - klass = StateFu.const_get((a=type.to_s.split('',2);[a.first.upcase, a.last].join)) - collection = machine.send("#{type}s") - options.symbolize_keys! - if sprocket = collection[name] - apply_to( sprocket, options, &block ) - sprocket - else - sprocket = klass.new( machine, name, options ) - collection << sprocket - apply_to( sprocket, options, &block ) - sprocket - end - end - - def define_state( name, options={}, &block ) - define_sprocket( :state, name, options, &block ) - end - - def define_event( name, options={}, &block ) - define_sprocket( :event, name, options, &block ) - end - - def define_hook slot, method_name=nil, &block - unless sprocket.hooks.has_key?( slot ) - raise ArgumentError, "invalid hook type #{slot.inspect} for #{sprocket.class}" - end - if block_given? - # unless (-1..1).include?( block.arity ) - # raise ArgumentError, "unexpected block arity: #{block.arity}" - # end - case method_name - when Symbol - machine.named_procs[method_name] = block - hook = method_name - when NilClass - hook = block - # allow only one anonymous hook per slot in the interests of - # sanity - replace any pre-existing ones - sprocket.hooks[slot].delete_if { |h| Proc === h } - else - raise ArgumentError.new( method_name.inspect ) - end - elsif method_name.is_a?( Symbol ) # no block - hook = method_name - # prevent duplicates - sprocket.hooks[slot].delete_if { |h| hook == h } - else - raise ArgumentError, "#{method_name.class} is not a symbol" - end - sprocket.hooks[slot] << hook - end - - public + # + # methods for extending the DSL + # # helpers are mixed into all binding / transition contexts def helper( *modules ) @@ -139,9 +75,18 @@ module StateFu end # - # event definition + # event definition methods # + # Defines an event. Any options supplied will be added to the event, + # except :from and :to which are used to define the origin / target + # states. Successive invocations will _update_ (not replace) previously + # defined events; origin / target states and options are always + # accumulated, not clobbered. + # + # Several different styles of definition are available. Consult the + # specs / features for examples. + def event( name, options={}, &block ) options.symbolize_keys! require_sprocket( StateFu::State, NilClass ) @@ -161,6 +106,15 @@ module StateFu end end + # define an event or state requirement. + # options: + # :on => :entry|:exit|array (state only) - check requirement on state entry, exit or both? + # default = :entry + # :message => string|proc|proc_name_symbol - message to be returned on requirement failure. + # if a proc or symbol (named proc identifier), evaluated at runtime; a proc should + # take one argument, which is a StateFu::Transition. + # :msg => alias for :message, for the morbidly terse + def requires( *args, &block ) require_sprocket( StateFu::Event, StateFu::State ) options = args.extract_options!.symbolize_keys! @@ -205,28 +159,42 @@ module StateFu evt.from sprocket evt.to sprocket evt - # raise NotImplementedError end # # state definition # + # define the initial_state (otherwise defaults to the first state mentioned) def initial_state( *args, &block ) require_no_sprocket() machine.initial_state= state( *args, &block) end + # define a state; given a block, apply the block to a Lathe for the state def state( name, options={}, &block ) require_no_sprocket() define_state( name, options, &block ) end + # + # Event definition + # + + # set the origin state(s) of an event (or, given a hash of symbols / arrays + # of symbols, set both the origins and targets) + # from :my_origin + # from [:column_a, :column_b] + # from :eden => :armageddon + # from [:beginning, :prelogue] => [:ende, :prologue] def from *args, &block require_sprocket( StateFu::Event ) sprocket.from( *args, &block ) end + # set the target state(s) of an event + # to :destination + # to [:end, :finale, :intermission] def to *args, &block require_sprocket( StateFu::Event ) sprocket.to( *args, &block ) @@ -260,17 +228,8 @@ module StateFu end # - # do something with all states / events + # Define a series of states at once, or return and iterate over all states yet defined # - def each_sprocket( type, *args, &block) - - options = args.extract_options!.symbolize_keys! - if args == [:ALL] || args == [] - args = machine.send("#{type}s").except( options.delete(:except) ) - end - args.map { |name| self.send( type, name, options.dup, &block) }.extend StateArray - end - def states( *args, &block ) require_no_sprocket() each_sprocket( 'state', *args, &block ) @@ -278,6 +237,9 @@ module StateFu alias_method :all_states, :states alias_method :each_state, :states + # + # Define a series of events at once, or return and iterate over all events yet defined + # def events( *args, &block ) require_sprocket( NilClass, StateFu::State ) each_sprocket( 'event', *args, &block ) @@ -286,6 +248,7 @@ module StateFu alias_method :each_event, :events # Bunch of silly little methods for defining events + # :nodoc: def before *a, &b; require_sprocket( StateFu::Event ); define_hook :before, *a, &b; end def on_exit *a, &b; require_sprocket( StateFu::State ); define_hook :exit, *a, &b; end @@ -294,5 +257,94 @@ module StateFu def after *a, &b; require_sprocket( StateFu::Event ); define_hook :after, *a, &b; end def accepted *a, &b; require_sprocket( StateFu::State ); define_hook :accepted, *a, &b; end + # + # + # + + private + + # require that the current sprocket be of a given type + def require_sprocket( *valid_types ) + raise ArgumentError.new("Lathe is for a #{sprocket.class}, not one of #{valid_types.inspect}") unless valid_types.include?( sprocket.class ) + end + + # ensure this is not a child lathe + def require_no_sprocket() + require_sprocket( NilClass ) + end + + # instantiate a child Lathe and apply the given block + def apply_to( sprocket, options, &block ) + StateFu::Lathe.new( machine, sprocket, options, &block ) + sprocket + end + + # abstract method for defining states / events + def define_sprocket( type, name, options={}, &block ) + name = name.to_sym + klass = StateFu.const_get((a=type.to_s.split('',2);[a.first.upcase, a.last].join)) + collection = machine.send("#{type}s") + options.symbolize_keys! + if sprocket = collection[name] + apply_to( sprocket, options, &block ) + sprocket + else + sprocket = klass.new( machine, name, options ) + collection << sprocket + apply_to( sprocket, options, &block ) + sprocket + end + end + + # :nodoc: + def define_state( name, options={}, &block ) + define_sprocket( :state, name, options, &block ) + end + + # :nodoc: + def define_event( name, options={}, &block ) + define_sprocket( :event, name, options, &block ) + end + + # :nodoc: + def define_hook slot, method_name=nil, &block + unless sprocket.hooks.has_key?( slot ) + raise ArgumentError, "invalid hook type #{slot.inspect} for #{sprocket.class}" + end + if block_given? + # unless (-1..1).include?( block.arity ) + # raise ArgumentError, "unexpected block arity: #{block.arity}" + # end + case method_name + when Symbol + machine.named_procs[method_name] = block + hook = method_name + when NilClass + hook = block + # allow only one anonymous hook per slot in the interests of + # sanity - replace any pre-existing ones + sprocket.hooks[slot].delete_if { |h| Proc === h } + else + raise ArgumentError.new( method_name.inspect ) + end + elsif method_name.is_a?( Symbol ) # no block + hook = method_name + # prevent duplicates + sprocket.hooks[slot].delete_if { |h| hook == h } + else + raise ArgumentError, "#{method_name.class} is not a symbol" + end + sprocket.hooks[slot] << hook + end + + # :nodoc: + def each_sprocket( type, *args, &block) + options = args.extract_options!.symbolize_keys! + if args.empty? || args == [:ALL] + args = machine.send("#{type}s").except( options.delete(:except) ) + end + args.map { |name| self.send( type, name, options.dup, &block) }.extend StateArray + end + end end lib/state_fu/lathe.rb @@ -1,12 +1,13 @@ module StateFu class Machine - include Helper + include StateFu::Applicable # meta-constructor; expects to be called via Klass.machine() def self.for_class(klass, name, options={}, &block) options.symbolize_keys! name = name.to_sym - unless machine = StateFu::FuSpace.class_machines[ klass ][ name ] + + unless machine = StateFu::FuSpace.machines[ klass ][ name ] machine = new( name, options, &block ) machine.bind!( klass, name, options[:field_name] ) end @@ -66,32 +67,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=StateFu::DEFAULT_MACHINE, field_name = nil ) + field_name ||= "#{name.to_s.underscore.tr(' ','_')}#{StateFu::Persistence::DEFAULT_SUFFIX}" + StateFu::FuSpace.bind!(self, owner, name, field_name) end def empty? lib/state_fu/machine.rb @@ -11,7 +11,7 @@ module StateFu end def self.define_once_only_method_missing( klass ) - return if ( klass.instance_methods ).map(&:to_sym).include?( :method_missing_before_state_fu ) + return if klass.instance_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 ) @@ -19,12 +19,13 @@ module StateFu state_fu! # reset method_missing for this instance # more for tidy stack traces than anything else + # TODO - benchmark with presence / absence of this reset metaclass = class << self; self; end metaclass.instance_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 ) + end + # call the newly defined method, or the original method_missing + if respond_to?( method_name ) # it was defined by calling state_fu! send( method_name, *args, &block ) else method_missing_before_state_fu( method_name, *args, &block ) @@ -35,6 +36,9 @@ module StateFu # ensure the methods are available before calling state_fu def self.prepare_class( klass ) + unless klass.is_a?(Class) + raise NotImplementedError.new("singleton machines are not yet supported") + end self.define_once_only_method_missing( klass ) end # prepare_class lib/state_fu/method_factory.rb @@ -1,7 +1,9 @@ module StateFu - class MockTransition - include StateFu::Helper - include ContextualEval + # a fake transition which cannot be fired; useful for specs and for testing + # requirements + class MockTransition < Context + include Applicable + include Transitive attr_reader( :binding, :machine, lib/state_fu/mock_transition.rb @@ -1,10 +1,85 @@ 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_FIELD_NAME_SUFFIX = '_field' + DEFAULT_SUFFIX = '_field' + @@class_for = {} + @@fields_prepared = {} + # + # Class Methods + # + + # 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 + + # 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 + persister_class = class_for binding.target, field_name + if (klass = binding.target).is_a?(Class) + prepare_field( klass, field_name, persister_class) + end + returning persister_class.new( binding, field_name ) do |persister| + Logger.debug( "#{persister_class}: method #{binding.method_name} as field #{persister.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 if RelaxDB is not included. + # 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 ) && @@ -13,7 +88,7 @@ module StateFu # checks to see if the field_name for persistence is an # ActiveRecord column. - # Safe to use if ActiveRecord is not included. + # 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") && @@ -21,26 +96,6 @@ module StateFu klass.table_exists? && klass.columns.map(&:name).include?( field_name.to_s ) end - - # 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 - 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 ) - class_for( klass, field_name ).prepare_field( klass, field_name ) - end - + end end lib/state_fu/persistence.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 lib/state_fu/persistence/active_record.rb @@ -24,8 +24,9 @@ module StateFu end end + # define this method in subclasses to do any preparation def self.prepare_field( klass, field_name ) - raise NotImplementedError # abstract method + Logger.warn("Abstract method in #{self}.prepare_field called. Override me!") end def initialize( binding, field_name ) lib/state_fu/persistence/base.rb @@ -1,6 +1,8 @@ module StateFu - class Sprocket # Abstract Superclass of State & Event - include StateFu::Helper # define apply! + # the abstract superclass of State & Event + # defines behaviours shared by both classes + class Sprocket + include Applicable # define apply! attr_reader :machine, :name, :options, :hooks @@ -18,6 +20,7 @@ module StateFu @hooks[slot.to_sym] << [name.to_sym, value] end + # yields a lathe for self; useful for updating machine definitions on the fly def lathe(options={}, &block) StateFu::Lathe.new( machine, self, options, &block ) end @@ -38,6 +41,25 @@ module StateFu options[v]=k end + # allows state == <name> || event == <name> to return true + def == other + if other.is_a?(Symbol) + self.name == other + else + super other + end + end + + # allows case equality tests against the state/event's name + # eg + # case state + # when :new + # ... + # end + def === other + self.to_sym === other.to_sym || super(other) + end + end end lib/state_fu/sprocket.rb @@ -37,11 +37,6 @@ module StateFu end.empty? end - # allows @obj.state_fu.state === :new - def === other - self.to_sym === other.to_sym - end - # display nice and short def inspect s = self.to_s lib/state_fu/state.rb @@ -6,10 +6,10 @@ module StateFu # This is what gets yielded to event hooks; it also gets attached # to any TransitionHalted exceptions raised. - class Transition - include StateFu::Helper - include ContextualEval - + class Transition < Context + include Applicable # define apply! + include Transitive + attr_reader( :binding, :machine, :origin, lib/state_fu/transition.rb @@ -25,16 +25,16 @@ namespace :spec do t.verbose = true t.spec_opts = ["-c","-b","-u"] if ENV['L'] - t.spec_opts += ["-l", ENV["L"],"-f", "specdoc"] + t.spec_opts += ["-l", ENV["L"],"-f", "specdoc"] else - t.spec_opts += ["-f", "profile"] + t.spec_opts += ["-f", "profile"] end t.spec_files = FileList[specfile] end - - desc "runs the last modified spec; L=n runs only that line" + + desc "runs all specs, or those which last failed" Spec::Rake::SpecTask.new(:faily) do |t| - specfile = find_last_modified_spec || return + specfile = find_last_modified_spec || return faily = 'spec.fail' t.verbose = true t.spec_opts = ["-f","failing_examples:#{faily}", "-f","n","-c","-b","-u"] @@ -42,5 +42,5 @@ namespace :spec do t.spec_opts << ["-e",faily] end end - + end lib/tasks/spec_last.rake @@ -116,10 +116,14 @@ describe "A pristine class Klass with StateFu included:" do it "should know the Machine after calling Klass.machine.bind!( Child )" do Child.machine.should_not == Klass.machine Klass.machine.bind!( Child ) + StateFu::FuSpace.machines[Child].should == {:state_fu => Klass.machine} Child.machine.should == Klass.machine Klass.machine.bind!( Child, :snoo ) + StateFu::FuSpace.machines[Child].should == { + :state_fu => Klass.machine, + :snoo => Klass.machine + } Child.machine(:snoo).should == Klass.machine - end end spec/integration/class_accessor_spec.rb @@ -33,7 +33,7 @@ describe StateFu::Binding do describe "constructor" do before do - mock( StateFu::FuSpace ).field_names() do + mock( StateFu::FuSpace ).field_names.at_most(1) do { Klass => { :example => :example_field } } @@ -66,8 +66,8 @@ describe StateFu::Binding do describe "when StateFu::Persistence.active_record_column? is true" do before do - mock( StateFu::Persistence ).active_record_column?(Klass, :example_field).times(2) { true } - mock( Klass ).before_save( :state_fu!) { } + mock( StateFu::Persistence ).active_record_column?(Klass, :example_field).times(1) { true } + mock( Klass ).before_create( :state_fu!) { } end it "should get an ActiveRecord persister" do mock( StateFu::Persistence::ActiveRecord ).new( anything, :example_field ) { @p } @@ -78,7 +78,7 @@ describe StateFu::Binding do describe "when StateFu::Persistence.active_record_column? is false" do before do - mock( StateFu::Persistence ).active_record_column?(Klass, :example_field).times(2) { false } + mock( StateFu::Persistence ).active_record_column?(Klass, :example_field) { false } end it "should get an Attribute persister" do mock( StateFu::Persistence::Attribute ).new( anything, :example_field ) { @p } @@ -176,6 +176,8 @@ describe StateFu::Binding do end describe "when called with additional arguments after the destination event/state" do + + # This would make very little sense to someone trying to understand how to use the library. it "should pass the arguments to any requirements to determine transition availability" do set_method_arity( @obj, :tissue?, needed_arity = 1 ) mock(@obj).tissue?(is_a(StateFu::Transition)) {|t| t.args.should == [:a,:b] } spec/units/binding_spec.rb @@ -15,9 +15,9 @@ describe StateFu::FuSpace do end describe "Before any Machine is defined" do - it "should return {} given StateFu::FuSpace.class_machines()" do - StateFu::FuSpace.should respond_to(:class_machines) - StateFu::FuSpace.class_machines.should == {} + it "should return {} given StateFu::FuSpace.machines()" do + StateFu::FuSpace.should respond_to(:machines) + StateFu::FuSpace.machines.should == {} end end @@ -28,16 +28,16 @@ describe StateFu::FuSpace do StateFu::DEFAULT_MACHINE.should == :state_fu end - it "should return { Klass => { ... } } given StateFu::FuSpace.class_machines()" do - StateFu::FuSpace.should respond_to(:class_machines) - machines = StateFu::FuSpace.class_machines() + it "should return { Klass => { ... } } given StateFu::FuSpace.machines()" do + StateFu::FuSpace.should respond_to(:machines) + machines = StateFu::FuSpace.machines() machines.keys.should == [Klass] machines.values.first.should be_kind_of( Hash ) end - it "should return { :state_fu => <StateFu::Machine> } given StateFu::FuSpace.class_machines[Klass]" do - StateFu::FuSpace.should respond_to(:class_machines) - machines = StateFu::FuSpace.class_machines[Klass] + it "should return { :state_fu => <StateFu::Machine> } given StateFu::FuSpace.machines[Klass]" do + StateFu::FuSpace.should respond_to(:machines) + machines = StateFu::FuSpace.machines[Klass] machines.should be_kind_of(Hash) machines.should_not be_empty machines.length.should == 1 @@ -69,9 +69,9 @@ describe StateFu::FuSpace do end end - it "should return { :state_fu => <StateFu::Machine>, :two => <StateFu::Machine> } given StateFu::FuSpace.class_machines()" do - StateFu::FuSpace.should respond_to(:class_machines) - machines = StateFu::FuSpace.class_machines[Klass] + it "should return { :state_fu => <StateFu::Machine>, :two => <StateFu::Machine> } given StateFu::FuSpace.machines()" do + StateFu::FuSpace.should respond_to(:machines) + machines = StateFu::FuSpace.machines[Klass] machines.should be_kind_of(Hash) machines.should_not be_empty machines.length.should == 2 @@ -83,9 +83,9 @@ describe StateFu::FuSpace do before(:each) do StateFu::FuSpace.reset! end - it "should return {} given StateFu::FuSpace.class_machines()" do - StateFu::FuSpace.should respond_to(:class_machines) - StateFu::FuSpace.class_machines.should == {} + it "should return {} given StateFu::FuSpace.machines()" do + StateFu::FuSpace.should respond_to(:machines) + StateFu::FuSpace.machines.should == {} end end spec/units/fu_space_spec.rb @@ -20,7 +20,7 @@ describe StateFu::Machine do before do reset! make_pristine_class 'Klass' - mock( StateFu::FuSpace ).class_machines() { { Klass => {} } } + mock( StateFu::FuSpace ).machines() { { Klass => {} } } end it "should create a new machine and bind! it" do @@ -41,7 +41,7 @@ describe StateFu::Machine do describe "when there's a matching machine in FuSpace" do it "should retrieve the previously created machine" do @machine = Object.new - mock( StateFu::FuSpace ).class_machines() { { Klass => { :moose => @machine } } } + mock( StateFu::FuSpace ).machines() { { Klass => { :moose => @machine } } } StateFu::Machine.for_class( Klass, :moose ).should == @machine end end @@ -92,7 +92,7 @@ describe StateFu::Machine do klass = Klass name = :StinkJuice field_name = 'stink_juice_field' - mock( StateFu::FuSpace ).insert!( Klass, @mchn, name, field_name.to_sym ) {} + mock( StateFu::FuSpace ).insert!( Klass, @mchn, name, field_name ) {} @mchn.bind!( Klass, name ) end end spec/units/machine_spec.rb @@ -16,8 +16,7 @@ describe StateFu::MethodFactory do @machine = Klass.machine do event( :simple_event, :from => { [:a, :b] => :targ } ) - - state( :a ) { cycle } + state( :a ) { cycle } end # machine @obj = Klass.new end @@ -48,7 +47,13 @@ describe StateFu::MethodFactory do it "should call state_fu!" do mock.proxy( StateFu::Binding ).new( Klass.machine, @obj, :state_fu ) + @obj + @obj.private_methods.map(&:to_sym).should include(:state_fu_field) + #@obj.should respond_to :state_fu_field + @obj.state_fu.machine.events.should_not be_empty + @obj.simple_event! + # @obj.should_have_received( :state_fu! ) end spec/units/method_factory_spec.rb 93dea7e4919386fed0c1bc4754e6348bd22758bc davidlee david@davelee.com.au http://github.com/davidlee/state-fu/commit/32173785a31862ce6c09b67910ae3e542e0016ab 32173785a31862ce6c09b67910ae3e542e0016ab 2009-08-04T17:36:40-07:00 2009-08-04T17:36:40-07:00 Version bump to 0.4.0 110c779c45f65d1f60974359df39cabde1ba2881 davidlee david@davelee.com.au