@@ -295,6 +295,9 @@ module StateFu end end + # change the current state of the binding without any + # requirements or other sanity checks, or any hooks firing. + # Useful for test / spec scenarios, and abusing the framework. def teleport!( target ) persister.current_state=( machine.states[target] ) end @@ -310,9 +313,11 @@ module StateFu map {|x| x.join('=') }.join( " " ) + ' =>|' end + # let's be == the current_state_name as a symbol. + # a nice little convenience. def == other - if other.respond_to?(:to_sym) && current_state_name.is_a?(Symbol) - other.to_sym == current_state_name || super( other ) + if other.respond_to?( :to_sym ) && current_state + current_state_name == other.to_sym || super( other ) else super( other ) end lib/state_fu/binding.rb @@ -1,15 +1,16 @@ require 'rubygems' - -class Symbol +# ruby1.9 style symbol comparability for ruby1.8 +class Symbol # :nodoc: unless instance_methods.include?(:'<=>') - # Logger.log .. def <=> other self.to_s <=> other.to_s end end end -unless Object.const_defined?('ActiveSupport') +# if ActiveSupport is absent, install a very small subset of it for +# some convenience methods +unless Object.const_defined?('ActiveSupport') # :nodoc: Dir[File.join(File.dirname( __FILE__), 'active_support_lite','**' )].sort.each do |lib| next unless File.file?( lib ) require lib lib/state_fu/core_ext.rb @@ -3,31 +3,36 @@ module StateFu attr_reader :origins, :targets, :requirements - # - # TODO - event guards - # - + # called by Lathe when a new event is constructed def initialize(machine, name, options={}) @requirements = [].extend ArrayWithSymbolAccessor super( machine, name, options ) end + # the names of all possible origin states def origin_names origins ? origins.map(&:to_sym) : nil end + # the names of all possible target states def target_names targets ? targets.map(&:to_sym) : nil end + # tests if a state or state name is in the list of targets def to?( state ) target_names.include?( state.to_sym ) end + # tests if a state or state name is in the list of origins def from?( state ) 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 @@ -43,34 +48,48 @@ module StateFu 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 ) end + # *adds to* the target states given a list of symbols / States def targets=( *args ) update_state_collection( '@targets', *args ) end - # complete?(:origins) # do we have an origins? - # complete? # do we have an origins and targets? + + # 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 end + # if there is a single state in #origins, returns it def target targets && targets.length == 1 && targets[0] || nil end + # a simple event has exactly one target, and any number of + # origins. It's simple because it can be triggered without + # supplying a target name - ie, <tt>go!<tt> vs <tt>go!(:home)<tt> def simple? !! ( origins && target ) 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 + # targets= are accumulators. def from *args options = args.extract_options!.symbolize_keys! args.flatten! @@ -88,6 +107,7 @@ module StateFu end end + # sets the target states for the event. def to *args options = args.extract_options!.symbolize_keys! args.flatten! @@ -95,12 +115,16 @@ 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 lib/state_fu/event.rb @@ -5,11 +5,12 @@ module StateFu class FuSpace cattr_reader :named_machines, :class_machines, :field_names - # class_machines[ Class ][ method_name ] # => a StateFu::Machine - # class_machines[ Klass ][ nil ] # => the Klass's default Machine - # field_names[ Class ][ method_name ] # => name of attribute / db field - # 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 + # * field_names[ Class ][ method_name ] # => name of attribute / db field + # LAZY_HASH = lambda do |h, k| if k.nil? self[ StateFu::DEFAULT_MACHINE ] lib/state_fu/fu_space.rb @@ -106,10 +106,12 @@ module StateFu # 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 @@ -186,11 +188,14 @@ module StateFu 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 + # pass it as a normal argument. Ruby bug! def limit_arguments( block, *args ) case block.arity when -1, 0 lib/state_fu/helper.rb @@ -1,5 +1,8 @@ module StateFu - module Hooks + + # TODO document structure / sequence of hooks elsewhere + + module Hooks # :nodoc: ALL_HOOKS = [[:event, :before], # good place to start a transaction, etc [:origin, :exit], # say goodbye! lib/state_fu/hooks.rb @@ -1,10 +1,17 @@ module StateFu + # A Lathe parses and a Machine definition and returns a freshly turned + # Machine. + # + # It provides the means to define the arrangement of StateFu objects + # ( eg States and Events) which comprise a workflow, process, + # lifecycle, circuit, syntax, etc. class Lathe # NOTE: Sprocket is the abstract superclass of Event and State attr_reader :machine, :sprocket, :options + # you don't need to call this directly. def initialize( machine, sprocket = nil, options={}, &block ) @machine = machine @sprocket = sprocket lib/state_fu/lathe.rb @@ -42,6 +42,7 @@ module StateFu self.to_sym === other.to_sym end + # display nice and short def inspect s = self.to_s s = s[0,s.length-1] lib/state_fu/state.rb @@ -8,7 +8,9 @@ * Documentation, documentation, documentation: cucumber. * specs -** move specs into bdd folder & use cuke for API / features +** write tool for skeleton rspec unit tests +** RDOC / code comments +** move current specs into bdd folder & use cuke for API / features ** move towards full & consistent rspec unit tests ** rcov (waiting for 1.9) / heckle / et al ** real-world example machines for cucumber features @@ -22,9 +24,6 @@ * Deep copy / duplication / serialization -* event hook for reconstituted[_at] ( eg :new ) - huh? - * next_state & next_state! method should be able to take a hash or proc a filter ** hash filter based on .options ** proc filter replaces block; arbitrary filtering todo.org changelog.org f06a46a6508396fbe7fd238cc2c5e9093186ab89 davidlee david@davelee.com.au http://github.com/davidlee/state-fu/commit/27e8152154cbb4a761576d3f0e889580fd682be0 27e8152154cbb4a761576d3f0e889580fd682be0 2009-06-25T06:23:52-07:00 2009-06-25T06:23:52-07:00 more RDOC love 2adb52d0ddd116e1714a804aa716164e208d35fb davidlee david@davelee.com.au