validating-workflow 0.7.2 → 0.7.6

data/.gitignore

@@ -4,4 +4,5 @@ pkg
 doc/
 html/
 *.swp
+*.gemspec
 .yardoc

data/README.markdown

@@ -1,7 +1,7 @@
-What is workflow?
------------------
+What is validating-workflow?
+----------------------------
 
-Workflow is a finite-state-machine-inspired API for modeling and
+Validating-Workflow is a finite-state-machine-inspired API for modeling and
 interacting with what we tend to refer to as 'workflow'.
 
 A lot of business modeling tends to involve workflow-like concepts, and
@@ -20,6 +20,10 @@ from, and we can cause transitions to fail (guards), and we can hook in
 to every transition that occurs ever for whatever reason we can come up
 with.
 
+For convenience, validating-workflow adds certain validation options for
+ActiveModel so you may declaratively specify what to validate in which
+states or transitions when defining your validators.
+
 Now, all that's a mouthful, but we'll demonstrate the API bit by bit
 with a real-ish world example.
 

data/Rakefile

@@ -19,12 +19,12 @@ end
 begin
   require 'jeweler'
   Jeweler::Tasks.new do |gemspec|
-    gemspec.name = "workflow"
+    gemspec.name = 'workflow'
     gemspec.rubyforge_project = 'workflow'
-    gemspec.email = "vladimir@geekq.net"
-    gemspec.homepage = "http://www.geekq.net/workflow/"
-    gemspec.authors = ["Vladimir Dobriakov"]
-    gemspec.summary = "A replacement for acts_as_state_machine."
+    gemspec.email = 'vladimir@geekq.net'
+    gemspec.homepage = 'http://www.geekq.net/workflow/'
+    gemspec.authors = ['Vladimir Dobriakov', 'Willem van Kerkhof']
+    gemspec.summary = 'A replacement for acts_as_state_machine.'
     gemspec.description = <<-EOS
     Workflow is a finite-state-machine-inspired API for modeling and interacting
     with what we tend to refer to as 'workflow'.

data/VERSION

@@ -1 +1 @@
-0.7.0
+0.7.6

data/lib/workflow/state_dependent_validations.rb

@@ -1,3 +1,5 @@
+require 'active_model/validations'
+
 module Workflow
   module StateDependentValidations
     module StateDependency
@@ -7,18 +9,30 @@ module Workflow
       end
 
       def validate_with_state_dependency(record)
-        if not record.respond_to?(:current_state) or perform_validation_for_state?(record.current_state)
+        if not record.respond_to?(:current_state) or
+            perform_validation_for_state?(record.current_state) or
+            perform_validation_for_transition?(record.in_transition) or
+            perform_validation_for_transition?("#{record.in_exit}_exit") or
+            perform_validation_for_transition?("#{record.in_entry}_entry")
           validate_without_state_dependency(record)
         end
       end
 
       protected
       def perform_validation_for_state?(state)
-        (unless_in_state_option.empty? and if_in_state_option.empty?) or
+        (unless_in_state_option.empty? and if_in_state_option.empty? and
+          unless_in_transition_option.empty? and if_in_transition_option.empty?) or
             (if_in_state_option.any? and if_in_state_option.include?(state.to_s)) or
             (unless_in_state_option.any? and not unless_in_state_option.include?(state.to_s))
       end
 
+      def perform_validation_for_transition?(transition)
+        (unless_in_state_option.empty? and if_in_state_option.empty? and
+          unless_in_transition_option.empty? and if_in_transition_option.empty?) or
+            (if_in_transition_option.any? and if_in_transition_option.include?(transition.to_s)) or
+            (unless_in_transition_option.any? and not unless_in_transition_option.include?(transition.to_s))
+      end
+
       def if_in_state_option
         @if_in_state_option ||= [options[:if_in_state]].flatten.compact.collect(&:to_s)
       end
@@ -26,19 +40,23 @@ module Workflow
       def unless_in_state_option
         @unless_in_state_option ||= [options[:unless_in_state]].flatten.compact.collect(&:to_s)
       end
+
+      def if_in_transition_option
+        @if_in_transition_option ||= [options[:if_in_transition]].flatten.compact.collect(&:to_s)
+      end
+
+      def unless_in_transition_option
+        @unless_in_transition_option ||= [options[:unless_in_transition]].flatten.compact.collect(&:to_s)
+      end
     end
 
   end
 end
 
