davidlee-state-fu 0.0.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,174 @@
+h1. State-Fu
+
+h2. What is it?
+
+State-Fu is:
+
+ * an unique toolkit for state-oriented programming
+
+ * a rich DSL for describing workflows, rules engines and behaviour
+
+ * something you've probably wanted for a long time but didn't know it
+
+It lets you describe:
+
+ * series of discrete states
+
+ * events which can change the current state
+
+ * rules about when these events can occur
+
+ * behaviours which occur when they do
+
+Other libraries exist for ruby which do some or all of these
+things. "What's different about State-Fu?", you may ask.
+
+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,
+and it ticks when you hold it up to your ear.[1]
+
+State-Fu 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: State-Fu 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
+    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>
+
+A few of the features which set State-Fu apart for more ambitious work are:
+
+ * a lovely, simple and flexible API gives you plenty of choices
+
+ * use an ActiveRecord field for state persistence, or just an
+   attribute - or use both, on the same class, for different workflows
+
+ * 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
+
+ * events can transition from / to any number of states
+
+ * drive application behaviour with a rich set of event hooks
+
+ * define behaviour as methods on your objects, or keep it all in the
+   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.
+
+ * requirement failure messages can be generated at runtime, making
+   use of whatever application and state-machine context they need
+
+ * transitions can be halted mid-execution, and you can actually
+   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!
+
+ * 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
+
+ * store arbitrary meta-data on any component of State-Fu - a simple
+   but extremely powerful tool for integration
+
+ * designed for transparency, introspection and ease of debugging,
+   which means a dynamic, powerful system you can actually use without
+   headaches
+
+ * fast, lightweight and useful enough to use in any ruby
+   project - works with Rails but does not require it.
+
+State-Fu works with any modern Ruby ( 1.8.6, 1.8.7, and 1.9.1)
+
+fn1. No disrespect intended to the authors of other similar libraries
+- some of whom I've borrowed an idea or two, and some useful criticism,
+from. They're stand-up guys, all of them. It's the truth though.
+
+I'd like to thank Ryan Allen in particular for his Workflow library,
+which I previously forked, piled hundreds of lines of code into and renamed
+Stateful (now deprecated). Some of his ideas (for example the ability to store metadata
+easily on *everything* ) have been instrumental in State-Fu's design.
+
+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.
+
+h2. Getting started
+
+First up:
+
+<pre>
+<code>
+ sudo gem install rspec rr activesupport
+ rake
+ rake spec:doc    # generate specdocs
+ rake doc         # generate rdoc
+ rake gem         # build the gem
+ rake gem:install # install it
+</code>
+</pre>
+And have a peek in the specs folder or rdoc for usage / documentation.
+
+Now you can simply:
+<code>
+ require 'state-fu'
+</code>
+and
+<code>
+ include StateFu
+</code> in any class you wish to make stateful.
+
+If you have questions, feature request or ideas, please join the "google group":http://groups.google.com/group/state-fu
+
+Also see the "issue tracker":http://github.com/davidlee/state-fu/issues

data/Rakefile

@@ -0,0 +1,87 @@
+#!/usr/bin/ruby1.9
+require "spec/rake/spectask"
+#require 'cucumber/rake/task'
+require "date"
+require "fileutils"
+require "rubygems"
+
+module Rakefile
+  def self.windows?
+    /djgpp|(cyg|ms|bcc)win|mingw/ =~ RUBY_PLATFORM
+  end
+end
+
+# 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 both units and integration specs"
+  task :both => [:units, :integration]
+
+  desc "Run all 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"]
+  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"]
+  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"]
+  end
+
+  desc "Run autotest"
+  task :auto do |t|
+    exec 'autospec'
+  end
+
+end
+
+desc 'Runs irb in this project\'s context'
+task :irb do |t|
+  exec 'irb -I lib -r state-fu'
+end
+
+desc 'Runs rdoc on the project lib directory'
+task :doc do |t|
+  exec 'rdoc lib/'
+end
+
+task :default => 'spec:all'

data/lib/no_stdout.rb

@@ -0,0 +1,32 @@
+require 'stringio'
+
+module NoStdout
+  module InstanceMethods
+
+    def no_stdout ( to = StringIO.new('','r+'), &block )
+      # supply an IO of your own to capture STDOUT, otherwise it's put in a StringIO
+      orig_stdout  = $stdout
+      $stdout      = @alt_stdout = to
+      result       = yield
+      $stdout      = orig_stdout
+      result
+    end
+
+    def last_stdout
+      return nil unless @alt_stdout
+      @alt_stdout.rewind
+      @alt_stdout.read
+    end
+
+  end
+
+  # TODO - explain / remember why this has two class_eval blocks -
+  # should one be an extend?
+  def self.included klass
+    klass.class_eval do
+      include InstanceMethods
+    end
+    klass.extend InstanceMethods
+  end
+
+end

