halorgium-dm-is-state_machine 0.10.2.via

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 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/lib/dm-is-state_machine.rb

@@ -0,0 +1,8 @@
+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, via)
+            @transitions << { :from => from, :to => to, :via => via }
+          end
+
+        end
+
+      end # Data
+    end # StateMachine
+  end # Is
+end # DataMapper

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

@@ -0,0 +1,142 @@
+module DataMapper
+  module Is
+    module StateMachine
+      module Data
+
+        class Machine
+          def initialize(definition, resource)
+            @definition = definition
+            @resource = resource
+          end
+
+          def run_initial
+            return unless initial
+            return unless initial_state = @definition.find_state(initial)
+            run_hook_if_present initial_state.options[:enter]
+          end
+
+          # hook may be either a Proc or symbol
+          def run_hook_if_present(hook)
+            return unless hook
+            if hook.respond_to?(:call)
+              hook.call(@resource)
+            else
+              @resource.__send__(hook)
+            end
+          end
+
+          def initial
+            @definition.initial
+          end
+
+          def find_event(event_name)
+            @definition.find_event(event_name)
+          end
+
+          def state?(state_name)
+            if @definition.find_state(state_name)
+              current_state_name == state_name.to_s
+            else
+              raise InvalidState.new("Invalid state: #{state_name.inspect}")
+            end
+          end
+
+          def fire_event(event_name)
+            transition = @definition.fire_event(event_name, current_state_name)
+
+            if via_state_name = transition[:via]
+              self.current_state_name = via_state_name
+            end
+
+            # == Change the current_state ==
+            self.current_state_name = transition[:to]
+          end
+
+          # Return the current state
+          #
+          # @api public
+          def current_state
+            @definition.find_state(current_state_name)
+            # TODO: add caching, i.e. with `@current_state ||= ...`
+          end
+
+          def current_state_name
+            @resource.attribute_get(@definition.column).to_s
+          end
+
+          def current_state_name=(state_name)
+            # == Run :exit hook (if present) ==
+            run_hook_if_present current_state.options[:exit]
+
+            @resource.update(@definition.column => state_name.to_s)
+
+            # == Run :enter hook (if present) ==
+            run_hook_if_present current_state.options[:enter]
+          end
+        end
+
+        # This Machine class represents one state machine.
+        #
+        # A model (i.e. a DataMapper resource) can have more than one Machine.
+        class MachineDefinition
+
+          # 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
+
+          attr_accessor :events
+
+          attr_accessor :states
+
+          def initialize(column, initial)
+            @column, @initial   = column, initial
+            @events, @states    = [], []
+          end
+
+          # Fire (activate) the event with name +event_name+
+          #
+          # @api public
+          def fire_event(event_name, current_state_name)
+            event_name = event_name.to_s
+            unless event = find_event(event_name)
+              raise InvalidEvent, "Could not find event (#{event_name.inspect})"
+            end
+            transition = event.transitions.find do |t|
+               Array(t[:from]).any? do |from_state|
+                 from_state.to_s == current_state_name
+               end
+            end
+            unless transition
+              raise InvalidEvent, "Event (#{event_name.inspect}) does not " +
+              "exist for current state (#{current_state_name.inspect})"
+            end
+            transition
+          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,110 @@
+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
+
+          if method_defined?("#{name}!")
+            raise InvalidEvent, "There is a method called #{name}! on #{self}"
+          end
+
+          event_object = create_event(name)
+
+          # ===== Setup context =====
+          @is_state_machine[:event] = {
+            :name   => name,
+            :object => event_object
+          }
+          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 destroy(options)
+          unless state_machine_context?(:is)
+            raise InvalidContext, "Valid only in 'is :state_machine' block"
+          end
+
+          event_object = create_event(:destroy)
+          from = options[:from]
+          to   = options[:to]
+          via  = options[:via]
+          event_object.add_transition(from, to, via)
+        end
+
+        def create_event(name)
+          unless state_machine_context?(:is)
+            raise InvalidContext, "Valid only in 'is :state_machine' block"
+          end
+
+          name = name.to_s
+
+          definition = @is_state_machine[:definition]
+          event = Data::Event.new(name, definition)
+          definition.events << event
+          event
+        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]
+          via  = options[:via]
+          event_object.add_transition(from, to, via)
+        end
+
+      end # EventDsl
+    end # StateMachine
+  end # Is
+end # DataMapper

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

@@ -0,0 +1,40 @@
+module DataMapper
+  module Is
+    module StateMachine
+      # State DSL (Domain Specific Language)
+      module StateDsl
+
+        # Define a state of the system.
+        #
+        # Example:
+        #
+        #   class TrafficLight
+        #     include DataMapper::Resource
+        #     property :id, Serial
+        #     is :state_machine do
+        #       state :green,  :enter => Proc.new { |o| o.log("G") }
+        #       state :yellow, :enter => Proc.new { |o| o.log("Y") }
+        #       state :red,    :enter => Proc.new { |o| o.log("R") }
+        #
+        #       # event definitions go here...
+        #     end
+        #
+        #     def log(string)
+        #       Merb::Logger.info(string)
+        #     end
+        #   end
+        def state(name, options = {})
+          unless state_machine_context?(:is)
+            raise InvalidContext, "Valid only in 'is :state_machine' block"
+          end
+
+          # ===== Setup context =====
+          definition = @is_state_machine[:definition]
+          state = Data::State.new(name, definition, options)
+          definition.states << state
+        end
+
+      end # StateDsl
+    end # StateMachine
+  end # Is
+end # DataMapper

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

