state_flow 0.1.0 → 0.2.0

data/README.rdoc

@@ -3,38 +3,76 @@
 
 状態遷移のためのDSLを提供するためのActiveRecordを拡張するプラグインです。
 
+基本的にUMLのステートチャート図に忠実に状態遷移を記述できるようにすることが最終目標です。
+現在のところ、以下のような機能があります。
+ * イベント／ガード／アクションの設定
+  * イベントとして定義可能なのは、以下の通りです。
+   * モデルに対する任意の名前のアクション(メソッドとして定義されるので、メソッド名に被っていると上書きされます)。
+   * アクションの戻り値
+   * 例外
+  * ガードはその条件に該当するかどうかを判断するメソッド名を指定します。
+  * アクションはモデルのメソッドを指定しますが、状態を変更するコードは不要です。
+  * 状態の遷移は自動で行われます。
+ * 状態のネスト
+  * 親の状態で定義されたイベントが実行された場合に正しく状態を遷移します。
+ * 状態を遷移する際のトランザクションの制御
+  * 各状態間の遷移毎にトランザクションを発行します。
+  * 例外発生時などにはロールバックを行い、(指定されていれば)例外に対応する状態に遷移してモデルを保存します。
+
+=== サンプル
 以下のような記述が可能です。
 
- class Page < ActiveRecord::Base
-   validates_presence_of :name
+ class Order < ActiveRecord::Base
+
+   class StockShortageError < StandardError
+   end
 
    selectable_attr :status_cd do
-     entry '01', :editable       , '編集可'
-     entry '04', :waiting_publish, '公開待ち'
-     entry '05', :publishing     , '公開処理中'
-     entry '06', :publishing_done, '公開処理完了'
-     entry '07', :published      , '公開済'
-     entry '08', :publish_failure, '公開失敗'
+     entry '00', :waiting_settling , '決済前'
+     entry '01', :online_settling  , '決済中'
+     entry '02', :receiving        , '入金待ち'
+     entry '03', :deliver_preparing, '配送準備中'
    end
 
    state_flow(:status_cd) do
-     state :created => {event(:publish) => :waiting_publish, :lock => true}
-
-     with_options(:failure => :publish_failure) do |publishing|
-       publishing.state :waiting_publish => :publishing, :lock => true
-       publishing.state :publishing => {action(:start_publish) => :publishing_done}
-       publishing.state :publishing_done => :published, :if => :accessable?
-       publishing.state :publish_failure
+     origin(:waiting_settling)
+
+     group(:valid) do 
+       from(:waiting_settling) do
+         guard(:pay_cash_on_delivery?).action(:reserve_point).action(:reserve_stock){
+           event(:reserve_stock_ok).to(:deliver_preparing)
+           event_else.action(:delete_point).to(:stock_error)
+         }
+         guard_else.action(:reserve_point).action(:reserve_stock, :temporary => true){
+           event(:reserve_stock_ok){
+             guard(:bank_deposit?).action(:send_mail_thanks).to(:receiving)
+             guard(:credit_card?).to(:online_settling)
+             guard(:foreign_payment?).action(:settle).to(:online_settling)
+           }
+           event_else{
+             guard(:foreign_payment?).action(:delete_point).action(:send_mail_stock_shortage)
+           }.to(:stock_error)
+         }
+         recover(StockShortageError).to(:stock_error)
+       end
+
+       from(:online_settling) do
+         guard(:credit_card?).action(:settle){
+           event(:ok).action(:reserve_stock).action(:send_mail_thanks).to(:deliver_preparing)
+           event_else.action(:release_stock).action(:delete_point).to(:settlement_error)
+         }
+         guard(:foreign_payment?){
+           event(:settlement_ok).to(:deliver_preparing)
+           event(:settlement_ng).action(:release_stock).action(:delete_point).action(:send_mail_invalid_purchage).to(:settlement_error)
+         }
+         recover(Exception).action(:release_stock).action(:delete_point).to(:settlement_error)
+       end
      end
