@@ -4,6 +4,14 @@ module StateFu attr_reader :object, :machine, :method_name, :persister, :transitions, :options + # the constructor should not be called manually; a binding is + # returned when an instance of a class with a StateFu::Machine + # calls: + # + # instance.#state_fu (for the default machine which is called :state_fu), + # instance.#state_fu( :<machine_name> ) ,or + # instance.#<machine_name> + # def initialize( machine, object, method_name, options={} ) @machine = machine @object = object @@ -33,10 +41,12 @@ module StateFu alias_method :workflow, :machine alias_method :state_machine, :machine + # the perister's field_name (a symbol) def field_name persister.field_name end + # the current_state, as maintained by the persister. def current_state persister.current_state end @@ -44,6 +54,7 @@ module StateFu alias_method :now, :current_state alias_method :state, :current_state + # the name, as a Symbol, of the binding's current_state def current_state_name begin current_state.name.to_sym @@ -55,19 +66,22 @@ module StateFu alias_method :state_name, :current_state_name alias_method :to_sym, :current_state_name - # a list of events which can fire from the current_state + # returns a list of StateFu::Events which can fire from the current_state def events machine.events.select {|e| e.complete? && e.from?( current_state ) }.extend EventArray end alias_method :events_from_current_state, :events # the subset of events() whose requirements for firing are met + # (with the arguments supplied, if any) def valid_events( *args ) return nil unless current_state return [] unless current_state.exitable_by?( self, *args ) events.select {|e| e.fireable_by?( self, *args ) }.extend EventArray end + # the subset of events() whose requirements for firing are NOT met + # (with the arguments supplied, if any) def invalid_events( *args ) ( events - valid_events( *args ) ).extend StateArray end @@ -84,6 +98,7 @@ module StateFu vt && vt.values.flatten.uniq.extend( StateArray ) end + # def next_states events.map(&:targets).compact.flatten.uniq.extend StateArray end @@ -101,7 +116,11 @@ module StateFu h end - # initialize a new transition + # initializes a new Transition to the given destination, with the + # given *args (to be passed to requirements and hooks). + # + # If a block is given, it yields the Transition or is executed in + # its evaluation context, depending on the arity of the block. def transition( event_or_array, *args, &block ) event, target = parse_destination( event_or_array ) StateFu::Transition.new( self, event, target, *args, &block ) @@ -112,17 +131,24 @@ module StateFu alias_method :trigger_event, :transition alias_method :begin_transition, :transition + # return a MockTransition to nowhere and passes it the given + # *args. Useful for evaluating requirements in spec / test code. def blank_mock_transition( *args, &block ) StateFu::MockTransition.new( self, nil, nil, *args, &block ) end + # return a MockTransition; otherwise the same as #transition def mock_transition( event_or_array, *args, &block ) event, target = nil event, target = parse_destination( event_or_array ) StateFu::MockTransition.new( self, event, target, *args, &block ) end - # sanitize args for fire! and fireable? + # sanitizes / extracts destination from *args for other methods. + # + # takes a single, simple (one target only) event, + # or an array of [event, target], + # or one of the above with symbols in place of the objects themselves. def parse_destination( event_or_array ) case event_or_array when StateFu::Event, Symbol @@ -138,7 +164,8 @@ module StateFu [event, target] end - # check that the event and target are "valid" (all requirements met) + # check that the event and target are valid (all requirements are + # met) with the given (optional) arguments def fireable?( event_or_array, *args ) event, target = parse_destination( event_or_array ) begin @@ -185,33 +212,8 @@ module StateFu alias_method :evaluate_requirement_with_transition, :evaluate_named_proc_or_method - # TODO SPECME HACKERY CRUFT FIXME THISSUCKS and needs *args - # def evaluate_requirement_message( name, dest ) - # # puts "#{name} #{dest}" - # msg = machine.requirement_messages[name] - # if [String, NilClass].include?( msg.class ) - # return msg - # else - # if dest.is_a?( StateFu::Transition ) - # t = dest - # else - # event, target = parse_destination( event_or_array ) - # t = transition( event, target ) - # end - # case msg - # when Symbol, Proc - # puts t.class - # evaluate_named_proc_or_method( msg, t ) - # # when Proc - # # t.evaluate &msg - # end - # end - # end - - # if there is one simple event, return a transition for it - # else return nil - # TODO - not convinced about the method name / aliases - but next - # is reserved :/ + # if there is exactly one legal transition which can be fired with + # the given (optional) arguments, return it. def next_transition( *args, &block ) vts = valid_transitions( *args ) return nil if vts.nil? @@ -224,11 +226,15 @@ module StateFu end end + # if there is exactly one state reachable via a transition which + # is valid with the given optional arguments, return it. def next_state( *args ) nt = next_transition( *args ) nt && nt.target end + # if there is exactly one event which is valid with the given + # optional arguments, return it def next_event( *args ) nt = next_transition( *args ) nt && nt.event lib/state_fu/binding.rb @@ -2,32 +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") && @@ -35,6 +21,7 @@ module StateFu 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 @@ -45,6 +32,7 @@ module StateFu 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 lib/state_fu/persistence.rb ec00948c26b45a72a905e4d216433239dfd16934 davidlee david@davelee.com.au http://github.com/davidlee/state-fu/commit/f0abe614bec6405f0dda064e4e470a168806f048 f0abe614bec6405f0dda064e4e470a168806f048 2009-06-25T05:30:03-07:00 2009-06-25T05:30:03-07:00 refactoring code comments for Persistence and Binding 4262da328d4f4872df15ae5734057937e4f8b13d davidlee david@davelee.com.au