data/lib/state-fu.rb

@@ -0,0 +1,93 @@
+
+#!/usr/bin/env ruby
+#
+# State-Fu
+#
+# State-Fu is a framework for state-oriented programming in ruby.
+#
+# You can use it to define state machines, workflows, rules engines,
+# and the behaviours which relate to states and transitions between
+# them.
+#
+# It is powerful and flexible enough to drive entire applications, or
+# substantial parts of them. It is designed as a library for authors,
+# as well as users, of libraries: State-Fu 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:
+#
+#   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
+#     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.
+
+require 'activesupport'
+
+require 'state_fu/core_ext'
+require 'state_fu/logger'
+require 'state_fu/helper'
+require 'state_fu/exceptions'
+require 'state_fu/fu_space'
+require 'state_fu/machine'
+require 'state_fu/lathe'
+require 'state_fu/method_factory'
+require 'state_fu/binding'
+require 'state_fu/persistence'
+require 'state_fu/persistence/base'
+require 'state_fu/persistence/active_record'
+require 'state_fu/persistence/attribute'
+require 'state_fu/sprocket'
+require 'state_fu/state'
+require 'state_fu/event'
+require 'state_fu/hooks'
+require 'state_fu/interface'
+require 'state_fu/transition'
+
+module StateFu
+  DEFAULT_MACHINE    = :state_fu
+
+  def self.included( klass )
+    klass.extend(         Interface::ClassMethods )
+    klass.send( :include, Interface::InstanceMethods )
+  end
+end
+
+if __FILE__ == $0
+  # run rake stuff (specs / doc )
+  # load example_machine.rb
+  # drop into irb
+end

data/lib/state_fu/binding.rb