-
-     state :published
-   end
-
-   def start_publish
-     # 公開時の処理
    end
  end
 
+詳しくはspec/order_spec.rbをご覧ください。
+
 == セットアップ
 state_flowプラグインはselectable_attrに依存しています。
 
@@ -78,8 +116,8 @@ config/initializers/state_flow.rb
 
 == Example
 以下のテスト用のモデルや、テストをご覧ください。
-http://github.com/akm/state_flow/blob/master/spec/resources/models/page.rb
-http://github.com/akm/state_flow/blob/master/spec/page_spec.rb
+http://github.com/akm/state_flow/blob/master/spec/resources/models/order.rb
+http://github.com/akm/state_flow/blob/master/spec/order_spec.rb
 
 
 Copyright (c) 2009 [Takeshi AKIMA], released under the MIT license

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/lib/state_flow/action.rb

@@ -2,66 +2,32 @@
 require 'state_flow'
 module StateFlow
 
-  class Action
-    attr_reader :flow
-    attr_accessor :success_key
-    attr_accessor :failure_key
-    attr_accessor :lock, :if, :unless
+  class Action < Element
+    include ActionClient
+    include EventClient
+    include GuardClient
 
-    def initialize(flow)
-      @flow = flow
-      @record_key_on_thread = "#{self.class.name}_#{self.object_id}_record"
-    end
-
-    def record
-      Thread.current[@record_key_on_thread]
-    end
-
-    def record=(value)
-      Thread.current[@record_key_on_thread] = value
-    end
-
-    def process(record)
-      return if self.if && !call_or_send(self.if, record)
-      return if self.unless && call_or_send(self.unless, record)
-      self.record = record
-      begin
-        block_given? ? yield(self) : proceed
-      ensure
-        self.record = nil
-      end
-    end
-    
-    def proceed
-      flow.process_with_log(self.record, success_key, failure_key)
+    attr_reader :method_name, :method_args
+    def initialize(origin, method_name, *method_args, &block)
+      @method_name, @method_args = method_name, method_args
+      super(origin, &block)
     end
     
-    def call_or_send(filter, record)
-      filter.respond_to?(:call) ? filter.call(record) :
-        filter.is_a?(Array) ? record.send(*filter) : record.send(filter)
-    end
-
-    def inspect
-      result = "<#{self.class.name}"
-      result << " @name=#{@name.inspect}" if @name
-      result << " @success_key=#{@success_key.inspect}" if @success_key
-      result << " @failure_key=#{@failure_key.inspect}" if @failure_key
-      result << " @lock=#{@lock.inspect}" if @lock
-      result << " @if=#{@if.inspect}" if @if
-        result << " @unless=#{@unless.inspect}" if @unless
-        result << '>'
-    end
-
-    module Executable
-      attr_accessor :action
-
-      def options        ; @options ||= {} ; end
-      def options=(value); @options = value; end
-
-      def success_key; action.success_key if action; end
-      def failure_key; action.failure_key if action; end
+    def process(context)
+      context.trace(self)
+      context.mark_proceeding
+      exception_handling(context) do
+        result = context.record_send(method_name, *method_args)
+        event = event_for_action_result(result)
+        if event
+          event.process(context)
+        elsif action
+          action.process(context)
+        end
+        update_to_destination(context)
+      end
     end
 
   end
-  
+
 end

data/lib/state_flow/action_client.rb

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+require 'state_flow'
+module StateFlow
+
+  module ActionClient
+    def action(method_name = nil, *method_args, &block)
+      if method_name
+        result = Action.new(self, method_name, *method_args, &block)
+        @action = result
+        result
+      else
+        @action
+      end
+    end
+  end
+end

data/lib/state_flow/action_event.rb

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+require 'state_flow'
+module StateFlow
+
+  class ActionEvent < Event
+    ELSE = Object.new
+
+    attr_reader :matcher
+    def initialize(origin, matcher, &block)
+      @matcher = matcher
+      super(origin, &block)
+    end
+
+    def match?(action_result)
+      return true if matcher == ActionEvent::ELSE
+      matcher === action_result
+    end
+
+  end
+
+end

