ex_machina 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 65774af491192a74ddda0683c63af42d4de122a1
-  data.tar.gz: 8e22de0cc6d23b9d20dc755e3dbab298efd2a9e4
+  metadata.gz: bc8cb9dc7e92353478947c8c9a88c166b5c02061
+  data.tar.gz: b612897d0b21304de584ea98a3801d6e7a76ea35
 SHA512:
-  metadata.gz: e50f7e90615c99ef72b6bddfecffdfcfc4df135d8f550ff0656092e1398eec8fc975c725a7110204c19e7294c134be5724273d26c2ba3c5c11c0c54932bce341
-  data.tar.gz: 77e6132fe89cb046378a284e77147529fbf5114c71a99e3f07a3a9e3b6b51e4c646c290023fd5a30b44c7ba9dd216f1757a22fa7ed62c6426e746f923f6f7083
+  metadata.gz: 25b5ef8875fb3de5cf84bc7d1ae856c1345cae080deef13a3d04442be5106154aaf915b3682846876323b5fd229ecbe81002d5653637be037d98a198f10dc057
+  data.tar.gz: e60ebe4a9de753d450a408b00302771c333e044df90d76c6305ced6d9a8b46a9303ede4086456a55afc5a3ba91c0d907d923bcc241df986f487e0ba8b13cc31d

data/.gitignore

@@ -7,3 +7,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+*.gem

data/README.md

