state-fu 0.11.1

data/LICENSE

@@ -0,0 +1,40 @@
+# State Fu
+#
+# The original master repository for State-Fu is at github:
+#    http://github.com/davidlee/state-fu
+#
+# Original Author: David Lee (2009)
+#                  http://github.com/davidlee
+#
+# Thanks to:       Ryan Allen    - ryan-allen/workflow
+#                  John Barnette - jbarnett/stateful
+#                  Scott Barron  - rubyist/aasm
+#
+# and other rubyists too numerous to mention, for the inspiration
+#
+# This software is released under this BSD license:
+#
+# Copyright (c) 2009, David Lee. All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+# * Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+# COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+# ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.

data/README.textile

@@ -0,0 +1,293 @@
+h1. StateFu
+
+h2. What is it?
+
+StateFu is another Ruby state machine.
+
+h2. What is a state machine?
+
+Finite state machines are a model for program behaviour; like
+object-oriented programming, they provide an abstract way to think
+about a domain.
+
+In a finite state machine, there are a number of discrete states. Only
+one state may be occupied at any given time (hence the "finite").
+
+States are linked together by events, and there are rules which govern
+when or how transitions between states can occur. Actions may be fired
+on entry to or exit from a state, or when a certain transition occurs.
+
+h2. Why is StateFu different to the other twenty state machines for Ruby?
+
+State machines are potentially a powerful way to simplify and
+structure a lot of problems. They can be used to:
+
+ * succinctly define the grammar of a networking protocol or a
+   configuration DSL
+
+ * clearly and compactly describe complex logic, which might otherwise
+   be difficult to understand by playing "follow the rabbit" through
+   methods thick with implementation details
+
+ * serialize and process multiple revisions of changing business rules
+
+ * provide an abstract representation of program or domain behaviour
+   which can be introspected, edited, queried and executed on the fly,
+   in a high-level and human-readable format
+
+ * provide a straightforward and easy way to record and validate
+   "status" information, especially when there are rules governing
+   when and how it can be updated
+
+ * reduce proliferation of classes and modules, or easily define and
+   control functionally related groups of objects, by defining
+   behaviours on interacting components of a state machine
+
+ * elegantly implement simple building blocks like stacks / queues,
+   parsers, schedulers, automata, etc
+
+StateFu was written from the ground up with one goal in mind: to be
+over-engineered. It is designed to make truly ambitious use of state
+machines not only viable, but strongly advantageous in many situations.
+
+It is designed in the very opposite vein to the intentional minimalism
+of most ruby state machine projects; it is tasked with taking on a
+great deal of complexity and functionality, and abstracting it behind
+a nice DSL, so that the code which *you* have to maintain is shorter and
+clearer.
+
+StateFu allows you to:
+
+ * give a class any number of machines
+
+ * define behaviours on state entry / exit; before, after or during
+   execution of a particular event; or before / after every transition
+   in a given machine
+
+ * give any object own its own private, "singleton" machines,
+   which are unique to that object and modifiable at runtime.
+
+ * create events with any number of origin or target states
+
+ * define and query guard conditions / transition requirements,
+  to establish rules about when a transition is valid
+
+ * use powerful reflection and logging capabilities to easily expose
+   and debug the operation of your machines
+
+ * automatically and unobtrusively define methods for querying each
+   state and event, and for firing transitions
+
+ * easily find out which transitions are valid at any given time
+
+ * generate descriptive, contextual messages when a transition is
+   invalid
+
+ * halt a transition during execution
+
+ * easily extend StateFu's DSL to match the problem domain
+
+ * fire transitions with a payload of arguments and program context,
+   which is available to guard conditions, event hooks, and
+   requirement messages when they are evaluated
+
+ * use a lovely, simple and flexible API which gives you plenty of
+   choices about how to describe your problem domain; choose (or
+   build) a programming style which suits the task at hand from an
+   expressive range of options
+
+ * store arbitrary meta-data on any component of StateFu - a simple
+   but extremely powerful tool for integration with almost anything.
+
+ * 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.
+
+ * automatically generate diagrams of state machines / workflows with graphviz
+
+ * use an ActiveRecord field for state persistence, or a regular
+   attribute - or use both, on the same class, for different
+   machines. If an appropriate ActiveRecord field exists for a
+   machine, it will be used. 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, send me a message.
+
+ * StateFu is fast, lightweight and useful enough to use in any ruby
+   project - works with Rails but does not require it.
+
+h2. Still not sold?
+
+StateFu is forged from a reassuringly dense but unidentifiable metal
+which comes only from the rarest of meteorites, and it ticks when you
+hold it up to your ear.[1]
+
+It is elegant, powerful and transparent enough that you can use
+it to drive substantial parts of your application, and actually want
+to do so.
+
+It is designed as a library for authors, as well as users, of
+libraries: StateFu goes to great lengths to impose very few limits on
+your ability to introspect, manipulate and extend the core features.
+
+It is also delightfully elegant and easy to use for simple things:
+
+<pre><code>
+
+  class Document < ActiveRecord::Base
+    include StateFu
+
+    def update_rss
+      puts "new feed!"
+      # ... do something here
+    end
+
+    machine( :status ) do
+      state :draft do
+        event :publish, :to => :published
+      end
+
+      state :published do
+        on_entry :update_rss
+        requires :author  # a database column
+      end
+
+      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
+
+  my_doc = Document.new
+
+  my_doc.status                          # returns a StateFu::Binding, which lets us access the 'Fu
+  my_doc.status.state     => 'draft'     # if this wasn't already a database column or attribute, an
+                                         # attribute has been created to keep track of the state
+  my_doc.status.name      => :draft      # the name of the current_state (defaults to the first defined)
+  my_doc.status.publish!                 # raised =>  StateFu::RequirementError: [:author]
+                                         # the author requirement prevented the transition
+  my_doc.status.name      => :draft      # see? still a draft.
+  my_doc.author = "Susan"                # so let's satisfy it ...
+  my_doc.publish!                        # and try again.
+  "new feed!"                            # aha - our event hook fires!
+  my_doc.status.name      => :published  # and the state has been updated.
+
+</code></pre>
+
+StateFu works with any modern Ruby ( 1.8.6, 1.8.7, and 1.9.1)
+
+h2. Getting started
+
+You can either clone the repository in the usual fashion (eg to
+yourapp/vendor/plugins/state-fu), or use StateFu as a gem.
+
+To install as a gem:
+
+<pre>
+<code>
+gem install davidlee-state-fu -s http://gems.github.com
+</code>
+</pre>
+
+To require it in your ruby project:
+
+<pre>
+<code>
+require 'rubygems'
+require 'state-fu'
+</code>
+</pre>
+
+To install the dependencies for running specs:
+
+<pre>
+<code>
+ sudo gem install rspec rr
+ rake             # run the specs
+ rake spec:doc    # generate specdocs
+ rake doc         # generate rdocs
+ rake build       # build the gem locally
+ rake install     # install it
+</code>
+</pre>
+
+Now you can simply <code>include StateFu</code> in any class you wish to make stateful.
+
+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 or send me a
+message on GitHub.
+
+h3. A note about ActiveSupport
+
+StateFu will use ActiveSupport if it is already loaded. If not, it
+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
+
+
+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 classical 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.
+
+h3. Thanks
+
+ * dsturnbull, for patches
+
+ * lachie, benkimball for pointing out README bugs / typos
+
+ * Ryan Allen for his original Workflow library