-# unless defined? ActiveModel::Validations
-  module ActiveModel::Validations
-    [AcceptanceValidator, ConfirmationValidator, ExclusionValidator,
-    FormatValidator, InclusionValidator, LengthValidator,
-    NumericalityValidator, PresenceValidator].each do |validator|
-      validator.send :include, Workflow::StateDependentValidations::StateDependency
-    end
+module ActiveModel::Validations
+  [AcceptanceValidator, ConfirmationValidator, ExclusionValidator,
+  FormatValidator, InclusionValidator, LengthValidator,
+  NumericalityValidator, PresenceValidator].each do |validator|
+    validator.send :include, Workflow::StateDependentValidations::StateDependency
   end
-# else
-#   raise 'state dependent validation only works with ActiveModel::Validations'
-# end
+end

data/lib/workflow.rb

@@ -2,10 +2,14 @@ require 'rubygems'
 
 # See also README.markdown for documentation
 module Workflow
+  autoload :ActiveModelPersistence, 'workflow/active_model_persistence'
+  autoload :MongoidPersistence,     'workflow/mongoid_persistence'
+  autoload :RemodelPersistence,     'workflow/remodel_persistence'
+  autoload :Transactional,          'workflow/transactional'
 
   class Specification
 
-    attr_accessor :states, :initial_state, :meta, :on_transition_proc
+    attr_accessor :states, :initial_state, :meta, :on_transition_proc, :on_failed_transition_proc
 
     def initialize(meta = {}, &specification)
       @states = Hash.new
@@ -22,31 +26,41 @@ module Workflow
     def state(name, meta = {:meta => {}}, &events_and_etc)
       # meta[:meta] to keep the API consistent..., gah
       new_state = Workflow::State.new(name, meta[:meta])
-      @initial_state = new_state if @states.empty?
+      @initial_state       = new_state if @states.empty?
       @states[name.to_sym] = new_state
-      @scoped_state = new_state
+      @scoped_state        = new_state
       instance_eval(&events_and_etc) if events_and_etc
     end
 
     def event(name, args = {}, &action)
       target = args[:transitions_to] || args[:transition_to]
-      raise WorkflowDefinitionError.new(
-        "missing ':transitions_to' in workflow event definition for '#{name}'") \
-        if target.nil?
+      if target.nil?
+        raise WorkflowDefinitionError.new \
+          "missing ':transitions_to' in workflow event definition for '#{name}'"
+      end
       @scoped_state.events[name.to_sym] =
-        Workflow::Event.new(name, target, (args[:meta] or {}), &action)
+        Workflow::Event.new(name, target, (args[:meta] || {}), &action)
+    end
+
+    def allow(name, args={}, &action)
+      args[:transitions_to] ||= args[:transition_to] || @scoped_state.to_sym
+      event name, args, &action
     end
 
-    def on_entry(&proc)
-      @scoped_state.on_entry = proc
+    def on_entry(&proc_to_run)
+      @scoped_state.on_entry = proc_to_run
     end
 
-    def on_exit(&proc)
-      @scoped_state.on_exit = proc
+    def on_exit(&proc_to_run)
+      @scoped_state.on_exit = proc_to_run
     end
 
-    def on_transition(&proc)
-      @on_transition_proc = proc
+    def on_transition(&proc_to_run)
+      @on_transition_proc = proc_to_run
+    end
+
+    def on_failed_transition(&proc_to_run)
+      @on_failed_transition_proc = proc_to_run
     end
   end
 
@@ -92,6 +106,18 @@ module Workflow
       @name, @transitions_to, @meta, @action = name, transitions_to.to_sym, meta, action
     end
 
+    def perform_validation?
+      !self.meta[:skip_all_validations]
+    end
+
+    def to_sym
+      @name.to_sym
+    end
+
+    def to_s
+      @name.to_s
+    end
+
   end
 
   module WorkflowClassMethods
@@ -113,7 +139,15 @@ module Workflow
         state_name = state.name
         module_eval do
           define_method "#{state_name}?" do
-            state_name == current_state.name
+            state_name.to_sym == current_state.name.to_sym
+          end
+
+          define_method "in_#{state_name}_exit?" do
+            self.in_exit and self.in_exit.to_sym == state_name.to_sym
+          end
+
+          define_method "in_#{state_name}_entry?" do
+            self.in_entry and self.in_entry.to_sym == state_name.to_sym
           end
         end
 
@@ -124,9 +158,19 @@ module Workflow
               process_event!(event_name, *args)
             end
 
