LICENSE @@ -24,7 +24,7 @@ require 'state_fu/hooks' require 'state_fu/interface' module StateFu - DEFAULT_KOAN = :om + DEFAULT_MACHINE = :om def self.included( klass ) klass.extend( Interface::ClassMethods ) lib/state-fu.rb @@ -4,7 +4,7 @@ module StateFu attr_reader :object, :machine, :method_name, :persister def initialize( machine, object, method_name ) - @machine = machine + @machine = machine @object = object @method_name = method_name @@ -12,9 +12,14 @@ module StateFu @persister = StateFu::Persistence.for( self, field_name ) Logger.info( "Persister added: #@persister ") end - alias_method :machinist, :object - alias_method :model, :object - alias_method :instance, :object + alias_method :o, :object + alias_method :obj, :object + alias_method :model, :object + alias_method :instance, :object + + alias_method :machine, :machine + alias_method :workflow, :machine + alias_method :state_machine, :machine def field_name persister.field_name @@ -23,7 +28,31 @@ module StateFu def current_state persister.current_state end + alias_method :at, :current_state + alias_method :state, :current_state - end + # fire event + def fire!( event, target_state=nil, *args, &block) + raise "!" + end + alias_method :call!, :fire! + alias_method :trigger!, :fire! + alias_method :transition!, :fire! + + # fire event to move to the next state, if there is only one possible state. + # otherwise raise an error ( NoNextStateError) + def next!( *args, &block) + raise "!" + end + alias_method :next_state!, :next! + + # fire event + def fire!( event_or_event_name, *args, &block) + raise "!" + end + alias_method :call!, :fire! + alias_method :trigger!, :fire! + alias_method :transition!, :fire! + end end lib/state_fu/binding.rb @@ -12,7 +12,7 @@ module StateFu # return the default machine, or an empty hash, given a missing index. LAZY_HASH = lambda do |h, k| if k.nil? - self[ StateFu::DEFAULT_KOAN ] + self[ StateFu::DEFAULT_MACHINE ] else h[k]= Hash.new() end lib/state_fu/fu_space.rb @@ -46,7 +46,7 @@ module StateFu super( idx ) rescue TypeError => e if idx.respond_to?(:to_sym) - self.detect { |i| i.respond_to?(:name) && i.name == idx.to_sym } + self.detect { |i| i == idx || i.respond_to?(:name) && i.name == idx.to_sym } else raise e end @@ -64,6 +64,16 @@ module StateFu # Array extender. Used by Machine to keep a list of states. module StateArray include StateOrEventArray + + # is there exactly one possible event to fire, with a single + # target event? + def next? + end + + # if next?, return the state + def next + end + end # Array extender. Used by Machine to keep a list of events. @@ -79,6 +89,16 @@ module StateFu 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? + end + + # if next?, return the event + def next + end + end # Array extender. Used by Machine to keep a list of helpers to mix into lib/state_fu/helper.rb @@ -3,38 +3,45 @@ module StateFu # Provides access to StateFu to your classes. Plenty of aliases are # provided so you can use whatever makes sense to you. module ClassMethods + # TODO: + # take option :alias => false (disable aliases) or :alias + # => :foo (use foo as class & instance accessor) + # # Given no arguments, return the default machine (:om) for the - # class, if it exists (or nil). + # class, creating it if it did not exist. # - # Given a symbol, return the machine by that name if it exists - # (or nil). + # Why is it called :om? This library was originally called + # Zen::Koan, and this remains in tribute. # - # Given a block, create the machine (:om if no name is supplied) - # if it does not yet exist, and define it with the contents of - # the block. + # Given a symbol, return the machine by that name, creating it + # if it didn't exist. # - # This can be done multiple times; changes are cumulative. + # Given a block, also define it with the contents of the block. # - # Calling Klass.machine with or without a block will create one if - # it does not exist, and bind it to your class. + # This can be done multiple times; changes are cumulative. # - # You can have as many as you like per class. + # You can have as many machines as you like per class. # # Klass.machine # the default machine named :om - # # equivalent to Klass.machine(:om) + # # equivalent to Klass.machine(:om) # Klass.machine(:workflow) # another totally separate machine - + # # machine( name=:om, options[:field_name], &block ) + def machine( *args, &block ) options = args.extract_options!.symbolize_keys! - name = args[0] || StateFu::DEFAULT_KOAN + name = args[0] || StateFu::DEFAULT_MACHINE StateFu::Machine.for_class( self, name, options, &block ) end - alias_method :statefully, :machine - alias_method :machine, :machine + alias_method :stfu, :machine + alias_method :state_fu, :machine alias_method :workflow, :machine + alias_method :statefully, :machine alias_method :state_machine, :machine + alias_method :stateful, :machine + alias_method :workflow, :machine + alias_method :engine, :machine # return a hash of :name => StateFu::Machine for your class. def machines( *args, &block ) @@ -46,18 +53,18 @@ module StateFu end alias_method :machines, :machines alias_method :workflows, :machines - alias_method :zen_machines, :machines + alias_method :engines, :machines # return the list of machines names for this class def machine_names() StateFu::FuSpace.class_machines[self].keys end - alias_method :machine_names, :machine_names - alias_method :workflow_names, :machine_names - alias_method :zen_machine_names, :machine_names + alias_method :machine_names, :machine_names + alias_method :workflow_names, :machine_names + alias_method :engine_names, :machine_names end - # Give the gift of self-awareness to your objects. These methods + # Give the gift of state to your objects. These methods # grant access to StateFu::Binding objects, which are bundles of # context linking a StateFu::Machine to an object / instance. # Again, plenty of aliases are provided so you can use whatever @@ -68,10 +75,9 @@ module StateFu @_om ||= {} end - # .om() is the instance method your objects use to meditate. - # - # A StateFu::Binding comes into being, linking your object and - # a machine, when you first call om() for that machine. + # A StateFu::Binding comes into being, linking your object and a + # machine, when you first call yourobject.binding() for that + # machine. # # Like the class method .machine(), calling it without any arguments # is equivalent to passing :om. @@ -80,46 +86,56 @@ module StateFu # can see and change its state, interact with events, etc. # public - def om( machine_name=StateFu::DEFAULT_KOAN ) - name = machine_name.to_sym - if machine = StateFu::FuSpace.class_machines[self.class][name] - _om[name] ||= StateFu::Binding.new( machine, self, name ) + def binding( name=StateFu::DEFAULT_MACHINE ) + name = name.to_sym + if mach = StateFu::FuSpace.class_machines[self.class][name] + _om[name] ||= StateFu::Binding.new( mach, self, name ) end end - alias_method :stateful, :om - alias_method :zen, :om - alias_method :machine, :om - alias_method :zen_machine, :om - alias_method :binding, :om - alias_method :machine, :om - alias_method :present, :om + alias_method :fu, :binding + alias_method :stfu, :binding + alias_method :state_fu, :binding + alias_method :stateful, :binding + alias_method :workflow, :binding + alias_method :engine, :binding + alias_method :machine, :binding # not strictly accurate, but makes sense sometimes + alias_method :context, :binding + alias_method :om, :binding # historical # Gain awareness of all bindings (state contexts) this object # has contemplated into being. # Returns a Hash of { :name => <StateFu::Binding>, ... } def bindings() _om end - alias_method :oms, :bindings - alias_method :machines, :bindings - alias_method :zen_machines, :bindings - alias_method :machines, :bindings - # Instant enlightenment. Instantiate all bindings. + alias_method :fus, :bindings + alias_method :stfus, :bindings + alias_method :state_fus, :bindings + alias_method :state_foos, :bindings + alias_method :workflows, :bindings + alias_method :engines, :bindings + alias_method :bindings, :bindings + alias_method :machines, :binding # not strictly accurate, but makes sense sometimes + alias_method :contexts, :bindings + + # Instantiate bindings for all machines defined for this class. # It's useful to call this before_create w/ # ActiveRecord classes, as this will cause the database field # to be populated with the default state name. - def meditate!( *names ) + def assemble!( *names ) if [names || [] ].flatten!.map! {|n| n.to_sym }.empty? names = self.class.machine_names() end - names.map { |n| om( n ) } + names.map { |n| binding( n ) } end - alias_method :initialize_state!, :meditate! - alias_method :zen!, :meditate! - alias_method :machine_init!, :meditate! - alias_method :awaken!, :meditate! - + alias_method :fu!, :assemble! + alias_method :stfu!, :assemble! + alias_method :state_fu!, :assemble! + alias_method :init_machines!, :assemble! + alias_method :initialize_state!, :assemble! + alias_method :build_workflow!, :assemble! + alias_method :meditate!, :assemble! # historical end end end lib/state_fu/interface.rb @@ -8,7 +8,7 @@ module StateFu end def initialize( machine, sprocket = nil, options={}, &block ) - @machine = machine + @machine = machine @sprocket = sprocket if sprocket sprocket.apply!( options ) @@ -76,12 +76,14 @@ module StateFu # helpers are mixed into all binding / transition contexts # use them to bend the language to your will - def helper( *names ) - names.each do |name| - const_name = name.to_s.camelize - # if we can't find it now, try later in the machinist object's context - machine.helpers << (const_name.constantize rescue const_name ) - end + def helper_( *modules ) + machine.helpers += modules + machine.helpers.extend( HelperArray ) + # names.each do |name| + # const_name = name.to_s.camelize + # # if we can't find it now, try later in the machinist object's context + # machine.helpers << (const_name.constantize rescue const_name ) + # end end # @@ -111,6 +113,13 @@ module StateFu # ... end + # create an event from *and* to the current state. + # Creates a loop, useful (only) for hooking behaviours onto. + def cycle( name, options={}, &block ) + require_sprocket( StateFu::State ) + # + end + # # state definition # lib/state_fu/lathe.rb @@ -8,7 +8,8 @@ module StateFu # analogous to self.for_class, but keeps machines in # global space, not tied to a specific class. def self.[] name, options, &block - # ... + # ... use case? + raise "pending" end # meta-constructor; expects to be called via Klass.machine() @@ -43,23 +44,37 @@ module StateFu StateFu::Lathe.new( self, &block ) end - # the Machine teaches a class how to meditate on it: - def teach!( klass, name=StateFu::DEFAULT_KOAN, field_name = nil ) + # 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. + # + # To do this globally, just duck-punch StateFu::Machine / + # StateFu::Binding. + def helper *modules + raise "pending" + 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.downcase.tr(' ', '_') + "_state" field_name = field_name.to_sym StateFu::FuSpace.insert!( klass, self, name, field_name ) end - alias_method :bind!, :teach! + alias_method :teach!, :bind! # TODO remove def empty? states.empty? end - def initial_state=( state ) - unless state.is_a?( StateFu::State ) - state = states[ state.to_sym ] || raise( ArgumentError, state.inspect ) + def initial_state=( s ) + case s + when Symbol, String, StateFu::State + @initial_state = states[ s.to_sym ] || StateFu::State.new( self, s.to_sym ) + else + raise( ArgumentError, s.inspect ) end - @initial_state = state end def initial_state() lib/state_fu/machine.rb @@ -10,7 +10,7 @@ module StateFu end def self.for( binding, field_name ) - if active_record_column?( binding.machinist, field_name ) + if active_record_column?( binding.object, field_name ) self::ActiveRecord.new( binding, field_name ) else self::Attribute.new( binding, field_name ) lib/state_fu/persistence.rb @@ -37,7 +37,7 @@ module StateFu end def object - binding.machinist + binding.object end def klass lib/state_fu/persistence/base.rb @@ -99,7 +99,6 @@ module StateFu # Try to give as many options (chances) as possible # - alias_method :machinist, :object alias_method :obj, :object alias_method :instance, :object alias_method :model, :object lib/state_fu/transition.rb @@ -37,7 +37,7 @@ describe "A pristine class Klass with StateFu included:" do before(:each) do Klass.machine do end - StateFu::DEFAULT_KOAN.should == :om + StateFu::DEFAULT_MACHINE.should == :om end it "should return a StateFu::Machine given Klass.machine()" do spec/integration/class_accessor_spec.rb @@ -29,7 +29,7 @@ describe "An instance of Klass with StateFu included:" do before(:each) do Klass.machine do end - StateFu::DEFAULT_KOAN.should == :om + StateFu::DEFAULT_MACHINE.should == :om end it "should return a StateFu::Binding given .om()" do @@ -71,8 +71,8 @@ describe "An instance of Klass with StateFu included:" do end it "should return the same Binding given .om() and .om(:om)" do - @k.om().should be_kind_of( StateFu::Binding ) - @k.om().should == @k.om(:om) + @k.binding().should be_kind_of( StateFu::Binding ) + @k.binding().should == @k.om(:om) end it "should return a StateFu::Binding given .om(:two)" do spec/integration/instance_accessor_spec.rb @@ -16,10 +16,10 @@ describe StateFu::Binding do describe "initialization via @obj.om()" do it "should create a new StateFu::Binding" do - mdn = @obj.om() + mdn = @obj.binding() mdn.should be_kind_of( StateFu::Binding ) mdn.machine.should == Klass.machine - mdn.machinist.should == @obj + mdn.object.should == @obj mdn.method_name.should == :om mdn.field_name.should == :om_state end @@ -43,12 +43,12 @@ describe StateFu::Binding do # initial_state :fetus end @machine = Klass.machine() - @object = Klass.new() - @om = @object.om() + @object = Klass.new() + @binding = @object.stfu() end it "should be sane (checking Machine for sanity)" do - machine = @om.machine + machine = @binding.machine machine.states.length.should == 2 machine.state_names.should == [:new, :old] machine.events.length.should == 1 @@ -59,17 +59,17 @@ describe StateFu::Binding do describe ".state()" do it "should default to machine.initial_state when no initial_state is explicitly defined" do - @om.respond_to?(:current_state).should == true - @om.current_state.should be_kind_of( StateFu::State ) - @om.current_state.name.should == :new - @om.machine.initial_state.name.should == :new + @binding.respond_to?(:current_state).should == true + @binding.current_state.should be_kind_of( StateFu::State ) + @binding.current_state.name.should == :new + @binding.machine.initial_state.name.should == :new end it "should default to the machine's initial_state if one is set" do Klass.machine() { initial_state :fetus } - Klass.machine.states.first.name.should == :new - Klass.machine.initial_state.name.should == :fetus - Klass.new().om.current_state.name.should == :fetus + Klass.machine.states.first.name.should == :new + Klass.machine.initial_state.name.should == :fetus + Klass.new().binding.current_state.name.should == :fetus end end spec/units/binding_spec.rb @@ -25,7 +25,7 @@ describe StateFu::FuSpace do before(:each) do Klass.machine do end - StateFu::DEFAULT_KOAN.should == :om + StateFu::DEFAULT_MACHINE.should == :om end it "should return { Klass => { ... } } given StateFu::FuSpace.class_machines()" do spec/units/fu_space_spec.rb @@ -47,6 +47,7 @@ **** JSON **** nested hash as basic interchange format? *** avoid procs if possible, or provide alternatives, to keep these options open +*** serialize / deserialize allows easy deep-object copies ** Documentation *** high-level overviews todo.org 017770614aeeb5d2e6e553ec616c7b6039ea6a2f David Lee dml@shifter.(none) http://github.com/davidlee/state-fu/commit/acbd62a6cc0d85da87a72277fa561443d840d935 acbd62a6cc0d85da87a72277fa561443d840d935 2009-03-25T06:53:58-07:00 2009-03-25T06:53:58-07:00 more or less completed the renaming and a little docs, though specs are crying out for love 133879b7d9b8c9275e254c6ee1f0d5c6274a3beb David Lee dml@shifter.(none)