@@ -0,0 +1,262 @@
+module StateFu
+  class Binding
+    include ContextualEval
+
+    attr_reader :object, :machine, :method_name, :persister, :transitions, :options
+
+    def initialize( machine, object, method_name, options={} )
+      @machine       = machine
+      @object        = object
+      @method_name   = method_name
+      @transitions   = []
+      @options       = options.symbolize_keys!
+      field_name     = StateFu::FuSpace.field_names[object.class][@method_name]
+      raise( ArgumentError, "No field_name" ) unless field_name
+      # ensure state field is set up (in case we created this binding
+      # manually, instead of via Machine.bind!)
+      StateFu::Persistence.prepare_field( object.class, field_name )
+      # add a persister
+      @persister     = StateFu::Persistence.for( self, field_name )
+      Logger.info( "Persister added: #@persister ")
+
+      # define event methods on self( binding ) and @object
+      StateFu::MethodFactory.new( self ).install!
+
+      # StateFu::Persistence.prepare_field( @object.class, field_name )
+    end
+    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
+    end
+
+    def current_state
+      persister.current_state
+    end
+    alias_method :at,    :current_state
+    alias_method :now,   :current_state
+    alias_method :state, :current_state
+
+    def current_state_name
+      current_state.name
+    end
+    alias_method :name,       :current_state_name
+    alias_method :state_name, :current_state_name
+    alias_method :to_sym,     :current_state_name
+
+    # a list of events which can fire from the current_state
+    def events
+      machine.events.select {|e| e.complete? && e.from?( current_state ) }.extend EventArray
+    end
+    alias_method :events_from_current_state,  :events
+
+    # the subset of events() whose requirements for firing are met
+    def valid_events
+      return nil unless current_state
+      return [] unless current_state.exitable_by?( self )
+      events.select {|e| e.fireable_by?( self ) }.extend EventArray
+    end
+
+    def invalid_events
+      (events - valid_events).extend StateArray
+    end
+
+    def unmet_requirements_for(event, target)
+      raise NotImplementedError
+    end
+
+    # the counterpart to valid_events - the states we can arrive at in
+    # the firing of one event, taking into account event and state
+    # transition requirements
+    def valid_next_states
+      valid_transitions.values.flatten.uniq.extend StateArray
+    end
+
+    def next_states
+      events.map(&:targets).compact.flatten.uniq.extend StateArray
+    end
+
+    def invalid_next_states
+      states - valid_states
+    end
+
+    # returns a hash of { event => [states] } whose transition
+    # requirements are met
+    def valid_transitions
+      h = {}
+      return nil if valid_events.nil?
+      valid_events.each do |e|
+        h[e] = e.targets.select do |s|
+          s.enterable_by?( self )
+        end
+      end
+      h
+    end
+
+    # initialize a new transition
+    def transition( event_or_array, *args, &block )
+      event, target = parse_destination( event_or_array )
+      StateFu::Transition.new( self, event, target, *args, &block )
+    end
+    alias_method :fire,    :transition
+    alias_method :trigger, :transition
+
+    # sanitize args for fire! and fireable?
+    def parse_destination( event_or_array )
+      case event_or_array
+      when StateFu::Event, Symbol
+        event  = event_or_array
+        target = nil
+      when Array
+        event, target = *event_or_array
+      end
+      x = event_or_array.is_a?( Array ) ? event_or_array.map(&:class) : event_or_array
+      raise ArgumentError.new( x.inspect ) unless
+        [StateFu::Event, Symbol  ].include?( event.class  ) &&
+        [StateFu::State, Symbol, NilClass].include?( target.class )
+      [event, target]
+    end
+
+    # check that the event and target are "valid" (all requirements met)
+    def fireable?( event_or_array )
+      event, target = parse_destination( event_or_array )
+      begin
+        t = transition( [event, target] )
+        !! t.requirements_met?
+      rescue InvalidTransition => e
+        nil
+      end
+    end
+    alias_method :event?,         :fireable?
+    alias_method :trigger?,       :fireable?
+    alias_method :triggerable?,   :fireable?
+    alias_method :transition?,    :fireable?
+    alias_method :transitionable?,:fireable?
+
+    # construct an event transition and fire it
+    def fire!( event_or_array, *args, &block)
+      event, target = parse_destination( event_or_array )
+      t = transition( [event, target], *args, &block )
+      t.fire!
+      t
+    end
+    alias_method :event!,    :fire!
+    alias_method :trigger!,    :fire!
+    alias_method :transition!, :fire!
+
+    # evaluate a requirement depending whether it's a method or proc,
+    # and its arity - see helper.rb (ContextualEval) for the smarts
+    def evaluate_requirement( name )
+      evaluate_named_proc_or_method( name )
+    end
+
+    def evaluate_requirement_message( name, dest )
+      msg = machine.requirement_messages[name]
+      if [String, NilClass].include?( msg.class )
+        return msg
+      else
+        if dest.is_a?( StateFu::Transition )
+          t = dest
+        else
+          event, target = parse_destination( event_or_array )
+          t = transition( event, target )
+        end
+        case msg
+        when Symbol
+          t.evaluate_named_proc_or_method( msg )
+        when Proc
+          t.evaluate &msg
+        end
+      end
+    end
+
+    # if there is one simple event, return a transition for it
+    # else return nil
+    # TODO - not convinced about the method name / aliases - but next
+    # is reserved :/
+    def next_transition( *args, &block )
+      return nil if valid_transitions.nil?
+      next_transition_candidates = valid_transitions.select {|e, s| s.length == 1 }
+      if next_transition_candidates.length == 1
+        nt   = next_transition_candidates.first
+        evt  = nt[0]
+        targ = nt[1][0]
+        return transition( [ evt, targ], *args, &block )
+      end
+    end
+
+    def next_state
+      next_transition && next_transition.target
+    end
+
+    alias_method :next_event, :next_transition
+
+    # if there is a next_transition, create, fire & return it
+    # otherwise raise an InvalidTransition
+    def next!( *args, &block )
+      if t = next_transition( *args, &block )
+        t.fire!
+        t
+      else
+        n = valid_transitions && valid_transitions.length
+        raise InvalidTransition.
+          new( self, current_state, valid_transitions,
+               "there are #{n} candidate transitions, need exactly 1")
+      end
+    end
+    alias_method :next_state!, :next!
+    alias_method :next_event!, :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?
+
+    # if there is one possible cyclical event, return a transition there
+    def cycle( *args, &block)
+      cycle_events = events.select {|e| e.target == current_state }
+      if cycle_events.length == 1
+        transition( cycle_events[0], *args, &block )
+      end
+    end
+
+    # if there is a cycle() transition, fire and return it
+    # otherwise raise an InvalidTransition
+    def cycle!( *args, &block )
+      if t = cycle( *args, &block )
+        t.fire!
+        t
+      else
+        err_msg = "Cannot cycle! unless there is exactly one event leading from the current state to itself"
+        raise InvalidTransition.new( self, current_state, current_state, err_msg )
+      end
+    end
+
+    # if there is one possible cyclical event, evaluate its
+    # requirements (true/false), else nil
+    def cycle?
+      if t = cycle
+        t.requirements_met?
+      end
+    end
+
+    # display something sensible that doesn't take up the whole screen
+    def inspect
+      "#<#{self.class} ##{__id__} object_type=#{@object.class} method_name=#{method_name.inspect} field_name=#{persister.field_name.inspect} machine=#{@machine.inspect} options=#{options.inspect}>"
+    end
+
+  end
+end