ardm-is-state_machine 1.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 33f98553240c3dda7d71d6c6778ced2eef9aea70
+  data.tar.gz: 47c1378362e0d2c2e4cc6250b9fb20903627a493
+SHA512:
+  metadata.gz: 348a08cd707301ae0978cad8f57eb347de5d44b14943ebf09ccb10feffbee0388d831487499c8e73128f0b959afcce18b9b8535d25c04f6eda752e7c5eb84621
+  data.tar.gz: a7fd6133e0d63ae775cae9e574ef465578769a05ba0be7453933614133f3a14d80f15677daf61cadbf34a65e20808eee2b5e9abc4be6c14d2c4340d1b635a0a6

data/.gitignore

@@ -0,0 +1,35 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## Rubinius
+*.rbc
+
+## PROJECT::GENERAL
+*.gem
+coverage
+rdoc
+pkg
+tmp
+doc
+log
+.yardoc
+measurements
+
+## BUNDLER
+.bundle
+Gemfile.*
+
+## PROJECT::SPECIFIC
+spec/db/

data/.travis.yml

@@ -0,0 +1,11 @@
+language: ruby
+sudo: false
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.5
+  - 2.2.0
+matrix:
+  allow_failures:
+    - rvm: 2.1.5
+    - rvm: 2.2.0

data/Gemfile

@@ -0,0 +1,65 @@
+require 'pathname'
+
+source 'https://rubygems.org'
+
+gemspec
+
+SOURCE         = ENV.fetch('SOURCE', :git).to_sym
+REPO_POSTFIX   = SOURCE == :path ? ''                                : '.git'
+DATAMAPPER     = SOURCE == :path ? Pathname(__FILE__).dirname.parent : 'http://github.com/ar-dm'
+DM_VERSION     = '~> 1.2.0'
+DO_VERSION     = '~> 0.10.6'
+DM_DO_ADAPTERS = %w[ sqlite postgres mysql oracle sqlserver ]
+CURRENT_BRANCH = ENV.fetch('GIT_BRANCH', 'master')
+
+gem 'ardm-core', DM_VERSION,
+  SOURCE  => "#{DATAMAPPER}/ardm-core#{REPO_POSTFIX}",
+  :branch => CURRENT_BRANCH
+
+platforms :mri_18 do
+  group :quality do
+
+    gem 'rcov',      '~> 0.9.10'
+    gem 'yard',      '~> 0.7.2'
+    gem 'yardstick', '~> 0.4'
+
+  end
+end
+
+group :datamapper do
+
+  adapters = ENV['ADAPTER'] || ENV['ADAPTERS']
+  adapters = adapters.to_s.tr(',', ' ').split.uniq - %w[ in_memory ]
+
+  if (do_adapters = DM_DO_ADAPTERS & adapters).any?
+    do_options = {}
+    do_options[:git] = "#{DATAMAPPER}/do#{REPO_POSTFIX}" if ENV['DO_GIT'] == 'true'
+
+    gem 'data_objects', DO_VERSION, do_options.dup
+
+    do_adapters.each do |adapter|
+      adapter = 'sqlite3' if adapter == 'sqlite'
+      gem "do_#{adapter}", DO_VERSION, do_options.dup
+    end
+
+    gem 'ardm-do-adapter', DM_VERSION,
+      SOURCE  => "#{DATAMAPPER}/ardm-do-adapter#{REPO_POSTFIX}",
+      :branch => CURRENT_BRANCH
+  end
+
+  adapters.each do |adapter|
+    gem "ardm-#{adapter}-adapter", DM_VERSION,
+      SOURCE  => "#{DATAMAPPER}/ardm-#{adapter}-adapter#{REPO_POSTFIX}",
+      :branch => CURRENT_BRANCH
+  end
+
+  plugins = ENV['PLUGINS'] || ENV['PLUGIN']
+  plugins = plugins.to_s.tr(',', ' ').split.push('ardm-migrations').uniq
+
+  plugins.each do |plugin|
+    gem plugin, DM_VERSION,
+      SOURCE  => "#{DATAMAPPER}/#{plugin}#{REPO_POSTFIX}",
+      :branch => CURRENT_BRANCH
+  end
+
+end

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 David James
+
+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,102 @@
+= dm-is-state_machine
+
+DataMapper plugin that adds state machine functionality to your models.
+
+== Why is this plugin useful?
+
+Your DataMapper resource might benefit from a state machine if it:
+
+* has different "modes" of operation
+* has discrete behaviors
+* especially if the behaviors are mutually exclusive
+
+And you want a clean, high-level way of describing these modes / behaviors
+and how the resource moves between them.  This plugin allows you to
+declaratively describe the states and transitions involved.
+
+== Installation
+
+1. Download dm-more.
+2. Install dm-is-state_machine using the supplied rake files.
+
+== Setting up with Merb ##
+
+Add this line to your init.rb:
+
+  dependency "dm-is-state_machine"
+
+## Example DataMapper resource (i.e. model) ##
+
+  # /app/models/traffic_light.rb
+  class TrafficLight
+    include DataMapper::Resource
+
+    property :id, Serial
+
+    is :state_machine, :initial => :green, :column => :color do
+      state :green
+      state :yellow
+      state :red,    :enter => :red_hook
+      state :broken
+
+      event :forward do
+        transition :from => :green,  :to => :yellow
+        transition :from => :yellow, :to => :red
+        transition :from => :red,    :to => :green
+      end
+    end
+
+    def red_hook
+      # Do something
+    end
+  end
+
+== What this gives you
+
+=== Explained in words
+
+The above DSL (domain specific language) does these things "behind the scenes":
+
+1. Defines a DataMapper property called 'color'.
+
+2. Makes the current state available by using 'traffic_light.color'.
+
+3. Defines the 'forward!' transition method.  This method triggers the
+   appropriate transition based on the current state and comparing it against
+   the various :from states.  It will raise an error if you attempt to call
+   it with an invalid state (such as :broken, see above).  After the method
+   runs successfully, the state machine will be left in the :to state.
+
+=== Explained with some code examples
+
+    # Somewhere in your controller, perhaps
+    light = TrafficLight.new
+
+    # Move to the next state
+    light.forward!
+
+    # Do something based on the current state
+    case light.color
+    when "green"
+      # do something green-related
+    when "yellow"
+      # do something yellow-related
+    when "red"
+      # do something red-related
+    end
+
+== Specific examples
+
+We would also like to hear how *you* are using state machines in your code.
+
+== See also
+
+Here are some other projects you might want to look at.  Most of them
+are probably intended for ActiveRecord.  They take different approaches,
+which is pretty interesting.  If you find something you like in these other
+projects, let us know.  Maybe we can incorporate some of your favorite parts.
+That said, I do not want to create a Frankenstein. :)
+
+* http://github.com/pluginaweek/state_machine/tree/master
+* http://github.com/davidlee/stateful/tree/master
+* http://github.com/sbfaulkner/has_states/tree/master