@@ -0,0 +1,126 @@
+module DataMapper
+  module Is
+    module StateMachine
+
+      class InvalidContext  < RuntimeError; end
+      class InvalidState    < RuntimeError; end
+      class InvalidEvent    < RuntimeError; end
+      class EventConfusion  < RuntimeError; end
+      class DuplicateStates < RuntimeError; end
+      class NoInitialState  < RuntimeError; end
+
+      ##
+      # Makes a column ('state' by default) act as a state machine. It will
+      # define the property if it does not exist.
+      #
+      # @example [Usage]
+      #   is :state_machine
+      #   is :state_machine, :initial => :internal
+      #   is :state_machine, :column => :availability
+      #   is :state_machine, :column => :availability, :initial => :external
+      #
+      # @param options<Hash> a hash of options
+      #
+      # @option :column<Symbol> the name of the custom column
+      #
+      def is_state_machine(options = {}, &block)
+        extend DataMapper::Is::StateMachine::EventDsl
+        extend DataMapper::Is::StateMachine::StateDsl
+        include DataMapper::Is::StateMachine::InstanceMethods
+
+        # ===== Setup context =====
+        options = { :column => :state, :initial => nil }.merge(options)
+        column  = options[:column]
+        initial = options[:initial].to_s
+        unless properties.detect { |p| p.name == column }
+          property column, String, :default => initial
+        end
+        definition = Data::MachineDefinition.new(column, initial)
+        @is_state_machine = { :definition => definition }
+
+        class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def #{column}=(value)
+            value = value.to_s if value.kind_of?(Symbol)
+            attribute_set(#{column.inspect}, value)
+          end
+        RUBY
+
+        # ===== Define callbacks =====
+        # TODO: define callbacks
+        # before :save do
+        #   if self.new_record?
+        #     # ...
+        #   else
+        #     # ...
+        #   end
+        # end
+
+        before :destroy do
+          if state_machine.find_event(:destroy)
+            transition!(:destroy)
+          end
+        end
+
+        # ===== Setup context =====
+        push_state_machine_context(:is)
+
+        yield if block_given?
+
+        # ===== Teardown context =====
+        pop_state_machine_context
+      end
+
+      protected
+
+      def push_state_machine_context(label)
+        @is_state_machine ||= {}
+        @is_state_machine[:context] ||= []
+        @is_state_machine[:context] << label
+
+        # Compacted, but barely readable for humans
+        # ((@is_state_machine ||= {})[:context] ||= []) << label
+      end
+
+      def pop_state_machine_context
+        @is_state_machine[:context].pop
+      end
+
+      def state_machine_context?(label)
+        (i = @is_state_machine) && (c = i[:context]) &&
+        c.respond_to?(:include?) && c.include?(label)
+      end
+
+      module InstanceMethods
+
+        def initialize(*args)
+          super
+          # ===== Run :enter hook if present =====
+          state_machine.run_initial
+        end
+
+        def transition!(event_name)
+          state_machine.fire_event(event_name)
+        end
+
+        def state?(state_name)
+          state_machine.state?(state_name)
+        end
+
+        def state_machine
+          return unless is_sm = model.instance_variable_get(:@is_state_machine)
+          return unless definition = is_sm[:definition]
+          Data::Machine.new(definition, self)
+        end
+
+      end # InstanceMethods
+
+    end # StateMachine
+  end # Is
+end # DataMapper
+
+# Notes
+# -----
+#
+# Since this gets mixed into a class, I try to keep the namespace pollution
+# down to a minimum.  This is why I only use the @is_state_machine instance
+# variable.

metadata

@@ -0,0 +1,124 @@
+--- !ruby/object:Gem::Specification 
+name: halorgium-dm-is-state_machine
+version: !ruby/object:Gem::Version 
+  hash: 1012425149
+  prerelease: 7
+  segments: 
+  - 0
+  - 10
+  - 2
+  - via
+  version: 0.10.2.via
+platform: ruby
+authors: 
+- David James
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-12-11 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: dm-core
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 51
+        segments: 
+        - 0
+        - 10
+        - 2
+        version: 0.10.2
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 13
+        segments: 
+        - 1
+        - 2
+        - 9
+        version: 1.2.9
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 15
+        segments: 
+        - 0
+        - 4
+        - 0
+        version: 0.4.0
+  type: :development
+  version_requirements: *id003
+description: DataMapper plugin for creating state machines
+email: djwonk [a] collectiveinsight [d] net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- lib/dm-is-state_machine.rb
+- lib/dm-is-state_machine/is/data/event.rb
+- lib/dm-is-state_machine/is/data/machine.rb
+- lib/dm-is-state_machine/is/data/state.rb
+- lib/dm-is-state_machine/is/dsl/event_dsl.rb
+- lib/dm-is-state_machine/is/dsl/state_dsl.rb
+- lib/dm-is-state_machine/is/state_machine.rb
+- LICENSE
+- README.rdoc
+has_rdoc: true
+homepage: http://github.com/halorgium/dm-is-state_machine/tree/via
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+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 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: datamapper
+rubygems_version: 1.5.0
+signing_key: 
+specification_version: 3
+summary: DataMapper plugin for creating state machines
+test_files: []
+