+            # this allows checks like can_approve? or can_reject_item?
+            # note we don't have a more generic can?(:approve) method.
+            # this is fully intentional, since this way it is far easier
+            # to overwrite the can_...? mehtods in a model than it would be
+            # with a generic can?(...) method.
             define_method "can_#{event_name}?" do
               return self.current_state.events.include? event_name
             end
+
+            define_method "in_transition_#{event_name}?" do
+              return false unless self.in_transition
+              return self.in_transition.to_sym == event_name.to_sym
+            end
           end
         end
       end
@@ -134,6 +178,8 @@ module Workflow
   end
 
   module WorkflowInstanceMethods
+    attr_accessor :in_entry, :in_exit, :in_transition
+
     def current_state
       loaded_state = load_workflow_state
       res = spec.states[loaded_state.to_sym] if loaded_state
@@ -153,38 +199,36 @@ module Workflow
     end
 
     def process_event!(name, *args)
+      assure_transition_allowed! name
       event = current_state.events[name.to_sym]
-      if event.nil?
-        raise NoTransitionAllowed.new \
-            "There is no event #{name.to_sym} defined for the #{current_state} state"
-      end
+      assure_target_state_exists!(event)
+      set_transition_flags(current_state, spec.states[event.transitions_to], event)
       @halted_because = nil
-      @halted = false
-      return_value = run_action(event.action, *args) || run_action_callback(event.name, *args)
+      @halted         = false
+      return_value    = run_action(event.action, *args) || run_action_callback(event.name, *args)
       if @halted
-        return false
+        run_on_failed_transition(*args)
+        return_value = false
       else
-        target_state = spec.states[event.transitions_to]
-        check_transition(event)
-        set_validation_triggers(current_state, target_state, name)
-        # TODO: shift this down by one line?!
-        # ... or possibly validate twice!
-        run_on_transition(current_state, target_state, name, *args) # if valid?
-        if valid?
-          transition(current_state, target_state, name, *args)
+        if event.perform_validation? and not valid?
+          run_on_failed_transition(*args)
+          @halted = true # make sure this one is not reset in the on_failed_transition callback
+          return_value = false
         else
-          @halted_because = 'Validation for transition failed: %{errors}' % {:errors => self.errors.full_messages.join(', ')}
-          @halted = true
-          return false
+          transition(*args)
         end
-        return_value.nil? ? true : return_value
       end
+      return_value.nil? ? true : return_value
     end
 
-    def set_validation_triggers(current_state, target_state, event_name)
-      self.instance_variable_set "@validate_on_#{current_state}_exit", true
-      self.instance_variable_set "@validate_on_#{target_state}_entry", true
-      self.instance_variable_set "@validate_on_#{event_name}", true
+    def set_transition_flags(current_state, target_state, event)
+      @in_exit       = current_state
+      @in_entry      = target_state
+      @in_transition = event
+    end
+
+    def clear_transition_flags
+      set_transition_flags nil, nil, nil
     end
 
     def halt(reason = nil)
@@ -193,8 +237,7 @@ module Workflow
     end
 
     def halt!(reason = nil)
-      @halted_because = reason
-      @halted = true
+      halt reason
       raise TransitionHalted.new(reason)
     end
 
@@ -213,27 +256,49 @@ module Workflow
       c.workflow_spec
     end
 
-    private
+    protected
+
+    def assure_transition_allowed!(name)
+      unless self.send "can_#{name}?"
+        prohibit_transition! name
+      end
+    end
+
+    def prohibit_transition!(name)
+      raise NoTransitionAllowed.new \
+          "There is no event #{name} defined for the #{current_state} state."
+    end
 
-    def check_transition(event)
+    def assure_target_state_exists!(event)
       # Create a meaningful error message instead of
       # "undefined method `on_entry' for nil:NilClass"
       # Reported by Kyle Burton
       if !spec.states[event.transitions_to]
-        raise WorkflowError.new("Event[#{event.name}]'s " +
-            "transitions_to[#{event.transitions_to}] is not a declared state.")
+        raise WorkflowError.new \
+            "Event[#{event.name}]'s transitions_to[#{event.transitions_to}] is not a declared state."
       end
     end
 
-    def transition(from, to, name, *args)
-      run_on_exit(from, to, name, *args)
-      val = persist_workflow_state to.to_s
-      run_on_entry(to, from, name, *args)
+    def transition(*args)
+      run_on_exit(*args)
+      run_on_transition(*args)
+      val = persist_workflow_state wf_target_state.name
+      run_on_entry(*args)
       val
     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
