apollo 1.0.0

data/Rakefile

@@ -0,0 +1,48 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "apollo"
+    gem.summary = %Q{A fork of workflow: a finite-state-machine-inspired API for modeling and interacting with what we tend to refer to as 'workflow'.}
+    gem.email = "warlickt@operissystems.com"
+    gem.homepage = "http://github.com/tekwiz/apollo"
+    gem.authors = ["Travis D. Warlick, Jr."]
+    # gem.add_development_dependency "rspec", "~> 1.3.0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+# TODO rspecs
+# require 'spec/rake/spectask'
+# Spec::Rake::SpecTask.new(:spec) do |spec|
+#   spec.libs << 'lib' << 'spec'
+#   spec.spec_files = FileList['spec/**/*_spec.rb']
+# end
+# 
+# Spec::Rake::SpecTask.new(:rcov) do |spec|
+#   spec.libs << 'lib' << 'spec'
+#   spec.pattern = 'spec/**/*_spec.rb'
+#   spec.rcov = true
+#   spec.rcov_opts << '--exclude \/Library\/' << '--exclude /\.gem\/'
+# end
+
+# task :spec => :check_dependencies
+# 
+# task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "Apollo #{version}"
+  rdoc.rdoc_files.include('README*', 'MIT-LICENSE', 'LICENSE', 'VERSION')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+task :clobber => [:clobber_rcov, :clobber_rdoc]

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/apollo.gemspec

@@ -0,0 +1,60 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{apollo}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Travis D. Warlick, Jr."]
+  s.date = %q{2010-04-23}
+  s.email = %q{warlickt@operissystems.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.markdown"
+  ]
+  s.files = [
+    ".gitignore",
+     "LICENSE",
+     "MIT-LICENSE",
+     "README.markdown",
+     "Rakefile",
+     "VERSION",
+     "apollo.gemspec",
+     "lib/apollo.rb",
+     "lib/apollo/active_record_instance_methods.rb",
+     "lib/apollo/event.rb",
+     "lib/apollo/specification.rb",
+     "lib/apollo/state.rb",
+     "test/couchtiny_example.rb",
+     "test/main_test.rb",
+     "test/readme_example.rb",
+     "test/test_helper.rb",
+     "test/without_active_record_test.rb"
+  ]
+  s.homepage = %q{http://github.com/tekwiz/apollo}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{A fork of workflow: a finite-state-machine-inspired API for modeling and interacting with what we tend to refer to as 'workflow'.}
+  s.test_files = [
+    "test/couchtiny_example.rb",
+     "test/main_test.rb",
+     "test/readme_example.rb",
+     "test/test_helper.rb",
+     "test/without_active_record_test.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end
+

data/lib/apollo.rb

@@ -0,0 +1,263 @@
+module Apollo
+  autoload :Event,                        'apollo/event'
+  autoload :State,                        'apollo/state'
+  autoload :Specification,                'apollo/specification'
+  autoload :ActiveRecordInstanceMethods,  'apollo/active_record_instance_methods'
+  
+  # The current version
+  VERSION = File.read(File.join(File.expand_path(File.dirname(__FILE__)), '..', 'VERSION')).strip
+  
+  class TransitionHalted < Exception
+    attr_reader :halted_because
+
+    def initialize(msg = nil)
+      @halted_because = msg
+      super msg
+    end
+  end
+
+  class NoTransitionAllowed < Exception; end
+
+  class ApolloError < Exception; end
+
+  class ApolloDefinitionError < Exception; end
+  
+  module ClassMethods
+    attr_reader :apollo_spec
+    
+    def apollo_column(column_name=nil)
+      if column_name
+        @apollo_state_column_name = column_name.to_sym
+      else
+        @apollo_state_column_name ||= :current_state
+      end
+      @apollo_state_column_name
+    end
+
+    def apollo(&specification)
+      @apollo_spec = Specification.new(Hash.new, &specification)
+      @apollo_spec.states.values.each do |state|
+        state_name = state.name
+        module_eval do
+          define_method "#{state_name}?" do
+            state_name == current_state.name
+          end
+        end
+
+        state.events.values.each do |event|
+          event_name = event.name
+          module_eval do
+            define_method "#{event_name}!".to_sym do |*args|
+              process_event!(event_name, *args)
+            end
+          end
+        end
+      end
+    end
+  end
+
+  module InstanceMethods
+    def current_state
+      loaded_state = load_apollo_state
+      res = spec.states[loaded_state.to_sym] if loaded_state
+      res || spec.initial_state
+    end
+
+    def halted?
+      @halted
+    end
+
+    def halted_because
+      @halted_because
+    end
+
+    def process_event!(name, *args)
+      event = current_state.events[name.to_sym]
+      raise NoTransitionAllowed.new(
+        "There is no event #{name.to_sym} defined for the #{current_state} state") \
+        if event.nil?
+      # This three member variables are a relict from the old apollo library
+      # TODO: refactor some day
+      @halted_because = nil
+      @halted = false
+      @raise_exception_on_halt = false
+      return_value = run_action(event.action, *args) || run_action_callback(event.name, *args)
+      if @halted
+        if @raise_exception_on_halt
+          raise @raise_exception_on_halt
+        else
+          false
+        end
+      else
+        check_transition(event)
+        run_on_transition(current_state, spec.states[event.to], name, *args)
+        transition(current_state, spec.states[event.to], name, *args)
+        return_value
+      end
+    end
+
+    private
+
+    def check_transition(event)
+      # Create a meaningful error message instead of
+      # "undefined method `on_entry' for nil:NilClass"
+      # Reported by Kyle Burton
+      if !spec.states[event.to]
+        raise ApolloError.new("Event[#{event.name}]'s " +
+            "to[#{event.to}] is not a declared state.")
+      end
+    end
+
+    def spec
+      c = self.class
+      # using a simple loop instead of class_inheritable_accessor to avoid
+      # dependency on Rails' ActiveSupport
+      until c.apollo_spec || !(c.include? Apollo)
+        c = c.superclass
+      end
+      c.apollo_spec
+    end
+
+    def halt(reason)
+      @halted_because = reason
+      @halted = true
+      @raise_exception_on_halt = false
+    end
+
+    def halt!(reason, exception_klass = TransitionHalted)
+      @halted_because = reason
+      @halted = true
+      if exception_klass.class == Class
+        @raise_exception_on_halt = exception_klass.new(reason)
+      else
+        @raise_exception_on_halt = exception_klass
+      end
+      @raise_exception_on_halt.set_backtrace(caller)
+    end
+
+    def transition(from, to, name, *args)
+      run_on_exit(from, to, name, *args)
+      persist_apollo_state to.to_s
+      run_on_entry(to, from, name, *args)
+    end
+
+    def run_on_transition(from, to, event, *args)
+      instance_exec(from.name, to.name, event, *args, &spec.on_transition_proc) if spec.on_transition_proc
+    end
+
+    def run_action(action, *args)
+      instance_exec(*args, &action) if action
+    end
+
+    def run_action_callback(action_name, *args)
+      self.send action_name.to_sym, *args if self.respond_to?(action_name.to_sym)
+    end
+
+    def run_on_entry(state, prior_state, triggering_event, *args)
+      if state.on_entry
+        instance_exec(prior_state.name, triggering_event, *args, &state.on_entry)
+      else
+        hook_name = "on_#{state}_entry"
+        self.send hook_name, prior_state, triggering_event, *args if self.respond_to? hook_name
+      end
+    end
+
+    def run_on_exit(state, new_state, triggering_event, *args)
+      if state
+        if state.on_exit
+          instance_exec(new_state.name, triggering_event, *args, &state.on_exit)
+        else
+          hook_name = "on_#{state}_exit"
+          self.send hook_name, new_state, triggering_event, *args if self.respond_to? hook_name
+        end
+      end
+    end
+
+    # load_apollo_state and persist_apollo_state
+    # can be overriden to handle the persistence of the apollo state.
+    #
+    # Default (non ActiveRecord) implementation stores the current state
+    # in a variable.
+    #
+    # Default ActiveRecord implementation uses a 'apollo_state' database column.
+    def load_apollo_state
+      @apollo_state if instance_variable_defined? :@apollo_state
+    end
+
+    def persist_apollo_state(new_value)
+      @apollo_state = new_value
+    end
+  end
+
+  def self.included(klass)
+    klass.send :include, InstanceMethods
+    klass.extend ClassMethods
+    if Object.const_defined?(:ActiveRecord)
+      if klass < ActiveRecord::Base
+      klass.send :include, ActiveRecordInstanceMethods
+      klass.before_validation :write_initial_state
+      end
+    end
+  end
+
+  # Generates a `dot` graph of the apollo.
+  # Prerequisite: the `dot` binary.
+  # You can use it in your own Rakefile like this:
+  #
+  #     namespace :doc do
+  #       desc "Generate a graph of the apollo."
+  #       task :apollo do
+  #         Apollo::create_apollo_diagram(Order.new)
+  #       end
+  #     end
+  #
+  # You can influence the placement of nodes by specifying
+  # additional meta information in your states and transition descriptions.
+  # You can assign higher `doc_weight` value to the typical transitions
+  # in your apollo. All other states and transitions will be arranged
+  # around that main line. See also `weight` in the graphviz documentation.
+  # Example:
+  #
+  #     state :new do
+  #       event :approve, :to => :approved, :meta => {:doc_weight => 8}
+  #     end
+  #
+  #
+  # @param klass A class with the Apollo mixin, for which you wish the graphical apollo representation
+  # @param [String] target_dir Directory, where to save the dot and the pdf files
+  # @param [String] graph_options You can change graph orientation, size etc. See graphviz documentation
+  def self.create_apollo_diagram(klass, target_dir, graph_options='rankdir="LR", size="7,11.6", ratio="fill"')
+    apollo_name = "#{klass.name.tableize}_apollo"
+    fname = File.join(target_dir, "generated_#{apollo_name}")
+    File.open("#{fname}.dot", 'w') do |file|
+      file.puts %Q|
+digraph #{apollo_name} {
+  graph [#{graph_options}];
+  node [shape=box];
+  edge [len=1];
+      |
+
+      klass.apollo_spec.states.each do |state_name, state|
+        file.puts %Q{  #{state.name} [label="#{state.name}"];}
+        state.events.each do |event_name, event|
+          meta_info = event.meta
+          if meta_info[:doc_weight]
+            weight_prop = ", weight=#{meta_info[:doc_weight]}"
+          else
+            weight_prop = ''
+          end
+          file.puts %Q{  #{state.name} -> #{event.to} [label="#{event_name.to_s.humanize}" #{weight_prop}];}
+        end
+      end
+      file.puts "}"
+      file.puts
+    end
+    `dot -Tpdf -o#{fname}.pdf #{fname}.dot`
+    puts "
+Please run the following to open the generated file:
+
+open #{fname}.pdf
+
+"
+  end
+end

data/lib/apollo/active_record_instance_methods.rb

@@ -0,0 +1,24 @@
+module Apollo
+  module ActiveRecordInstanceMethods
+    def load_apollo_state
+      read_attribute(self.class.apollo_column)
+    end
+
+    # On transition the new apollo state is immediately saved in the
+    # database.
+    def persist_apollo_state(new_value)
+      update_attribute self.class.apollo_column, new_value
+    end
+
+    private
+
+    # Motivation: even if NULL is stored in the apollo_state database column,
+    # the current_state is correctly recognized in the Ruby code. The problem
+    # arises when you want to SELECT records filtering by the value of initial
+    # state. That's why it is important to save the string with the name of the
+    # initial state in all the new records.
+    def write_initial_state
+      write_attribute self.class.apollo_column, current_state.to_s
+    end
+  end
+end

data/lib/apollo/event.rb

@@ -0,0 +1,9 @@
+module Apollo
+  class Event
+    attr_accessor :name, :to, :meta, :action
+
+    def initialize(name, to, meta = {}, &action)
+      @name, @to, @meta, @action = name, to.to_sym, meta, action
+    end
+  end
+end

data/lib/apollo/specification.rb

@@ -0,0 +1,43 @@
+module Apollo
+  class Specification
+    attr_accessor :states, :initial_state, :meta, :on_transition_proc
+
+    def initialize(meta = {}, &specification)
+      @states = Hash.new
+      @meta = meta
+      instance_eval(&specification)
+    end
+
+    private
+
+    def state(name, meta = {:meta => {}}, &events_and_etc)
+      # meta[:meta] to keep the API consistent..., gah
+      new_state = State.new(name, meta[:meta])
+      @initial_state = new_state if @states.empty?
+      @states[name.to_sym] = new_state
+      @scoped_state = new_state
+      instance_eval(&events_and_etc) if events_and_etc
+    end
+
+    def event(name, args = {}, &action)
+      target = args[:to] || args[:to]
+      raise ApolloDefinitionError.new(
+        "missing ':to' in apollo event definition for '#{name}'") \
+        if target.nil?
+      @scoped_state.events[name.to_sym] =
+        Event.new(name, target, (args[:meta] or {}), &action)
+    end
+
+    def on_entry(&proc)
+      @scoped_state.on_entry = proc
+    end
+
+    def on_exit(&proc)
+      @scoped_state.on_exit = proc
+    end
+
+    def on_transition(&proc)
+      @on_transition_proc = proc
+    end
+  end
+end