@@ -1,8 +1,15 @@
+[![wercker status](https://app.wercker.com/status/32429e43b793f95c450ddd2a89efdb21/s/master "wercker status")](https://app.wercker.com/project/bykey/32429e43b793f95c450ddd2a89efdb21)
+
 # ExMachina
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/ex_machina`. To experiment with that code, run `bin/console` for an interactive prompt.
+A simple implementation of [Finine-state machine](https://en.wikipedia.org/wiki/Finite-state_machine) using OOP following the principles:
+
+- Machine: a set of status, events and transitions
+- Status: the state of a machine
+- Event: a action performed on each status
+- Transition: the graph of status for a given event
 
-TODO: Delete this and the text above, and describe your gem
+The *machine* is declared on target class that knowns the possible *status* and *events*. Each event should be implemented on its own class, where the *transitions* are declared too. ExMachina manages the flow, execution and transitions of each event and status.
 
 ## Installation
 
@@ -22,7 +29,78 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Include the `ExMachina::Machine` on target object and define the status and events calling `has_status` and `has_events` respectively:
+
+Here a classic example of a state machine of an Engine, which have too events: start and stop:
+
+```ruby
+class Engine
+  include ExMachina::Machine
+
+  has_status [:stopped, :running]
+  has_events Engine::Start, Engine::Stop
+
+  attr_accessor :status, :fuel
+  def initialize(status = "stopped", fuel = 10)
+    @status, @fuel = satus, fuel
+  end
+end
+```
+
+And implement each event on its own class. Here was made on subclasses:
+
+```ruby
+class Engine::Start
+  include ExMachina::Event
+
+  transition from: :stopped, to: :running, if: :has_fuel?, after: :consumes_fuel
+
+  def has_fuel?
+    context.fuel > 0
+  end
+
+  def perform(execution)
+    # do something here
+
+    execution.success!
+  end
+
+  def consumes_fuel
+    context.fuel -= 1
+  end
+end
+
+class Engine::Stop
+  include ExMachina::Event
+
+  transition from: :running, to: :stopped
+end
+```
+
+Here is an usage example:
+
+```ruby
+engine = Engine.new     # => #<Engine:0x007fb77c065758>
+engine.status           # "stopped" 
+engine.fuel             # 10
+
+engine.can_start?       # true
+engine.start            # true
+engine.status           # "running"
+
+engine.running?         # true
+engine.start            # false
+engine.errors           # ["No transitions defined from 'running' status"]
+
+engine.stop             # true
+engine.status           # "stopped"
+engine.stopped?         # true
+engine.fuel             # 9
+
+engine.fuel = 0         # 0
+engine.can_start?       # false
+engine.start            # false
+```
 
 ## Development
 
@@ -34,8 +112,6 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/ex_machina. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-

data/lib/ex_machina/adapter/active_record.rb

@@ -0,0 +1,13 @@
+module ExMachina
+  module Adapter
+    module ActiveRecord
+      def within_transaction(&block)
+        raise NotImplementedError, "not supported yet"
+      end
+
+      def persist(model)
+        model.save
+      end
+    end
+  end
+end

data/lib/ex_machina/adapter/memory.rb

@@ -0,0 +1,13 @@
+module ExMachina
+  module Adapter
+    module Memory
+      def within_transaction(&block)
+        block.call
+      end
+
+      def persist(model)
+        # do nothing
+      end
+    end
+  end
+end

data/lib/ex_machina/adapter/sequel.rb

@@ -0,0 +1,13 @@
+module ExMachina
+  module Adapter
+    module Sequel
+      def within_transaction(&block)
+        DB.transaction(&block)
+      end
+
+      def persist(model)
+        model.save
+      end
+    end
+  end
+end

data/lib/ex_machina/adapter.rb

@@ -0,0 +1,18 @@
+require "ex_machina/adapter/memory"
+require "ex_machina/adapter/sequel"
+require "ex_machina/adapter/active_record"
+
+module ExMachina
+  module Adapter
+    def self.included(base)
+      if defined?(::Sequel)
+        base.include Adapter::Sequel
+      elsif defined?(::ActiveRecord)
+        base.include Adapter::ActiveRecord
+      else
+        base.include Adapter::Memory
+      end
+    end
+  end
+end
+

data/lib/ex_machina/event/{runner.rb → execution.rb}

@@ -1,6 +1,6 @@
 module ExMachina
   module Event
-    class Runner
+    class Execution
 
       STATUSES = [
         SUCCESS = :success,
@@ -86,8 +86,11 @@ module ExMachina
 
       def eligible?
         if transition.conditional?
-          invoke(event, transition.do_if, self) ||
-            invoke(event, transition.do_unless, self)
+          if transition.do_if
+            invoke(transition.do_if)
+          elsif transition.do_unless
+            !invoke(transition.do_unless)
+          end
         else
           true
         end
@@ -98,41 +101,29 @@ module ExMachina
 
         return skipped! unless eligible?
 
-        invoke(event, transition.do_before, self)
+        invoke(transition.do_before)
         begin
-          call = invoke(event, :call, self)
-          invoke(event, transition.do_after, self)
+          call = invoke(:perform)
+          invoke(transition.do_after)
           finish!(call)
         rescue StandardError => ex
           error!(ex)
         end
 
         if success?
-          invoke(event, :change_status, self)
-          invoke(event, transition.do_success, self)
+          invoke(:transit)
+          invoke(transition.do_success)
         elsif failure?
-          invoke(event, transition.do_failure, self)
+          invoke(transition.do_failure)
         end
 
         call
       end
 
-      def invoke(context, meth, *args)
-        return if meth.nil?
+      protected
 
-        if meth.respond_to?(:call)
-          all_args    = Array([context, *args])
-          meth_params = meth.parameters
-          meth_args   = *all_args.first(meth_params.size)
-
-          meth.call(*meth_args)
-
-        elsif context.respond_to?(meth)
-          meth_params = context.method(meth).parameters
-          meth_args   = *args.first(meth_params.size)
-
-          context.send(meth, *meth_args)
-        end
+      def invoke(meth, arg = self)
+        Util.invoke_method(event, meth, arg)
       end
     end
   end

data/lib/ex_machina/event/transition.rb

@@ -5,8 +5,6 @@ module ExMachina
       attr_reader :from, :to
       attr_reader :do_if, :do_unless, :do_before, :do_after, :do_success, :do_failure
 
-      attr_accessor :previous, :current, :context, :result
-
       def initialize(options)
         @from    = Array(options.fetch(:from)).map { |status| normalize(status) }
         @to      = normalize(options.fetch(:to))

data/lib/ex_machina/event.rb

@@ -1,13 +1,15 @@
 require "ex_machina/event/transition"
-require "ex_machina/event/runner"
+require "ex_machina/event/execution"
 require "ex_machina/event/validations"
+require "ex_machina/adapter"
 
 module ExMachina
   module Event
     def self.included(base)
-      base.extend(ClassMethods)
-      base.include(InstanceMethods)
-      base.include(Validations)
+      base.extend  ClassMethods
+      base.include InstanceMethods
+      base.include Validations
+      base.include Adapter
     end
 
     module ClassMethods
@@ -27,7 +29,7 @@ module ExMachina
         self.new(context).can_fire?
       end
       def event
-        self.name.demodulize.underscore
+        @event ||= Util::String.new(self.name).demodulize.underscore
       end
     end
 
@@ -38,31 +40,40 @@ module ExMachina
         @context = context
       end
 
+      # Available transitions
       def transitions
         self.class
           .transitions
           .select { |transition| transition.from?(status) }
       end
 
+      # The context current status
       def status
         context.status
       end
 
-      def change_status(execution)
+      # Called on event success
+      def transit(execution)
         context.status = execution.current.to_s
-        context.save
+        persist(context)
+      end
+
+      # Override this method on event implementation
+      def perform
+        true
       end
 
       def fire
         validate
-        return unless can_fire?
+        return false unless can_fire?
 
         result = false
         within_transaction do
           transitions.each do |transition|
-            runner = Runner.new(self, transition)
-            result = runner.run
+            runner = Execution.new(self, transition)
+            runner.run
 
+            result = runner.success?
             break result unless runner.skipped?
           end
         end
@@ -79,14 +90,6 @@ module ExMachina
         valid?
       end
 
-      def call
-        raise NotImplementedError, "method 'call' must be implemented on event class"
-      end
-
-      def within_transaction(&block)
-        # TODO implement strategy for transaction
-        DB.transaction(&block)
-      end
     end
   end
 end

data/lib/ex_machina/{eventable.rb → machine.rb}

@@ -1,7 +1,7 @@
 module ExMachina
-  module Eventable
+  module Machine
     def self.included(base)
-      base.extend ClassMethods
+      base.extend  ClassMethods
       base.include InstanceMethods
     end
 

data/lib/ex_machina/util.rb

@@ -0,0 +1,39 @@
+module ExMachina
+  module Util
+    class String < ::String
+      # Convert 'MyModule::MyClass' to 'MyClass'
+      def demodulize
+        self.split("::").last
+      end
+
+      # Convert 'MyClass' to 'my_class'
+      def underscore
+        self
+          .gsub("::", "/")
+          .gsub(/(^[A-Z])/) { |match| "#{match.downcase}" }
+          .gsub(/([A-Z])/) { |match| "_#{match.downcase}" }
+      end
+    end
+
+    extend self
+
+    # Invoke method or lambda on given context passing correspondent args
+    def invoke_method(context, meth, *args)
+      return if meth.nil?
+
+      if meth.respond_to?(:call)
+        all_args    = Array([context, *args])
+        meth_params = meth.parameters
+        meth_args   = *all_args.first(meth_params.size)
+
+        meth.call(*meth_args)
+
+      elsif context.respond_to?(meth)
+        meth_params = context.method(meth).parameters
+        meth_args   = *args.first(meth_params.size)
+
+        context.send(meth, *meth_args)
+      end
+    end
+  end
+end

data/lib/ex_machina/version.rb

@@ -1,3 +1,3 @@
 module ExMachina
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/ex_machina.rb

@@ -1,6 +1,8 @@
 require "ex_machina/version"
+require "ex_machina/util"
+require "ex_machina/machine"
 require "ex_machina/event"
-require "ex_machina/eventable"
+require "ex_machina/adapter"
 
 module ExMachina
 end

data/wercker.yml

@@ -0,0 +1,7 @@
+box: ruby:2.3.0
+build:
+    steps:
+        - bundle-install
+        - script:
+            name: rspec
+            code: bundle exec rspec

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ex_machina
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Rodrigo Panachi
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-03-05 00:00:00.000000000 Z
+date: 2016-03-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -69,12 +69,18 @@ files:
 - bin/setup
 - ex_machina.gemspec
 - lib/ex_machina.rb
+- lib/ex_machina/adapter.rb
+- lib/ex_machina/adapter/active_record.rb
+- lib/ex_machina/adapter/memory.rb
+- lib/ex_machina/adapter/sequel.rb
 - lib/ex_machina/event.rb
-- lib/ex_machina/event/runner.rb
+- lib/ex_machina/event/execution.rb
 - lib/ex_machina/event/transition.rb
 - lib/ex_machina/event/validations.rb
-- lib/ex_machina/eventable.rb
+- lib/ex_machina/machine.rb
+- lib/ex_machina/util.rb
 - lib/ex_machina/version.rb
+- wercker.yml
 homepage: https://github.com/rpanachi/ex_machina
 licenses:
 - MIT