davidlee-state-fu 0.3.1 → 0.10.0

data/README.textile

@@ -4,25 +4,35 @@ h2. What is it?
 
 State-Fu is:
 
- * an unique toolkit for state-oriented programming
+ * a generalized, extensible framework for state-oriented,
+   event-driven programming in Ruby.
 
- * a rich DSL for describing workflows, rules engines and behaviour
+ * a rich DSL for describing workflows, rules engines, behaviours and
+   processes
 
- * something you've probably wanted for a long time but didn't know it
+ * useful both as a Rails plugin, and in standalone ruby programs
+   without any additional dependencies.
 
 It lets you describe:
 
  * series of discrete states
 
- * events which can change the current state
+ * events which allow transitions to occur between states
 
- * rules about when these events can occur
+ * rules (requirements) about when these transitions can occur
 
  * behaviours which occur when they do
 
+Which adds up to a surprisingly useful way to skin a lot of
+problems
+
 Other libraries exist for ruby which do some or all of these
 things. "What's different about State-Fu?", you may ask.
 
+h2. Why StateFu is not your grandmother's state machine
+
+h3. Flippant answer:
+
 Those libraries you've played with are toys. They're made of
 plastic. State-Fu is forged from a reassuringly dense but
 unidentifiable metal which comes only from the rarest of meteorites,
@@ -61,6 +71,13 @@ It is also delightfully elegant and easy to use for simple things:
       event :delete, :from => :ALL, :to => :deleted do
         execute :destroy
       end
+
+      # save all states once transition is complete.
+      # this wants to be last, as it iterates over each state which is
+      # already defined.
+      states do
+        accepted { object.save! }
+      end
     end
   end
 
@@ -80,18 +97,17 @@ It is also delightfully elegant and easy to use for simple things:
 
 </code></pre>
 
-A few of the features which set State-Fu apart for more ambitious work are:
+h3. Feature Comparison and Detailed Answer
 
- * a lovely, simple and flexible API gives you plenty of choices
+A few of the features which set State-Fu apart for more ambitious work are:
 
- * use an ActiveRecord field for state persistence, or just an
-   attribute - or use both, on the same class, for different workflows
+ * a lovely, simple and flexible API gives you plenty of choices about
+   how to describe your problem domain.
 
- * customising the persistence mechanism (eg to use a Rails session,
-   or a text file) is as easy as defining a getter and setter method
-
- * define any number of workflows on the same object / model, or re-use
-   them across multiple classes
+ * define any number of workflows on the same object / model;
+   workflows (Machines) can be entirely separate, or interact with
+   each other. Re-use machines across multiple classes, serialize them
+   to a database, or build them on the fly.
 
  * events can transition from / to any number of states
 
@@ -101,8 +117,8 @@ A few of the features which set State-Fu apart for more ambitious work are:
    state machine itself
 
  * requirements determine at runtime whether a particular state
-   transition can occur, and if not, can tell a user what they must do
-   to satisfy the requirements.
+   transition can occur, and if not, can tell a user (or developer)
+   what they must do to satisfy the requirements.
 
  * requirement failure messages can be generated at runtime, making
    use of whatever application and state-machine context they need
@@ -111,23 +127,51 @@ A few of the features which set State-Fu apart for more ambitious work are:
    determine why, and where from
 
  * in every event hook, requirement filter, and other method calls,