data/Rakefile

@@ -0,0 +1,114 @@
+#!/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
+# rake build
+# rake install
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s| # gemspec (Gem::Specification)
+  s.name              = "state-fu"
+  s.rubyforge_project = "state-fu"
+  s.platform          = Gem::Platform::RUBY
+  s.has_rdoc          = true
+#  s.extra_rdoc_files  = ["README.rdoc"]
+  s.summary           = "A rich library for state-oriented programming with state machines / workflows"
+  s.description       = s.summary
+  s.author            = "David Lee"
+  s.email             = "david@rubyist.net.au"
+  s.homepage          = "http://github.com/davidlee/state-fu"
+  s.require_path      = "lib"
+#  s.files             = %w(README.rdoc Rakefile) + Dir.glob("{lib,spec}/**/*")
+  s.files             = %w(Rakefile) + Dir.glob("{lib,spec}/**/*")
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+namespace :spec do
+
+  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
+
+  task :skip_slow do
+    ENV['SKIP_SLOW_SPECS'] = 'true'
+  end
+
+  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
+
+  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","--color"]
+  end
+
+  desc "Run autotest"
+  task :auto do |t|
+    exec 'autospec'
+  end
+
+  task :default => :state_fu
+end
+
+desc 'Runs irb in this project\'s context'
+task :irb do |t|
+  exec 'irb -I lib -I spec -r state-fu -r spec_helper'
+end
+
+desc 'Runs rdoc on the project lib directory'
+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'
+
+  Cucumber::Rake::Task.new(:features) do |t|
+      t.cucumber_opts = "--format pretty"
+  end
+rescue LoadError => e
+end
+
+task :all     => 'spec:all'
+task :default => :all