data/Rakefile

@@ -0,0 +1,4 @@
+require 'rubygems'
+require 'rake'
+
+FileList['tasks/**/*.rake'].each { |task| import task }

data/ardm-is-state_machine.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/dm-is-state_machine/is/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.name          = 'ardm-is-state_machine'
+  gem.version       = DataMapper::Is::StateMachine::VERSION
+
+  gem.authors     = [ 'Martin Emde', 'David James' ]
+  gem.email       = [ 'me@martinemde.com', 'djwonk [a] collectiveinsight [d] net' ]
+  gem.summary     = 'Ardm fork of dm-is-state_machine'
+  gem.description = 'DataMapper plugin for creating state machines'
+  gem.homepage    = "https://github.com/ar-dm/ardm-is-state_machine"
+  gem.license     = 'MIT'
+
+  gem.files            = `git ls-files`.split("\n")
+  gem.test_files       = `git ls-files -- {spec}/*`.split("\n")
+  gem.extra_rdoc_files = %w[LICENSE README.rdoc]
+  gem.require_paths = [ "lib" ]
+
+  gem.add_runtime_dependency 'ardm-core', '~> 1.2'
+
+  gem.add_development_dependency 'rake',  '~> 0.9'
+  gem.add_development_dependency 'rspec', '~> 1.3'
+end

data/lib/ardm-is-state_machine.rb

@@ -0,0 +1 @@
+require 'dm-is-state_machine'

data/lib/dm-is-state_machine.rb

@@ -0,0 +1,10 @@
+require 'dm-core'
+
+require 'dm-is-state_machine/is/state_machine'
+require 'dm-is-state_machine/is/data/event'
+require 'dm-is-state_machine/is/data/machine'
+require 'dm-is-state_machine/is/data/state'
+require 'dm-is-state_machine/is/dsl/event_dsl'
+require 'dm-is-state_machine/is/dsl/state_dsl'
+
+DataMapper::Model.append_extensions DataMapper::Is::StateMachine

data/lib/dm-is-state_machine/is/data/event.rb

@@ -0,0 +1,25 @@
+module DataMapper
+  module Is
+    module StateMachine
+      module Data
+
+        class Event
+
+          attr_reader :name, :machine, :transitions
+
+          def initialize(name, machine)
+            @name        = name
+            @machine     = machine
+            @transitions = []
+          end
+
+          def add_transition(from, to)
+            @transitions << { :from => from, :to => to }
+          end
+
+        end
+
+      end # Data
+    end # StateMachine
+  end # Is
+end # DataMapper

data/lib/dm-is-state_machine/is/data/machine.rb

