state_flow 0.1.0

data/.gitignore

@@ -0,0 +1,2 @@
+/coverage
+/pkg

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 [name of plugin creator]
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,85 @@
+= StateFlow
+== StateFlowとは？
+
+状態遷移のためのDSLを提供するためのActiveRecordを拡張するプラグインです。
+
+以下のような記述が可能です。
+
+ class Page < ActiveRecord::Base
+   validates_presence_of :name
+
+   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, '公開失敗'
+   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
+     end
+
+     state :published
+   end
+
+   def start_publish
+     # 公開時の処理
+   end
+ end
+
+== セットアップ
+state_flowプラグインはselectable_attrに依存しています。
+
+- selectable_attr
+-- http://github.com/akm/selectable_attr
+- selectable_attr_rails
+-- http://github.com/akm/selectable_attr_rails
+
+== Railsで使う場合
+
+=== プラグインとしてインストール
+ ruby script/plugin install git://github.com/akm/selectable_attr.git
+ ruby script/plugin install git://github.com/akm/selectable_attr_rails.git
+ ruby script/plugin install git://github.com/akm/state_flow.git
+でオッケーです。
+
+== gemの場合
+まずgemcutterの設定をしていなかったら、
+ gem install gemcutter
+ gem tumble
+を実行した後、
+ gem install selectable_attr selectable_attr_rails state_flow
+を実行するとインストール完了。
+
+で、config/initializersに以下の２つのファイルを作成すればオッケーです。
+
+config/initializers/selectable_attr.rb
+
+ require 'selectable_attr'
+ require 'selectable_attr_i18n'
+ require 'selectable_attr_rails'
+ SelectableAttrRails.add_features_to_rails
+
+config/initializers/state_flow.rb
+
+ require 'state_flow'
+ ActiveRecord::Base.module_eval do
+   include StateFlow
+ end
+
+
+== 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
+
+
+Copyright (c) 2009 [Takeshi AKIMA], released under the MIT license

data/Rakefile

@@ -0,0 +1,55 @@
+require 'rubygems'
+gem 'rspec', '>= 1.1.4'
+require 'rake'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+require 'spec/rake/verify_rcov'
+ 
+desc 'Default: run unit tests.'
+task :default => :spec
+ 
+task :pre_commit => [:spec, 'coverage:verify']
+ 
+desc 'Run all specs under spec/**/*_spec.rb'
+Spec::Rake::SpecTask.new(:spec => 'coverage:clean') do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.spec_opts = ['--options', 'spec/spec.opts']
+  t.rcov_dir = 'coverage'
+  t.rcov = true
+  # t.rcov_opts = ["--include-file", "lib\/*\.rb", "--exclude", "spec\/"]
+  t.rcov_opts = ["--exclude", "spec\/"]
+end
+ 
+desc 'Generate documentation for the state_flow plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'State_flow'
+  rdoc.options << '--line-numbers' << '--inline-source' << '-c UTF-8'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+ 
+namespace :coverage do
+  desc "Delete aggregate coverage data."
+  task(:clean) { rm_f "coverage" }
+ 
+  desc "verify coverage threshold via RCov"
+  RCov::VerifyTask.new(:verify => :spec) do |t|
+    t.threshold = 100.0 # Make sure you have rcov 0.7 or higher!
+    t.index_html = 'coverage/index.html'
+  end
+end
+ 
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "state_flow"
+    s.summary  = "state_flow provides a DSL for State Transition"
+    s.description  = "state_flow provides a DSL for State Transition"
+    s.email    = "akima@gmail.com"
+    s.homepage = "http://github.com/akm/state_flow/"
+    s.authors  = ["Takeshi Akima"]
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/init.rb

@@ -0,0 +1,5 @@
+require 'state_flow'
+
+ActiveRecord::Base.module_eval do
+  include StateFlow
+end

data/install.rb

@@ -0,0 +1 @@
+# Install hook code here

data/lib/state_flow/action.rb

