lib/stateful/context.rb spec/stateful/context_spec.rb @@ -1,11 +1,13 @@ = Stateful TODO for 1.0: + - make machine.valid? :from => :to work - complete tracing plugin - ar/dm integration - complete timestamps plugin - turn these notes into real docs - flesh out Machine#to_dot + - clean up, minimally document, and :nodoc: classes == Example @@ -33,11 +35,11 @@ stay :state_or_list end - # events that are available on any state can be wildcarded with :any, + # events that are available on any state can be wildcarded with :ANY, # which is the only reserved state name. Everything else is fair game. on :ping do - move :any => :pinged + move :ANY => :pinged end end end @@ -47,31 +49,32 @@ AClass.statefully do - # you can listen for attempted state entry. Stateful will provide your - # block with the model that's changing state, the destination state, - # and the previous state (if any). + # you can listen for attempted state entry. - # all the block params are optional. your block can take no arguments - # if that sproings your winkie. - - entering :state_or_list do |model, event, to, from| + entering :state_or_list do |ctx| # do some ruby stuff! Exceptions thrown in here will # keep the transition from occuring, i.e., the model's # current state will still be 'from'. + + # the context here gives you all sorts of stuff: + + ctx.model # the target model, + ctx.event # the name of the event that was fired, + ctx.to # the destination state, + ctx.from # the source state, and + ctx.extras # any additional keys you might've passed in! end - # you can also listen for successful state entry. same optional block - # params are available. + # you can also listen for successful state entry. same context is available. - entered :state_or_list do |model, event, to, from| + entered :state_or_list do |ctx| # more ruby stuff! You can throw exceptions in here, of course, # but it won't change the model's current state. end - # listening for attempted state exit is just like state entry, - # but the destination state is provided instead of the source. - - exiting :state_or_list do |model, event, to, from| + # listening for attempted state exit: + + exiting :state_or_list do |ctx| # awesome ruby stuff! throwing exceptions in here vetoes # the transition. end @@ -81,13 +84,13 @@ # it's possible to listen to events fire, too! - firing :event_or_list do |model, event, to, from| + firing :event_or_list do |ctx| # throwing exceptions here will veto the transition end # or after they've successfully fired - fired :event_or_list do |model, event, to, from| + fired :event_or_list do |ctx| # throwing here does squat end end README.rdoc @@ -1,9 +1,11 @@ +# FIXME: only require this crap where it's necessary + require "stateful/version" require "stateful/errors" require "stateful/machine" require "stateful/state" require "stateful/event" - +require "stateful/context" require "stateful/persisters" require "stateful/tracing" lib/stateful.rb @@ -26,7 +26,7 @@ module Stateful #:nodoc: Array(froms).each { |from| @event.transitions[from] = to } # covers 'move from any state to :dest' - @event.transitions.default = to if froms == :any + @event.transitions.default = to if froms == :ANY end def stay(*names) lib/stateful/builders/event.rb @@ -21,23 +21,27 @@ module Stateful end def accessorize(target) - @persister.accessorize(target) + persister.accessorize(target) - @states.keys.each do |name| + states.keys.each do |name| unless target.method_defined?("#{name}?") - target.class_eval <<-RUBY - def #{name}? - self.class.statefully.persister.state_of(self) == #{name.inspect} - end - RUBY + target.send(:define_method, "#{name}?") do + @persister.state_of(self) + end + # target.class_eval <<-RUBY + # def #{name}? + # self.class.statefully.persister.state_of(self) == #{name.inspect} + # end + # RUBY end end - @events.keys.each do |name| + events.keys.each do |name| unless target.method_defined?("#{name}!") + # FIXME: define_method instead? target.class_eval <<-RUBY - def #{name}! - self.class.statefully.execute(self, #{name.inspect}) + def #{name}!(extras={}) + self.class.statefully.execute(self, #{name.inspect}, extras) end RUBY end @@ -46,7 +50,7 @@ module Stateful self end - def execute(model, name) + def execute(model, name, extras={}) raise Stateful::BadModel.new(model) unless model.class.stateful? now = persister.state_of(model) @@ -54,22 +58,22 @@ module Stateful from = states[now] or raise StateNotFound.new(now) dest = event.transitions[now] or raise BadTransition.new(model, event) to = states[dest] or raise StateNotFound.new(dest) - args = model, event.name, to.name, from.name + ctx = Context.new(model, event.name, to.name, from.name, extras) - fire(event, :firing, args) - fire(from, :exiting, args) - fire(to, :entering, args) + fire(event, :firing, ctx) + fire(from, :exiting, ctx) + fire(to, :entering, ctx) # 'internal' event - fire(to, :persisting, args) + fire(to, :persisting, ctx) persister.persist(model, to.name) # 'internal' event - fire(to, :persisted, args) + fire(to, :persisted, ctx) - fire(to, :entered, args) - fire(event, :fired, args) + fire(to, :entered, ctx) + fire(event, :fired, ctx) self end @@ -88,9 +92,9 @@ module Stateful private - def fire(target, event_name, args) - super(event_name, *args) # first fire the global listeners, - target.fire(event_name, *args) # then the ones for a specific state/event + def fire(target, event_name, ctx) + super(event_name, ctx) # first fire the global listeners, + target.fire(event_name, ctx) # then the ones for a specific state/event end end end lib/stateful/machine.rb @@ -87,11 +87,11 @@ describe Stateful::Machine do activate.transitions.size.must == 3 end - it "can specify events available everywhere with :any" do + it "can specify events available everywhere with :ANY" do @machine.apply do on :pause do move :active => :inactive - move :any => :paused + move :ANY => :paused end end @@ -234,15 +234,29 @@ describe Stateful::Machine do global, specific = nil AStatefulClass.statefully do - firing { |*args| global = args } - firing(:activate) { |*args| specific = args } + firing { |ctx| global = ctx } + firing(:activate) { |ctx| specific = ctx } end AStatefulClass.statefully.execute(@instance, :activate) - # model, event, to, from - global.must == [@instance, :activate, :active, :inactive] - specific.must == [@instance, :activate, :active, :inactive] + [global, specific].each do |ctx| + ctx.model.must == @instance + ctx.event.must == :activate + ctx.to.must == :active + ctx.from.must == :inactive + end + end + + it "passes provided extras on to the handlers" do + ctx = nil + + AStatefulClass.statefully do + fired { |x| ctx = x } + end + + AStatefulClass.statefully.execute(@instance, :activate, :key => :value) + ctx.extras[:key].must == :value end end spec/stateful/machine_spec.rb bdaca7d3e97df53ce8d61854e623ea5c5fe8b2cb John Barnette jbarnette@gmail.com http://github.com/jbarnette/stateful/commit/8dd071600b383edbd6ed1790ac9b70460fef891c 8dd071600b383edbd6ed1790ac9b70460fef891c 2008-07-27T19:56:21-07:00 2008-07-27T19:56:21-07:00 Event listeners take a context object now. ee68585b0a3629496bdd3025dc1d44fe59780c78 John Barnette jbarnette@gmail.com