data/lib/binding.rb

@@ -0,0 +1,292 @@
+module StateFu
+  class Binding
+
+    attr_reader :object, :machine, :method_name, :field_name, :persister, :transitions, :options, :target
+
+
+    # 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
+      @method_name   = method_name
+      @transitions   = []
+      @options       = options.symbolize_keys!
+      @target        = singleton? ? object : object.class
+      @field_name    = options[:field_name] || @target.state_fu_field_names[method_name]
+      @persister     = Persistence.for( self )
+
+      # define event methods on this binding and its @object
+      MethodFactory.new( self ).install!
+      @machine.helpers.inject_into( self )
+    end
+
+    alias_method :o,             :object
+    alias_method :obj,           :object
+    alias_method :model,         :object
+    alias_method :instance,      :object
+
+    alias_method :workflow,      :machine
+    alias_method :state_machine, :machine
+
+    #
+    # current state
+    #
+
+    # the current State
+    def current_state
+      persister.current_state
+    end
+    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
+      rescue NoMethodError
+        nil
+      end
+    end
+    alias_method :name,       :current_state_name
+    alias_method :state_name, :current_state_name
+    alias_method :to_sym,     :current_state_name
+
+    #
+    # These methods are called from methods defined by MethodFactory.
+    #
+
+    # event_name [target], *args
+    #
+    def find_transition(event, target=nil, *args)
+      target ||= args.last[:to].to_sym rescue nil
+      query = transitions.for_event(event).to(target).with(*args)
+      query.find || query.valid.singular || nil
+    end
+
+    # event_name? [target], *args
+    #
+    def can_transition?(event, target=nil, *args)
+      begin
+        if t = find_transition(event, target, *args)
+          t.valid?(*args)
+        end
+      rescue IllegalTransition, UnknownTarget
+        nil
+      end
+    end
+
+    # event_name! [target], *args
+    #
+    def fire_transition!(event, target=nil, *args)
+      find_transition(event, target, *args).fire!
+    end
+
+    #
+    # events
+    #
+
+    # returns a list of Events which can fire from the current_state
+    def events
+      machine.events.select do |e|
+        e.can_transition_from? current_state
+      end.extend EventArray
+    end
+    alias_method :events_from_current_state,  :events
+
+    # all states which can be reached from the current_state.
+    # Does not check transition requirements, etc.
+    def next_states
+      events.map(&:targets).compact.flatten.uniq.extend StateArray
+    end
+
+    #
+    # transition validation
+    #
+
+    def transitions(opts={}) # .with(*args)
+      TransitionQuery.new(self, opts)
+    end
+
+    def valid_transitions(*args)
+      transitions.valid.with(*args)
+    end
+
+    def valid_next_states(*args)
+      valid_transitions(*args).targets
+    end
+
+    def valid_events(*args)
+      valid_transitions(*args).events
+    end
+
+    def invalid_events(*args)
+      (events - valid_events(*args)).extend StateArray
+    end
+
+
+    # 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 )
+      return transitions.with(*args, &block).find(event_or_array)
+    end
+
+    #
+    # next_transition and friends: when there's exactly one valid move
+    #
+
+    # if there is exactly one legal & valid transition which can be fired with
+    # the given (optional) arguments, return it.
+    def next_transition( *args, &block )
+      transitions.with(*args, &block).next
+    end
+
+    # as above but ignoring any transitions whose origin and target are the same
+    def next_transition_excluding_cycles( *args, &block )
+      transitions.not_cyclic.with(*args, &block).next
+    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, &block)
+      transitions.with(*args, &block).next_state
+    end
+
+    # if there is exactly one event which is valid with the given
+    # optional arguments, return it
+    def next_event( *args )
+      transitions.with(*args, &block).next_event
+    end
+
+    # if there is a next_transition, create, fire & return it
+    # otherwise raise an IllegalTransition
+    def next!( *args, &block )
+      if t = next_transition( *args, &block )
+        t.fire!
+      else
+        raise TransitionNotFound.new( self, valid_transitions(*args), "Exactly 1 valid transition required.")
+      end
+    end
+    alias_method :next_transition!, :next!
+    alias_method :next_event!, :next!
+    alias_method :next_state!, :next!
+
+    # if there is a next_transition, return true / false depending on
+    # whether its requirements are met
+    # otherwise, nil
+    def next?( *args, &block )
+      if t = next_transition( *args, &block )
+        t.requirements_met?
+      end
+    end
+    # alias_method :next_state?, :next?
+    # alias_method :next_event?, :next?
+
+    # Cyclic transitions (origin == target)
+
+    # if there is one possible cyclical event, return a transition there
+    # otherwise, maybe we got an event name as an argument?
+    def cycle(event_or_array=nil, *args, &block)
+      if event_or_array.nil?
+        transitions.cyclic.with(*args, &block).singular ||
+          transitions.cyclic.with(*args, &block).valid.singular
+      else
+        transitions.cyclic.with(*args, &block).find(event_or_array)
+      end
+    end
+
+    # if there is a single possible cycle() transition, fire and return it
+    # otherwise raise an IllegalTransition
+    def cycle!(event_or_array=nil, *args, &block )
+      returning cycle(event_or_array, *args, &block ) do |t|
+        raise TransitionNotFound.new( self, transitions.cyclic.with(*args,&block), "Cannot cycle! unless there is exactly one cyclic event") \
+          if t.nil?
+        t.fire!
+      end
+    end
+
+    # if there is one possible cyclical event, evaluate its
+    # requirements (true/false), else nil
+    def cycle?(event_or_array=nil, *args )
+      if t = cycle(event_or_array, *args )
+        t.requirements_met?
+      end
+    end
+
+    # next! without the raise if there's no next transition
+    # TODO SPECME
+    def update!( *args, &block )
+      if t = next_transition( *args, &block )
+        t.fire!
+      end
+    end
+
+    #
+    # misc
+    #
+
+    # 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
+
+    # display something sensible that doesn't take up the whole screen
+    def inspect
+      '<#' + self.class.to_s + ' ' +
+        attrs = [[:current_state, state_name.inspect],
+                 [:object_type , @object.class],
+                 [:method_name , method_name.inspect],
+                 [:field_name  , field_name.inspect],
+                 [:machine     , machine.to_s]].
+        map {|x| x.join('=') }.join( " " ) + '>'
+    end
+
+    # let's be == (and hence ===) the current_state_name as a symbol.
+    # a nice little convenience.
+    def == other
+      if other.respond_to?( :to_sym ) && current_state
+        current_state_name == other.to_sym || super( other )
+      else
+        super( other )
+      end
+    end
+
+    # TODO better name
+    # is this a binding unique to a specific instance (not bound to a class)?
+    def singleton?
+      options[:singleton]
+    end
+
+    # SPECME DOCME OR KILLME
+    def reload()
+      if persister.is_a?( Persistence::ActiveRecord )
+        object.reload
+      end
+      persister.reload
+      self
+    end
+
+    def inspect
+      s = self.to_s
+      s = s[0,s.length-1]
+      s << " object=#{object}"
+      s << " current_state=#{current_state.to_sym.inspect rescue nil}"
+      s << " events=#{events.map(&:to_sym).inspect rescue nil}"
+      s << " machine=#{machine.to_s}"
+      s << ">"
+      s
+    end
+
+  end
+end