@@ -0,0 +1,90 @@
+module DataMapper
+  module Is
+    module StateMachine
+      module Data
+
+        # This Machine class represents one state machine.
+        #
+        # A model (i.e. a DataMapper resource) can have more than one Machine.
+        class Machine
+
+          # The property of the DM resource that will hold this Machine's
+          # state.
+          #
+          # TODO: change :column to :property
+          attr_accessor :column
+
+          # The initial value of this Machine's state
+          attr_accessor :initial
+
+          # The current value of this Machine's state
+          #
+          # This is the "primary control" of this Machine's state.  All
+          # other methods key off the value of @current_state_name.
+          attr_accessor :current_state_name
+
+          attr_accessor :events
+
+          attr_accessor :states
+
+          def initialize(column, initial)
+            @column, @initial   = column, initial
+            @events, @states    = [], []
+            @current_state_name = initial
+          end
+
+          # Fire (activate) the event with name +event_name+
+          #
+          # @api public
+          def fire_event(event_name, resource)
+            unless event = find_event(event_name)
+              raise InvalidEvent, "Could not find event (#{event_name.inspect})"
+            end
+            transition = event.transitions.find do |t|
+               t[:from].to_s == @current_state_name.to_s
+            end
+            unless transition
+              raise InvalidEvent, "Event (#{event_name.inspect}) does not" +
+              "exist for current state (#{@current_state_name.inspect})"
+            end
+
+            # == Run :exit hook (if present) ==
+            resource.run_hook_if_present current_state.options[:exit]
+
+            # == Change the current_state ==
+            @current_state_name = transition[:to]
+
+            # == Run :enter hook (if present) ==
+            resource.run_hook_if_present current_state.options[:enter]
+          end
+
+          # Return the current state
+          #
+          # @api public
+          def current_state
+            find_state(@current_state_name)
+            # TODO: add caching, i.e. with `@current_state ||= ...`
+          end
+
+          # Find event whose name is +event_name+
+          #
+          # @api semipublic
+          def find_event(event_name)
+            @events.find { |event| event.name.to_s == event_name.to_s }
+            # TODO: use a data structure that prevents duplicates
+          end
+
+          # Find state whose name is +event_name+
+          #
+          # @api semipublic
+          def find_state(state_name)
+            @states.find { |state| state.name.to_s == state_name.to_s }
+            # TODO: use a data structure that prevents duplicates
+          end
+
+        end
+
+      end # Data
+    end # StateMachine
+  end # Is
+end # DataMapper

data/lib/dm-is-state_machine/is/data/state.rb

@@ -0,0 +1,21 @@
+module DataMapper
+  module Is
+    module StateMachine
+      module Data
+
+        class State
+
+          attr_reader :name, :machine, :options
+
+          def initialize(name, machine, options = {})
+            @name    = name
+            @options = options
+            @machine = machine
+          end
+
+        end
+
+      end # Data
+    end # StateMachine
+  end # Is
+end # DataMapper

data/lib/dm-is-state_machine/is/dsl/event_dsl.rb

@@ -0,0 +1,81 @@
+module DataMapper
+  module Is
+    module StateMachine
+      # Event DSL (Domain Specific Language)
+      module EventDsl
+
+        # Define an event. This takes a block which describes all valid
+        # transitions for this event.
+        #
+        # Example:
+        #
+        #   class TrafficLight
+        #     include DataMapper::Resource
+        #     property :id, Serial
+        #     is :state_machine, :initial => :green, :column => :color do
+        #       # state definitions go here...
+        #
+        #       event :forward do
+        #         transition :from => :green,  :to => :yellow
+        #         transition :from => :yellow, :to => :red
+        #         transition :from => :red,    :to => :green
+        #       end
+        #     end
+        #   end
+        #
+        # +transition+ takes a hash where <tt>:to</tt> is the state to transition
+        # to and <tt>:from</tt> is a state (or Array of states) from which this
+        # event can be fired.
+        def event(name, &block)
+          unless state_machine_context?(:is)
+            raise InvalidContext, "Valid only in 'is :state_machine' block"
+          end
+
+          # ===== Setup context =====
+          machine = @is_state_machine[:machine]
+          event = Data::Event.new(name, machine)
+          machine.events << event
+          @is_state_machine[:event] = {
+            :name   => name,
+            :object => event
+          }
+          push_state_machine_context(:event)
+
+          # ===== Define methods =====
+          define_method("#{name}!") do
+            transition!(name)
+          end
+
+          # Possible alternative to the above:
+          # (class_eval is typically faster than define_method)
+          #
+          # self.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          #   def #{name}!
+          #     machine.current_state_name = __send__(:"#{column}")
+          #     machine.fire_event(name, self)
+          #     __send__(:"#{column}="), machine.current_state_name
+          #   end
+          # RUBY
+
+          yield if block_given?
+
+          # ===== Teardown context =====
+          pop_state_machine_context
+        end
+
+        def transition(options)
+          unless state_machine_context?(:event)
+            raise InvalidContext, "Valid only in 'event' block"
+          end
+          event_name   = @is_state_machine[:event][:name]
+          event_object = @is_state_machine[:event][:object]
+
+          from = options[:from]
+          to   = options[:to]
+          event_object.add_transition(from, to)
+        end
+
+      end # EventDsl
+    end # StateMachine
+  end # Is
+end # DataMapper