-   you have complete and tidy access to your classes, the state
-   machine, and the transition context. Use real ruby code anywhere,
-   without breathing through a straw!
+   you have complete and consistent access to your classes, its
+   StateFu::Machines, and any Transition context. Use real ruby code
+   anywhere, without breathing through a straw!
+
+ * extend State-Fu (with Lathe#helper) Binding and Transition
+   instances for your Machine to define your a DSL customized for your
+   problem domain, and to keep your class definitions clean. Helper
+   methods have easy access to all the context associated with your
+   object instance, its StateFu::Machines and any Transition in
+   progress.
 
- * extend State-Fu with helper modules, or raw blocks of ruby code, to
-   model your problem domain - globally, per state machine / workflow,
-   or for an individual event transition
+ * extend a State-Fu Lathe (with Lathe#tool) to keep your Machine
+   definitions DRY
 
  * store arbitrary meta-data on any component of State-Fu - a simple
-   but extremely powerful tool for integration
+   but extremely powerful tool for integration with almost anything.
 
  * designed for transparency, introspection and ease of debugging,
    which means a dynamic, powerful system you can actually use without
-   headaches
+   headaches.
+
+ * flexible and helpful logging out of the box - will use the Rails
+   logger if you're in a Rails project, or standalone logging to
+   STDOUT or a file. Configurable loglevel and message prefixes help
+   StateFu be a good citizen in a shared application log.
 
  * magically generate diagrams of state machines / workflows with graphviz
 
+ * "magically" use an ActiveRecord field for state persistence, or just an
+   attribute - or use both, on the same class, for different
+   workflows. If an ActiveRecord field exists for a machine's
+   field_name (by default, the machine's name suffixed with '_field';
+   the default machine name is 'state_fu', so if you don't explicitly
+   name a machine it will look for 'state_fu_field' in your
+   ActiveRecord columns (if ActiveRecord is included) and use
+   that. Otherwise, an attr_accessor will be used (and created, if
+   necessary).
+
+ * customising the persistence mechanism (eg to use a Rails session,
+   or a text file, or your choice of ORM) is usually as easy as
+   defining a getter and setter method for the persistence field, and
+   a rule about when to use it. If you want to use StateFu with a
+   persistence mechanism which is not yet supported, I'd like to hear
+   about it.
+
  * fast, lightweight and useful enough to use in any ruby
    project - works with Rails but does not require it.
 
@@ -146,6 +190,32 @@ I'd also like to tip my hat at John Barnette, who's own
 (coincidentally named) Stateful set a very high standard with an
 exceptionally elegant API.
 
+h3. StateFu is not a complete BPM (Business Process Management) platform
+
+It's worth noting that StateFu is at it's core a state machine, which
+strives to be powerful enough to be able to drive many kinds of
+application behaviour.
+
+It is not, however, a "proper" workflow engine on par with Ruote. In
+StateFu the basic units with which "workflows" are built are states
+and events; Ruote takes a higher level view, dealing with processes
+and participants. As a result, it's capable of directly implementing
+these design patterns:
+
+http://openwferu.rubyforge.org/patterns.html
+
+Whereas StateFu cannot, for example, readily model forking / merging
+of processes (nor does it handles scheduling, process management, etc.
+
+The author of Ruote, the Ruby Workflow Engine, outlines the difference
+pretty clearly here:
+
+http://jmettraux.wordpress.com/2009/07/03/state-machine-workflow-engine/
+
+If your application can be described with StateFu, you'll likely find
+it simpler to get running and work with; if not, you may find Ruote,
+or a combination of the two, suits your needs perfectly.
+
 h2. Getting started
 
 You can either clone the repository in the usual fashion (eg to
@@ -183,22 +253,42 @@ To install the dependencies for running specs:
 
 Now you can simply <code>include StateFu</code> in any class you wish to make stateful.
 
-The spec folder is currently the best source of documentation.
+The spec/ and features/ folders are currently one of the best source
+of documentation. The documentation is gradually evolving to catch up
+with the features, but if you have any questions I'm happy to help you
+get started.
 
-If you have questions, feature request or ideas, please join the "google group":http://groups.google.com/group/state-fu
+If you have questions, feature request or ideas, please join the
+"google group":http://groups.google.com/group/state-fu or send me a
+message on GitHub.
 
-A note about ActiveSupport:
+h3. A note about ActiveSupport
 
 StateFu will use ActiveSupport if it is already loaded. If not, it
-will load its own (very heavily cut down) 'lite' version. This means
-that if you require StateFu *before* other libraries which require
-ActiveSupport (e.g. ActiveRecord), you may have to explicitly
-<code>require 'activesupport'</code> before loading the dependent
-libraries.
+will load its own (heavily trimmed) 'lite' version.
+
+In most projects this will behave transparently, but it does mean that
+if you require StateFu *before* other libraries which
+require ActiveSupport (e.g. ActiveRecord), you may have to
+explicitly <code>require 'activesupport'</code> before loading the
+dependent libraries.
+
+So if you plan to use ActiveSupport in a stand-alone project with
+StateFu, you should require it before StateFu.
+
+h3. Addditional Resources
 
 Also see the "issue tracker":http://github.com/davidlee/state-fu/issues
 
 And the "build monitor":http://runcoderun.com/davidlee/state-fu/
 
-And the "RDoc":http://rdoc.info/projects/davidlee/state-fu/ , which
-needs a bit of love.
+And the "RDoc":http://rdoc.info/projects/davidlee/state-fu
+
+h3. Thanks
+
+ * dsturnbull, for helping w/ a patch to stop an error being raised
+   when an activerecord model has no database table
+
+ * lachie, benkimball for pointing out README bugs / typos
+
+ * Ryan Allen for his original Workflow library

data/Rakefile

@@ -1,16 +1,21 @@
-#!/usr/bin/ruby1.9
+#!/usr/bin/env ruby
 require "spec/rake/spectask"
 #require 'cucumber/rake/task'
 require "date"
 require "fileutils"
 require "rubygems"
 
+load File.join( File.dirname(__FILE__),"/lib/tasks/state_fu.rake" )
+
 module Rakefile
   def self.windows?
     /djgpp|(cyg|ms|bcc)win|mingw/ =~ RUBY_PLATFORM
   end
 end
 
+load 'lib/tasks/spec_last.rake'
+load 'lib/tasks/state_fu.rake'
+
 # to build the gem:
 #
 # gem install jeweller
@@ -38,30 +43,37 @@ rescue LoadError
 end
 
 namespace :spec do
-  desc "Run all specs"
+
+  desc 'run the nice new specs'
+  Spec::Rake::SpecTask.new(:state_fu) do |t|
+    t.spec_files = FileList["spec/state_fu_spec.rb"]
+    t.spec_opts = ["--options", "spec/spec.opts"]
+  end
+
+
+  desc "Run all (old) specs"
   Spec::Rake::SpecTask.new(:all) do |t|
     t.spec_files = FileList["spec/**/*_spec.rb"]
     t.spec_opts = ["--options", "spec/spec.opts"]
   end
 
-  desc "Run unit specs"
-  Spec::Rake::SpecTask.new(:units) do |t|
-    t.spec_files = FileList["spec/units/*_spec.rb"]
-    t.spec_opts = ["--options", "spec/spec.opts"]
+  task :skip_slow do
+    ENV['SKIP_SLOW_SPECS'] = 'true'
   end
-  task :unit => :units
 
-  desc "Run integration specs"
-  Spec::Rake::SpecTask.new(:integration) do |t|
-    t.spec_files = FileList["spec/integration/*_spec.rb"]
-    t.spec_opts = ["--options", "spec/spec.opts"]
+  desc "Run all specs, except especially slow ones"
+  task :quick => [:skip_slow, :all]
+
+  desc "Run all specs with profiling & backtrace" 
+  Spec::Rake::SpecTask.new(:prof) do |t|
+    t.spec_files = FileList["spec/**/*_spec.rb"]
+    t.spec_opts = ['-c','-b','-u','-f','profile','-R','-L','mtime']
   end
-  task :system => :integration
 
   desc "Print Specdoc for all specs (eaxcluding plugin specs)"
   Spec::Rake::SpecTask.new(:doc) do |t|
     t.spec_files = FileList["spec/**/*_spec.rb"]
-    t.spec_opts  = ["--format", "nested","--backtrace","--color"]
+    t.spec_opts  = ["--format", "nested","--color"]
   end
 
   desc "Run autotest"
@@ -69,26 +81,12 @@ namespace :spec do
     exec 'autospec'
   end
 
-    def find_last_modified_spec
-    require 'find'
-    specs = []
-    Find.find( File.expand_path(File.join(File.dirname(__FILE__),'spec'))) do |f|
-      next unless f !~ /\.#/ && f =~ /_spec.rb$/
-      specs << f
-    end
-    spec = specs.sort_by { |spec| File.stat( spec ).mtime }.last
-  end
-
-  desc "runs the last modified spec, without mucking about"
-  Spec::Rake::SpecTask.new(:last) do |t|
-    t.spec_opts = ['--options', "\"#{File.dirname(__FILE__)}/spec/spec.opts\""]
-    t.spec_files = FileList[find_last_modified_spec]
-  end
+  task :default => :state_fu
 end
 
 desc 'Runs irb in this project\'s context'
 task :irb do |t|
-  exec 'irb -I lib -r state-fu'
+  exec 'irb -I lib -I spec -r state-fu -r spec_helper'
 end
 
 desc 'Runs rdoc on the project lib directory'
@@ -96,6 +94,13 @@ task :doc do |t|
   exec 'rdoc lib/'
 end
 
+desc 'Delete logfiles'
+namespace :log do
+  task :clear do |t|
+    Dir['log/*.log'].each { |log| File.rm(log) }
+  end
+end
+
 begin
   require 'cucumber/rake/task'
 
@@ -105,4 +110,5 @@ begin
 rescue LoadError => e
 end
 
-task :default => 'spec:all'
+task :all     => 'spec:all'
+task :default => :all

data/lib/no_stdout.rb

@@ -3,7 +3,7 @@ require 'stringio'
 # a module for suppressing or capturing STDOUT or STDERR.
 # useful when shelling out to "noisy" applications or to suppress
 # output during tests.
-module NoStdout
+module NoStdout  #:nodoc:all
   module InstanceMethods
 
     # Suppresses or redirects STDOUT inside the given block.

data/lib/state-fu.rb

@@ -59,9 +59,12 @@ require 'rubygems'
 
 [ 'core_ext',
   'logger',
-  'helper',
+  'applicable',
+  'arrays',
+  'methodical',
+  'has_options',
+  'executioner',
   'exceptions',
-  'fu_space',
   'machine',
   'lathe',
   'method_factory',
@@ -77,21 +80,19 @@ require 'rubygems'
   'hooks',
   'interface',
   'transition',
-  'mock_transition',
+  'transition_query',
   'plotter' ].each do |lib|
   require File.expand_path( File.join( File.dirname(__FILE__), 'state_fu', lib ))
 end
 
 module StateFu
-  DEFAULT_MACHINE    = :state_fu
+  DEFAULT       = :default
+  DEFAULT_FIELD = :state_fu_field
 
   def self.included( klass )
     klass.extend(         Interface::ClassMethods )
     klass.send( :include, Interface::InstanceMethods )
+    klass.extend(         Interface::Aliases )
   end
 end
 
-if __FILE__ == $0
-  # drop into irb?
-end
-

data/lib/state_fu/active_support_lite/array/access.rb

@@ -1,49 +1,56 @@
-module ActiveSupport #:nodoc:
-  module CoreExtensions #:nodoc:
-    module Array #:nodoc:
+module ActiveSupport #:nodoc:all
+  module CoreExtensions #:nodoc
+    module Array #:nodoc
       # Makes it easier to access parts of an array.
-      module Access
+      module Access #:nodoc:all
         # Returns the tail of the array from +position+.
         #
         #   %w( a b c d ).from(0)  # => %w( a b c d )
         #   %w( a b c d ).from(2)  # => %w( c d )
         #   %w( a b c d ).from(10) # => nil
         #   %w().from(0)           # => nil
+        #:nodoc
         def from(position)
           self[position..-1]
         end
-        
+
         # Returns the beginning of the array up to +position+.
         #
         #   %w( a b c d ).to(0)  # => %w( a )
         #   %w( a b c d ).to(2)  # => %w( a b c )
         #   %w( a b c d ).to(10) # => %w( a b c d )
         #   %w().to(0)           # => %w()
+        #:nodoc
         def to(position)
           self[0..position]
         end
 
         # Equal to <tt>self[1]</tt>.
+        #:nodoc
         def second
           self[1]
         end
 
         # Equal to <tt>self[2]</tt>.
+        #:nodoc
         def third
           self[2]
         end
 
         # Equal to <tt>self[3]</tt>.
+        #:nodoc
         def fourth
           self[3]
         end
 
         # Equal to <tt>self[4]</tt>.
+        #:nodoc
         def fifth
           self[4]
         end
 
         # Equal to <tt>self[41]</tt>. Also known as accessing "the reddit".
+        #:nodoc
         def forty_two
           self[41]
         end

data/lib/state_fu/active_support_lite/array/conversions.rb

@@ -1,11 +1,12 @@
-module ActiveSupport #:nodoc:
-  module CoreExtensions #:nodoc:
-    module Array #:nodoc:
+module ActiveSupport #:nodoc
+  module CoreExtensions #:nodoc
+    module Array #:nodoc
       module Conversions
         # Converts the array to a comma-separated sentence where the last element is joined by the connector word. Options:
         # * <tt>:words_connector</tt> - The sign or word used to join the elements in arrays with two or more elements (default: ", ")
         # * <tt>:two_words_connector</tt> - The sign or word used to join the elements in arrays with two elements (default: " and ")
         # * <tt>:last_word_connector</tt> - The sign or word used to join the last element in arrays with three or more elements (default: ", and ")
+        #:nodoc
         def to_sentence(options = {})
           default_words_connector     = I18n.translate(:'support.array.words_connector',     :locale => options[:locale])
           default_two_words_connector = I18n.translate(:'support.array.two_words_connector', :locale => options[:locale])
@@ -42,6 +43,7 @@ module ActiveSupport #:nodoc:
 
         # Calls <tt>to_param</tt> on all its elements and joins the result with
         # slashes. This is used by <tt>url_for</tt> in Action Pack. 
+        #:nodoc
         def to_param
           collect { |e| e.to_param }.join '/'
         end
@@ -50,12 +52,14 @@ module ActiveSupport #:nodoc:
         # using the given +key+ as the param name.
         #
         #   ['Rails', 'coding'].to_query('hobbies') # => "hobbies%5B%5D=Rails&hobbies%5B%5D=coding"
+        #:nodoc
         def to_query(key)
           prefix = "#{key}[]"
           collect { |value| value.to_query(prefix) }.join '&'
         end
 
-        def self.included(base) #:nodoc:
+        #:nodoc
+        def self.included(base) #:nodoc
           base.class_eval do
             alias_method :to_default_s, :to_s
             alias_method :to_s, :to_formatted_s
@@ -71,6 +75,7 @@ module ActiveSupport #:nodoc:
         # output:
         #
         #   Blog.find(:all).to_formatted_s(:db) # => "First Post,Second Post,Third Post"
+        #:nodoc
         def to_formatted_s(format = :default)
           case format
             when :db
@@ -159,6 +164,7 @@ module ActiveSupport #:nodoc:
         #     </message>
         #   </messages>
         #
+        #:nodoc
         def to_xml(options = {})
           raise "Not all elements respond to to_xml" unless all? { |e| e.respond_to? :to_xml }
           require 'builder' unless defined?(Builder)

data/lib/state_fu/active_support_lite/array/extract_options.rb

@@ -1,7 +1,7 @@
-module ActiveSupport #:nodoc:
-  module CoreExtensions #:nodoc:
-    module Array #:nodoc:
-      module ExtractOptions
+module ActiveSupport #:nodoc
+  module CoreExtensions #:nodoc
+    module Array #:nodoc
+      module ExtractOptions #:nodoc:all    
         # Extracts options from a set of arguments. Removes and returns the last
         # element in the array if it's a hash, otherwise returns a blank hash.
         #
@@ -11,6 +11,7 @@ module ActiveSupport #:nodoc:
         #
         #   options(1, 2)           # => {}
         #   options(1, 2, :a => :b) # => {:a=>:b}
+        #:nodoc
         def extract_options!
           last.is_a?(::Hash) ? pop : {}
         end

data/lib/state_fu/active_support_lite/array/grouping.rb

@@ -1,9 +1,9 @@
 require 'enumerator'
 
-module ActiveSupport #:nodoc:
-  module CoreExtensions #:nodoc:
-    module Array #:nodoc:
-      module Grouping
+module ActiveSupport #:nodoc
+  module CoreExtensions #:nodoc
+    module Array #:nodoc
+      module Grouping #:nodoc:all
         # Splits or iterates over the array in groups of size +number+,
         # padding any remaining slots with +fill_with+ unless it is +false+.
         # 
@@ -19,6 +19,7 @@ module ActiveSupport #:nodoc:
         #   %w(1 2 3).in_groups_of(2, false) {|group| p group}
         #   ["1", "2"]
         #   ["3"]
+        #:nodoc
         def in_groups_of(number, fill_with = nil)
           if fill_with == false
             collection = self
@@ -56,6 +57,7 @@ module ActiveSupport #:nodoc:
         #   ["1", "2", "3"]
         #   ["4", "5"]
         #   ["6", "7"]
+        #:nodoc
         def in_groups(number, fill_with = nil)
           # size / number gives minor group size;
           # size % number gives how many objects need extra accomodation;
@@ -87,6 +89,7 @@ module ActiveSupport #:nodoc:
         #
         #   [1, 2, 3, 4, 5].split(3)                # => [[1, 2], [4, 5]]
         #   (1..10).to_a.split { |i| i % 3 == 0 }   # => [[1, 2], [4, 5], [7, 8], [10]]
+        #:nodoc
         def split(value = nil)
           using_block = block_given?
 

data/lib/state_fu/active_support_lite/array/random_access.rb

@@ -1,8 +1,9 @@
-module ActiveSupport #:nodoc:
-  module CoreExtensions #:nodoc:
-    module Array #:nodoc:
+module ActiveSupport #:nodoc
+  module CoreExtensions #:nodoc
+    module Array #:nodoc
       module RandomAccess
         # Returns a random element from the array.
+        #:nodoc
         def rand
           self[Kernel.rand(length)]
         end

data/lib/state_fu/active_support_lite/array/wrapper.rb

@@ -1,9 +1,10 @@
-module ActiveSupport #:nodoc:
-  module CoreExtensions #:nodoc:
-    module Array #:nodoc:
+module ActiveSupport #:nodoc
+  module CoreExtensions #:nodoc
+    module Array #:nodoc
       module Wrapper
         # Wraps the object in an Array unless it's an Array.  Converts the
         # object to an Array using #to_ary if it implements that.
+        #:nodoc
         def wrap(object)
           case object
           when nil

data/lib/state_fu/active_support_lite/array.rb

@@ -1,7 +1,9 @@
 require File.join( File.dirname( __FILE__),'array/extract_options')
+require File.join( File.dirname( __FILE__),'array/random_access')
 require File.join( File.dirname( __FILE__),'array/grouping')
 
-class Array #:nodoc:
+class Array #:nodoc:all:
   include ActiveSupport::CoreExtensions::Array::ExtractOptions
+  include ActiveSupport::CoreExtensions::Array::RandomAccess
   include ActiveSupport::CoreExtensions::Array::Grouping
 end