data/lib/state_flow/base.rb

@@ -3,28 +3,32 @@ require 'state_flow'
 module StateFlow
 
   class Base
-    include Builder
     
-    module ClassMethods
+    module ClientClassMethods
+      def state_flow_for(selectable_attr)
+        return nil unless @state_flows
+        @state_flows.detect{|flow| flow.attr_name == selectable_attr}
+      end
 
-      def process_state(selectable_attr, *keys, &block)
+      def state_flow(selectable_attr, options = nil, &block)
         options = {
-          :transactional => false, # :each, # :all
-        }.update(keys.extract_options!)
-        options[:transactional] = :each if options[:transactional] == true
-        state_flow = state_flow_for(selectable_attr)
-        raise ArgumentError, "state_flow not found: #{selectable_attr.inspect}" unless state_flow
-        transaction_if_need(options[:transactional] == :all) do
-          keys.each do |key|
-            entry = state_flow[key]
-            raise ArgumentError, "entry not found: #{key.inspect}" unless entry
-            transaction_if_need(options[:transactional] == :each) do
-              entry.process(&block)
-            end
+          :attr_key_name => "#{self.enum_base_name(selectable_attr)}_key".to_sym
+        }.update(options || {})
+        flow = Base.new(self, selectable_attr, options[:attr_key_name])
+        flow.instance_eval(&block)
+        @state_flows ||= []
+        @state_flows << flow
+        module_eval(<<-EOS, __FILE__, __LINE__)
+          def process_#{selectable_attr}(context_or_options = nil)
+            flow = self.class.state_flow_for(:#{selectable_attr})
+            context = flow.prepare_context(self, context_or_options)
+            context.process(flow)
           end
-        end
+        EOS
+        NamedEvent.build_event_methods(flow)
+        flow
       end
-      
+          
       def transaction_if_need(with_transaction, &block)
         if with_transaction
           self.transaction(&block)
@@ -33,30 +37,70 @@ module StateFlow
         end
       end
     end
-    
+
     attr_reader :klass, :attr_name, :attr_key_name, :status_keys
-    attr_reader :entries
     def initialize(klass, attr_name, attr_key_name)
       @klass, @attr_name, @attr_key_name = klass, attr_name, attr_key_name
       @status_keys = klass.send(@attr_key_name.to_s.pluralize).map{|s| s.to_sym}
-      @entries = []
     end
 
     def state_cd_by_key(key)
       @state_cd_by_key_method_name ||= "#{klass.enum_base_name(attr_name)}_id_by_key"
       klass.send(@state_cd_by_key_method_name, key)
     end
-    
-    def entry_for(key)
-      unless @entry_hash
-        @entry_hash = entries.inject({}) do |dest, entry|
-          dest[entry.key] = entry
+
+    def state(name, &block)
+      result = State.new(self, name, &block)
+      states << result
+      result
+    end
+    alias_method :group, :state
+    alias_method :state_group, :state
+
+    def states
+      @states ||= []
+    end
+
+    def all_states
+      unless @all_states
+        @all_states = states.map{|state| state.descendants}.flatten.inject({}) do |dest, state|
+          dest[state.name] = state
           dest
         end
       end
-      @entry_hash[key]
+      @all_states
+    end
+
+    def concrete_states
+      unless @concrete_states
+        @concrete_states = {}
+        all_states.each do |name, state| 
+          @concrete_states[state.name] = state if state.concrete?
+        end
+      end
+      @concrete_states
+    end
+
+    def origin(value = nil)
+      if value
+        @origin_name = value
+      else
+        @origin ||= all_states[@origin_name]
+      end
+    end
+
+    def prepare_context(record, context_or_options = nil)
+      context_or_options.is_a?(StateFlow::Context) ?
+        context_or_options :
+        StateFlow::Context.new(self, record, context_or_options)
+    end
+
+    def process(context)
+      current_key = context.current_attr_key
+      state = concrete_states[current_key]
+      state.process(context)
+      context
     end
-    alias_method :[], :entry_for
 
     def process_with_log(record, success_key, failure_key)
       origin_state = record.send(attr_name)
@@ -99,7 +143,6 @@ module StateFlow
     def inspect
       result = "<#{self.class.name} @attr_name=#{@attr_name.inspect} @attr_key_name=#{@attr_key_name.inspect}"
       result << " @klass=\"#{@klass.name}\""
-      result << " @entries=#{@entries.inspect}"
       result << '>'
     end
 

data/lib/state_flow/context.rb

@@ -0,0 +1,82 @@
+module StateFlow
+
+  class Context
+    
+    attr_reader :flow, :record, :options
+    
+    def initialize(flow, record, options = nil)
+      @flow, @record = flow, record
+      @options = {
+        :save => :save!,
+        :keep_process => true
+      }.update(options || {})
+    end
+
+    def process(flow_or_named_event = flow)
+      flow.klass.transaction do
+        flow_or_named_event.process(self)
+        save_record_if_need
+      end
+      if options[:keep_process]
+        last_current_key = current_attr_key
+        while true
+          @mark_proceeding = false
+          flow.process(self)
+          save_record_if_need if @mark_proceeding
+          break unless @mark_proceeding
+          break if last_current_key == current_attr_key
+          last_current_key = current_attr_key
+        end
+      end
+      self
+    end
+
+    def mark_proceeding
+      @mark_proceeding = true
+    end
+
+    def trace(object)
+      stack_trace << object
+    end
+
+    def stack_trace
+      @stack_trace ||= []
+    end
+
+
+    def save_record_if_need
+      return unless options[:save]
+      record.send(options[:save])
+    end
+
+    def record_send(*args, &block)
+      record.send(*args, &block)
+    end
+
+    def record_reload_if_possible
+      record.reload unless record.new_record?
+    end
+
+    def transaction_rollback
+      record.class.connection.rollback_db_transaction
+    end
+    
+    def exceptions
+      @exceptions ||= []
+    end
+
+    def recovered_exceptions
+      @recovered_exceptions ||= []
+    end
+
+    def recovered?(exception)
+      recovered_exceptions.include?(exception)
+    end
+
+    def current_attr_key
+      record_send(flow.attr_key_name)
+    end
+
+  end
+
+end

data/lib/state_flow/element.rb

@@ -0,0 +1,60 @@
+# -*- coding: utf-8 -*-
+require 'state_flow'
+module StateFlow
+
+  class Element
+    include ElementVisitable
+
+    attr_reader :origin
+    attr_reader :destination
+    def initialize(origin, &block)
+      @origin = origin
+      instance_eval(&block) if block
+    end
+
+    def to(destination)
+      @destination = destination
+    end
+
+    def flow
+      @flow || origin.flow
+    end
+
+    def state
+      origin.is_a?(State) ? origin : origin.state
+    end
+
+    def update_to_destination(context)
+      return unless destination
+      context.mark_proceeding
+      context.record_send("#{flow.attr_key_name}=", destination)
+    end
+
+    class << self
+      def uninspected_var(*vars)
+        @@uninspected_var_hash ||= {}
+        @@uninspected_var_hash[self] ||= []
+        @@uninspected_var_hash[self].concat(vars.map{|v| v.to_s.sub(/^([^@])/){"@#{$1}"}})
+      end
+
+      def uninspected_vars
+        @uninspected_vars ||= @@uninspected_var_hash.nil? ? %w(@flow @origin) :
+          self.ancestors.map{|klass| @@uninspected_var_hash[klass] || []}.flatten
+      end
+   end
+   self.uninspected_var :flow, :origin, :events, :guards, :action
+ 
+    def inspect
+      vars = (instance_variables - self.class.uninspected_vars).map do |name|
+        "#{name}=#{instance_variable_get(name).inspect}"
+      end
+      # vars = []
+      vars.unshift("%s:%#x" % [self.class.name, self.object_id])
+      "#<#{vars.join(' ')}>"
+    end
+
+
+    
+  end
+
+end

data/lib/state_flow/element_visitable.rb

@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+require 'state_flow'
+module StateFlow
+
+  module ElementVisitable
+    # Visitorパターン
+    def visit(&block)
+      results = block.call(self)
+      (results || [:events, :guards, :action]).each do |elements_name|
+        next if [:events, :guards, :action].include?(elements_name) && !respond_to?(elements_name)
+        elements = send(elements_name)
+        elements = [elements] unless elements.is_a?(Array)
+        elements.each do |element|
+          element.visit(&block) if element
+        end
+      end
+    end
+  end
+end

data/lib/state_flow/event.rb

@@ -2,19 +2,19 @@
 require 'state_flow'
 module StateFlow
 
-  class Event
-    include Action::Executable
-    attr_reader :flow, :name
-
-    def initialize(flow, name)
-      @flow = flow
-      @name = name.to_s.to_sym
-    end
-
-    def inspect
-      result = "<#{self.class.name} @name=#{@name.inspect}"
-      result << " @action=#{@action.inspect}" if @action
-      result << ">"
+  class Event < Element
+    include GuardClient
+    include ActionClient
+    include ExceptionHandlerClient
+    
+    def process(context)
+      context.trace(self)
+      if guard = guard_for(context)
+        guard.process(context)
+      else
+        action.process(context) if action
+      end
+      update_to_destination(context)
     end
   end
 

data/lib/state_flow/event_client.rb

@@ -0,0 +1,88 @@
+# -*- coding: utf-8 -*-
+require 'state_flow'
+module StateFlow
+
+  module EventClient
+    include ExceptionHandlerClient
+    
+    def events
+      @events ||= []
+    end
+
+    def event(*name_or_matcher_or_exceptions, &block)
+      options = name_or_matcher_or_exceptions.extract_options!
+      if name_or_matcher_or_exceptions.all?{|v| v.is_a?(Class) && v <= Exception}
+        handle_exception(*name_or_matcher_or_exceptions.push(options), &block)
+      else
+        if name_or_matcher_or_exceptions.length > 1
+          raise ArgumentError, "event(event_name) or event(action_result) or event(Exception1, Exception2...)"
+        end
+        name_or_matcher = name_or_matcher_or_exceptions.first
+        if origin.is_a?(State)
+          named_event(name_or_matcher, &block)
+        else
+          action_event(name_or_matcher, &block)
+        end
+      end
+    end
+
+    def named_event(name, &block)
+      result = NamedEvent.new(self, name, &block)
+      events << result
+      result
+    end
+
+    def action_event(matcher, &block)
+      result = ActionEvent.new(self, matcher, &block)
+      events << result
+      result
+    end
+
+    def event_else(&block)
+      if origin.is_a?(State)
+        raise ArgumentError, "event_else can't be after/in a state but an action"
+      end
+      result = ActionEvent.new(self, ActionEvent::ELSE, &block)
+      events << result
+      result
+    end
+
+    def handle_exception(*args, &block)
+      result = ExceptionHandler.new(self, *args, &block)
+      events << result
+      result
+    end
+
+    def recover(*args, &block)
+      options = {
+        :recovering => true, 
+        :rolling_back => true, 
+        :logging => :error
+      }.update(args.extract_options!)
+      handle_exception(*(args << options), &block)
+    end
+
+    def event_for_action_result(result)
+      events.detect{|ev| ev.match?(result)}
+    end
+
+    def exception_handling(context)
+      begin
+        yield
+      rescue Exception => exception
+        context.exceptions << exception
+        context.trace(exception)
+        handlers = events.select{|ev| ev.is_a?(ExceptionHandler)}
+        handlers.each do |handler|
+          next unless handler.match?(exception)
+          handler.process(context)
+          break
+        end
+        raise exception unless context.recovered?(exception)
+      end
+    end
+
+  end
+
+
+end