+    def run_on_transition(*args)
+      instance_exec(self.wf_prior_state.name, self.wf_target_state.name, self.wf_event_name, *args, &spec.on_transition_proc) if spec.on_transition_proc
+    end
+
+    def run_on_failed_transition(*args)
+      if spec.on_failed_transition_proc
+        return_value = instance_exec(self.wf_prior_state.name, self.wf_target_state.name, self.wf_event_name, *args, &spec.on_failed_transition_proc)
+      else
+        return_value = halt(:validation_failed)
+      end
+      clear_transition_flags
+      return return_value
     end
 
     def run_action(action, *args)
@@ -244,26 +309,42 @@ module Workflow
       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)
+    def run_on_entry(*args)
+      if self.wf_target_state.on_entry
+        instance_exec(self.wf_prior_state.name, self.wf_event_name, *args, &self.wf_target_state.on_entry)
       else
-        hook_name = "on_#{state}_entry"
-        self.send hook_name, prior_state, triggering_event, *args if self.respond_to? hook_name
+        hook_name = "on_#{self.wf_target_state.name}_entry"
+        self.send hook_name, self.wf_prior_state, self.wf_event_name, *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)
+    def run_on_exit(*args)
+      if self.wf_prior_state # no on_exit for entry into initial state
+        if self.wf_prior_state.on_exit
+          instance_exec(self.wf_target_state.name, self.wf_event_name, *args, &self.wf_prior_state.on_exit)
         else
-          hook_name = "on_#{state}_exit"
-          self.send hook_name, new_state, triggering_event, *args if self.respond_to? hook_name
+          hook_name = "on_#{self.wf_prior_state.name}_exit"
+          self.send hook_name, self.wf_target_state, self.wf_event_name, *args if self.respond_to? hook_name
         end
       end
     end
 
+    def wf_prior_state
+      @in_exit
+    end
+
+    def wf_target_state
+      @in_entry
+    end
+
+    def wf_event_name
+      @in_transition.name
+    end
+
+    def wf_event
+      @in_transition
+    end
+
     # load_workflow_state and persist_workflow_state
     # can be overriden to handle the persistence of the workflow state.
     #
@@ -280,66 +361,17 @@ module Workflow
     end
   end
 
-  module ActiveRecordInstanceMethods
-    def load_workflow_state
-      read_attribute(self.class.workflow_column)
-    end
-
-    # On transition the new workflow state is immediately saved in the
-    # database.
-    def persist_workflow_state(new_value)
-      update_attribute self.class.workflow_column, new_value
-    end
-
-    private
-
-    # Motivation: even if NULL is stored in the workflow_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.workflow_column, current_state.to_s
-    end
-  end
-
-  module RemodelInstanceMethods
-    def load_workflow_state
-      send(self.class.workflow_column)
-    end
-
-    def persist_workflow_state(new_value)
-      update(self.class.workflow_column => new_value)
-    end
-  end
-
-  module MongoidInstanceMethods
-    include ActiveRecordInstanceMethods
-    # implementation of abstract method: saves new workflow state to DB
-    def persist_workflow_state(new_value)
-      self.write_attribute(self.class.workflow_column, new_value.to_s)
-      self.save! :validate => false
-    end
-  end
-
   def self.included(klass)
     klass.send :include, WorkflowInstanceMethods
     klass.extend WorkflowClassMethods
-    if Object.const_defined?(:ActiveRecord)
-      if klass < ActiveRecord::Base
-        klass.send :include, ActiveRecordInstanceMethods
-        klass.before_validation :write_initial_state
-      end
-    elsif Object.const_defined?(:Remodel)
-      if klass < Remodel::Entity
-        klass.send :include, RemodelInstanceMethods
-      end
-    elsif Object.const_defined?(:Mongoid)
-      if klass.include? Mongoid::Document
-        klass.send :include, MongoidInstanceMethods
-        klass.after_initialize :write_initial_state
-      end
-    end
+
+#     [ActiveModelPersistence, MongoidPersistence, RemodelPersistence].each do |konst|
+#       if konst.happy_to_be_included_in? klass
+#       raise "including #{konst}"
+#         raise "including #{konst}"
+#         klass.send :include, konst
+#       end
+#     end
   end
 
   # Generates a `dot` graph of the workflow.
@@ -372,34 +404,42 @@ module Workflow
     workflow_name = "#{klass.name.tableize}_workflow".gsub('/', '_')
     fname = File.join(target_dir, "generated_#{workflow_name}")
     File.open("#{fname}.dot", 'w') do |file|