@@ -0,0 +1,67 @@
+# -*- coding: utf-8 -*-
+require 'state_flow'
+module StateFlow
+
+  class Action
+    attr_reader :flow
+    attr_accessor :success_key
+    attr_accessor :failure_key
+    attr_accessor :lock, :if, :unless
+
+    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)
+    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
+    end
+
+  end
+  
+end

data/lib/state_flow/base.rb

@@ -0,0 +1,108 @@
+# -*- coding: utf-8 -*-
+require 'state_flow'
+module StateFlow
+
+  class Base
+    include Builder
+    
+    module ClassMethods
+
+      def process_state(selectable_attr, *keys, &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
+          end
+        end
+      end
+      
+      def transaction_if_need(with_transaction, &block)
+        if with_transaction
+          self.transaction(&block)
+        else
+          yield
+        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
+          dest
+        end
+      end
+      @entry_hash[key]
+    end
+    alias_method :[], :entry_for
+
+    def process_with_log(record, success_key, failure_key)
+      origin_state = record.send(attr_name)
+      origin_state_key = record.send(attr_key_name)
+      begin
+        yield(record) if block_given?
+        # success_keyが指定されない場合、その変更はアクションとして指定されたメソッドに依存します。
+        if success_key 
+          record.send("#{attr_key_name}=", success_key)
+          record.save!
+        end
+      rescue Exception => error
+        log_attrs = {
+          :target => record,
+          :origin_state => origin_state,
+          :origin_state_key => origin_state_key ? origin_state_key.to_s : nil,
+          :dest_state => self.state_cd_by_key(success_key),
+          :dest_state_key => success_key ? success_key.to_s : nil
+        }
+        StateFlow::Log.error(error, log_attrs)
+        if failure_key
+          retry_count = 0
+          begin
+            record.send("#{attr_key_name}=", failure_key)
+            record.save!
+          rescue Exception => fatal_error
+            if retry_count == 0
+              retry_count += 1
+              record.attributes = record.class.find(record.id).attributes
+              retry
+            end
+            StateFlow::Log.fatal(fatal_error, log_attrs)
+            raise fatal_error
+          end
+        end
+        raise error
+      end
+    end
+
+    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
+
+  end
+
+end

data/lib/state_flow/builder.rb

@@ -0,0 +1,193 @@
+# -*- coding: utf-8 -*-
+require 'state_flow'
+module StateFlow
+
+  module Builder
+    module ClientClassMethods
+      def state_flow_for(selectable_attr)
+        return nil unless @state_flows
+        @state_flows.detect{|flow| flow.attr_name == selectable_attr}
+      end
+
+      def state_flow(selectable_attr, options = nil, &block)
+        options = {
+          :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)
+        flow.setup_events
+        @state_flows ||= []
+        @state_flows << flow
+        flow
+      end
+    end
+
+    def new_entry(key)
+      @entry_hash = nil
+      result = Entry.new(self, key)
+      entries << result
+      result
+    end
+
+    def state(*args)
+      raise_invalid_state_argument if args.length > 2
+      if args.length == 2
+        # 引数が２個ならできるだけ一つのHashにまとめます。
+        case args.first
+        when Hash then 
+          return state(args.first.update(args.last))
+        when Symbol, String
+          return state({args.first => nil}.update(args.last))
+        else
+          raise_invalid_state_argument
+        end
+      end
+      # 引数が一つだけになってます
+      arg = args.first
+      case arg
+      when Symbol, String
+        return state({args.first => nil})
+      when Hash then
+        # through
+      else
+        raise_invalid_state_argument
+      end
+      # 引数がHash一つだけの場合
+      base_options = extract_common_options(arg)
+      arg.each do |key, value|
+        entry = new_entry(key)
+        build_entry(entry, value, base_options)
+      end
+    end
+
+    def action(name)
+      NamedAction.new(self, name)
+    end
+
+    def event(name)
+      Event.new(self, name)
+    end
+
+    def setup_events
+      event_defs = {}
+      entries.each do |entry|
+        origin_key = entry.key
+        entry.events.each do |event|
+          event_trans = event_defs[event.name] ||= {}
+          event_trans[origin_key] = [event.success_key, event.failure_key]
+        end
+      end
+      event_defs.each do |event_name, trans|
+        method_def = <<-"EOS"
+          def #{event_name}
+            @state_flow ||= self.class.state_flow_for(:#{attr_name})
+            @#{event_name}_transitions ||= #{trans.inspect}
+            @state_flow.process_with_log(self, 
+              *@#{event_name}_transitions[#{attr_key_name}])
+          end
+        EOS
+        if klass.instance_methods.include?(event_name)
+          klass.logger.warn("state_flow plugin was going to define #{event_name} but didn't do it because #{event_name} does exist.")
+        else
+          klass.module_eval(method_def, __FILE__, __LINE__)
+        end
+      end
+    end
+    
+    private
+    
+    def build_entry(entry, options_or_success_key, base_options)
+      if options_or_success_key.nil?
+        return null_action_entry(entry, base_options)
+      end
+      case options_or_success_key
+      when String, Symbol then
+        return null_action_entry(entry, base_options, options_or_success_key.to_sym)
+      when Action then
+        entry.action = setup_action(options_or_success_key, base_options)
+        return entry
+      when Hash then
+        options = options_or_success_key
+        prior_options = extract_common_options(options)
+        options_keys = options.keys
+        if options_keys.all?{|key| key.is_a?(Action)}
+          build_action(entry, options, base_options.merge(prior_options))
+        elsif options_keys.all?{|key| key.is_a?(Event)}
+          raise_invalid_state_argument unless entry.is_a?(Entry)
+          build_events(entry, options, base_options.merge(prior_options))
+        else
+          raise_invalid_state_argument
+        end
+      when Array then
+        options_or_success_key.each do |options|
+          each_base_options = base_options.merge(extract_common_options(options))
+          build_entry(entry, options, each_base_options)
+        end
+      else
+        raise_invalid_state_argument
+      end
+    end
+
+    def null_action_entry(entry, options, success_key = nil)
+      action = Action.new(self)
+      options = options.dup
+      entry.action = setup_action(action, options, success_key)
+      entry.options = options
+      entry
+    end
+
+    def build_action(entry, action_hash, options)
+      raise_invalid_state_argument unless action_hash.length == 1
+      options = options.dup
+      entry.action = setup_action(action_hash.keys.first, options, action_hash.values.first)
+      entry.options = options
+    end
+
+    def setup_action(action, options, success_key = nil)
+      action.success_key = success_key.to_sym if success_key
+      action.failure_key = options.delete(:failure)
+      action.lock = options.delete(:lock)
+      action.if = options.delete(:if)
+      action.unless = options.delete(:unless)
+      action
+    end
+
+
+    def build_events(entry, event_hash, options)
+      event_hash.each do |event, value|
+        build_entry(event, value, options)
+        entry.events << event
+      end
+    end
+
+    COMMON_OPTION_NAMES = [:lock, :if, :unless, :failure]
+
+    def extract_common_options(hash)
+      COMMON_OPTION_NAMES.inject({}) do |dest, name|
+        value = hash.delete(name)
+        dest[name] = value if value
+        dest
+      end
+    end
+
+    def raise_invalid_state_argument
+      raise ArgumentError, state_argument_pattern
+    end
+
+    def state_argument_pattern
+      descriptions = <<-"EOS"
+        state arguments pattern:
+          * state :<state_name>
+          * state :<state_name> => :<new_state_name>
+          * state :<state_name> => action(:<method_name>)
+          * state :<state_name> => { action(:<method_name>) => :<new_state_name>}
+          * state :<state_name> => { event(:<event_name1>) => :<new_state_name>, event(:<event_name2>) => :<new_state_name>}
+          * state :<state_name> => { event(:<event_name1>) => { action(:<method_name1>) => :<new_state_name>}, event(:<event_name2>) => {action(:<method_name1>) => :<new_state_name>} }
+        And you can append :lock, :if, :unless option in Hash
+      EOS
+      descriptions.split(/$/).map{|s| s.sub(/^\s{8}/, '')}.join("\n")
+    end
+    
+  end
+
+end

data/lib/state_flow/entry.rb

@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+require 'state_flow'
+module StateFlow
+
+  class Entry
+    include Action::Executable
+    attr_reader :flow, :key
+
+    def initialize(flow, key)
+      @flow = flow
+      @key = key.to_s.to_sym
+    end
+    
+    def events
+      @events ||= [];
+    end
+
+    def event_for(name)
+      events.detect{|event| event.name == name}
+    end
+
+    def process(&block)
+      value = flow.state_cd_by_key(key)
+      find_options = {
+        :order => "id asc",
+        :conditions => ["#{flow.attr_name} = ?", value]
+      }
+      find_options[:lock] = action.lock if action.lock
+      if record = flow.klass.find(:first, find_options)
+        action.process(record, &block) if action
+      end
+    end
+    
+    def inspect
+      result = "<#{self.class.name} @key=#{@key.inspect}"
+      result << " @action=#{@action.inspect}" if @action
+      if @events && !@events.empty?
+        result << " @events=#{@events.sort_by{|event|event.name.to_s}.inspect}"
+      end
+      result << ">"
+    end
+  end
+
+end

data/lib/state_flow/event.rb

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+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 << ">"
+    end
+  end
+
+end

data/lib/state_flow/log.rb

@@ -0,0 +1,30 @@
+module StateFlow
+  class Log < ActiveRecord::Base
+    set_table_name 'state_flow_logs'
+    
+    belongs_to :target, :polymorphic => true
+
+    class << self
+      def fatal(message, options = nil); write(message, :fatal, options); end
+      def error(message, options = nil); write(message, :error, options); end
+      def warn (message, options = nil); write(message, :warn , options); end
+      def info (message, options = nil); write(message, :info , options); end
+      def debug(message, options = nil); write(message, :debug, options); end
+
+      private
+      def write(message, level, options = nil)
+        log = self.new(options || {})
+        log.level = level.to_s
+        log.descriptions = message.is_a?(Exception) ? format_exception(message) : message
+        unless log.save
+          logger.error(log.inspect)
+        end
+      end
+      
+      def format_exception(exception)
+        '%s\n  %s' % [exception.to_s, exception.backtrace.join("\n  ")]
+      end
+
+    end
+  end
+end

data/lib/state_flow/named_action.rb

@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+require 'state_flow'
+module StateFlow
+
+  class NamedAction < Action
+    attr_reader :name
+    def initialize(flow, name)
+      super(flow)
+      @name = name.to_s.to_sym
+    end
+
+    def proceed
+      flow.process_with_log(self.record, success_key, failure_key) do
+        self.record.send(name)
+      end
+    end
+  end
+
+end

data/lib/state_flow.rb

@@ -0,0 +1,20 @@
+module StateFlow
+  autoload :Base, 'state_flow/base'
+  autoload :Builder, 'state_flow/builder'
+  autoload :Action, 'state_flow/action'
+  autoload :NamedAction, 'state_flow/named_action'
+  autoload :Event, 'state_flow/event'
+  autoload :Entry, 'state_flow/entry'
+  autoload :Log, 'state_flow/log'
+  
+  # autoload :ActiveRecord, 'state_flow/active_record'
+  
+  def self.included(mod)
+    mod.module_eval do
+      extend ::StateFlow::Builder::ClientClassMethods
+      extend ::StateFlow::Base::ClassMethods
+      # include ::StateFlow::ActiveRecord if mod.ancestors.map{|m| m.name}.include?('ActiveRecord::Base')
+    end
+  end
+  
+end

data/spec/.gitignore

@@ -0,0 +1 @@
+/*.sqlite3