-      file.puts %Q|
-digraph #{workflow_name} {
+      file.puts klass.new.workflow_diagram(graph_options)
+    end
+    `dot -Tpdf -o'#{fname}.pdf' '#{fname}.dot'`
+    puts "A PDF file was generated at '#{fname}.pdf'"
+  end
+
+  # Returns a representation of the state diagram for the
+  # calling model as a string in dot language.
+  # See Workflow.create_workflow_diagram for more deails
+  def workflow_diagram(graph_options)
+    str = <<-EOS
+digraph #{self.class} {
   graph [#{graph_options}];
   node [shape=box];
   edge [len=1];
-      |
-
-      klass.workflow_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.transitions_to} [label="#{event_name.to_s.humanize}" #{weight_prop}];}
+    EOS
+
+    self.class.workflow_spec.states.each do |state_name, state|
+      state_meta = state.meta
+      if state == self.class.workflow_spec.initial_state
+        str << %Q{  #{state.name} [label="#{state.name}", shape=circle];\n}
+      else
+        str << %Q{  #{state.name} [label="#{state.name}", shape=#{state_meta[:terminal] ? 'doublecircle' : 'box, style=rounded'}];\n}
+      end
+      state.events.each do |event_name, event|
+        event_meta = event.meta
+        event_meta[:doc_weight] = 6 if event_meta[:main_path]
+        if event_meta[:doc_weight]
+          weight_prop = ", weight=#{event_meta[:doc_weight]}, penwidth=#{event_meta[:doc_weight] / 2 || 0.0}\n"
+        else
+          weight_prop = ''
         end
+        str << %Q{  #{state.name} -> #{event.transitions_to} [label="#{event_name.to_s.humanize}" #{weight_prop}];\n}
       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'
-
-"
+    str << "}\n"
+    return str
   end
 end

metadata

@@ -1,46 +1,30 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: validating-workflow
-version: !ruby/object:Gem::Version 
-  hash: 7
-  prerelease: false
-  segments: 
-  - 0
-  - 7
-  - 2
-  version: 0.7.2
+version: !ruby/object:Gem::Version
+  version: 0.7.6
+  prerelease: 
 platform: ruby
-authors: 
+authors:
 - Vladimir Dobriakov
 - Willem van Kerkhof
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2010-10-16 00:00:00 +02:00
-default_executable: 
+date: 2014-02-27 00:00:00.000000000 Z
 dependencies: []
-
-description: |
-  Workflow is a finite-state-machine-inspired API for modeling and interacting
-      with what we tend to refer to as 'workflow'.
-  
-      * nice DSL to describe your states, events and transitions
-      * robust integration with ActiveRecord and non relational data stores
-      * various hooks for single transitions, entering state etc.
-      * convenient access to the workflow specification: list states, possible events
-        for particular state
-      * state and transition dependent validations for ActiveModel
-
-email: 
-- vladimir@geekq.net
-- wvk@consolving.de
+description: ! "Validating-Workflow is a finite-state-machine-inspired API for modeling
+  and interacting\n    with what we tend to refer to as 'workflow'.\n\n    * nice
+  DSL to describe your states, events and transitions\n    * robust integration with
+  ActiveRecord and non relational data stores\n    * various hooks for single transitions,
+  entering state etc.\n    * convenient access to the workflow specification: list
+  states, possible events\n      for particular state\n    * state and transition
+  dependent validations for ActiveModel\n"
+email: vladimir@geekq.net, wvk@consolving.de
 executables: []
-
 extensions: []
-
-extra_rdoc_files: 
+extra_rdoc_files:
 - README.markdown
-files: 
+files:
 - .gitignore
 - MIT-LICENSE
 - README.markdown
@@ -55,44 +39,36 @@ files:
 - test/without_active_record_test.rb
 - workflow.rb
 - lib/workflow/state_dependent_validations.rb
-has_rdoc: true
 homepage: http://www.geekq.net/workflow/
 licenses: []
-
 post_install_message: 
-rdoc_options: 
+rdoc_options:
 - --charset=UTF-8
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
-rubyforge_project: workflow
-rubygems_version: 1.3.7
+rubyforge_project: 
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
-summary: A replacement for acts_as_state_machine.
-test_files: 
+summary: A replacement for acts_as_state_machine, an enhancement of workflow.
+test_files:
 - test/couchtiny_example.rb
 - test/main_test.rb
 - test/test_helper.rb
 - test/without_active_record_test.rb
 - test/multiple_workflows_test.rb
 - test/readme_example.rb
+has_rdoc: