just_state_machine 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ffaec8272814487f36a006b35a7fb4ba9d03e212
-  data.tar.gz: 9e6c7df7b81ee6e55d79f47c9a8e44ac36234df1
+  metadata.gz: b8088d7c136243526d1a99b0353c9b5068efb6e3
+  data.tar.gz: f88ff999ee19e0c5fa41516999fe1a8e5fcd2f6d
 SHA512:
-  metadata.gz: a8f00e1451d1fb713f8000027239c1de502093bb658be3ee7a2c1106103b39b4573053ae88445e4e399a9f2b1b5e455c9b95f789ac498d5e5e32a02253ad7dc0
-  data.tar.gz: dd327c2a4857e9b2795ac11dbb081d31f2da958fa17ce0bcfb2de68288edb7936ccb39a666294ffc2b6bae79b2c8917f5768d990d421c1b79101a7f68104ae3d
+  metadata.gz: b1200277a06f2a0da8313ff057f5237dfa71f1a3a6d5c4064ca7f9303cb655b44e545b8dc10e704b88b45b93742fdef3f498d206ab4c0fd73beaef57646d45b9
+  data.tar.gz: 1cd99d024ea0f880460e103ed6c8b8f0f0f3c3ad91d3fa4db37cca3672c217679c6327bdafa39677c0526380d6b9bf22a442c189e53de74a4890b884333c5e80

data/README.md

@@ -148,6 +148,19 @@ class UserStateMachine < Jsm::Base
     transition from: :intermediate, to: :beginner
     transition from: :master, to: :intermediate
   end
+
+
+  before :upgrade_title do |user|
+    user.name = 'before'
+  end
+
+  after :upgrade_title do |result, user|
+    if result
+      user.name += ' after success'
+    else
+      user.name += 'after failed'
+    end
+  end
 end
 
 # Client Class
@@ -155,7 +168,7 @@ class User
   include Jsm::Client
   jsm_use UserStateMachine # your state machine class here
 
-  attr_accessor :title # same with attribute_name in UserStateMachine
+  attr_accessor :title, :name # same with attribute_name in UserStateMachine
   def initialize
 	  @title = :beginner
 	  @level = 1
@@ -177,6 +190,62 @@ transition from: :intermediate, to: :beginner #one `from` states
 transition from: [:intermediate, :master], to: :beginner #multiple `from` states
 ```
 What above code means for multiple `from` states is the current state either `:intermediate` or `:master`, transform it into `:beginner` state
+
+### Callbacks
+`Jsm` now support callbacks. It provide 2 API: `before` and `after`. basically `before` callbacks is run before do event. Meanwhile, after callbacks is run after event. For **note**, after event first argument is `result` of the event
+```ruby
+class UserStateMachine < Jsm::Base
+  attribute_name :level
+
+  state :beginner
+  state :intermediate
+  state :master
+
+  event :upgrade_title do
+    transition from: [:beginner], to: :intermediate
+    transition from: [:intermediate], to: :master
+  end
+
+  event :downgrade_title do
+    transition from: :intermediate, to: :beginner
+    transition from: :master, to: :intermediate
+  end
+
+  before :upgrade_title do |user|
+    user.name = 'before'
+  end
+
+  after :upgrade_title do |result, user| # the first parameters is result of the event
+    if result
+      # execute if transition in event is success
+      user.name += ' after success'
+    else
+      # execute if transition in event is failed
+      user.name += 'after failed'
+    end
+  end
+end
+
+# Client Class
+class User
+  include Jsm::Client
+  jsm_use UserStateMachine # your state machine class here
+
+  attr_accessor :title, :name # same with attribute_name in UserStateMachine
+  def initialize
+	  @title = :beginner
+	  @level = 1
+  end
+  #your code here
+end
+
+user = User.new
+user.title # :beginner
+user.name # nil
+user.upgrade_title # true(it still return the original return value of the event)
+user.name # before after success
+```
+
 ## Active Model Integration
 ```ruby
 class UserStateMachine < Jsm::Base
@@ -231,7 +300,7 @@ end
 
 ### Validation
 It also support validation from `ActiveModel` . Validation checked based on `errors` value in the `instance`. you can add an error to the errors object. This will prevent the state from being changed
-```
+```ruby
 user = User.new
 user.level # 1
 user.level = 18
@@ -288,6 +357,44 @@ end
 ```
 `Jsm`  support `ActiveRecord`. In the `client` class include the `Jsm::Client::ActiveRecord`.  It also support `ActiveRecord` Validation. The behavior is same with `ActiveModel` client.
 
+## StateMachine Visualization
+When you want to visualize the state machine that has been defined. You can use the `Jsm::Drawer:Graphviz`. Basically it will generate an url for images of states diagram with theirs events. Basically the image is generated by `google chart`. They provide a really good API to generate state diagram.
+
+```ruby
+class UserStateMachine < Jsm::Base
+  attribute_name :relationship
+
+  state :single, initial: true
+  state :in_relationship
+  state :married
+  state :divorced
+  state :widowed
+
+  event :start_dating do
+    transition from: :single, to: :in_relationship
+  end
+
+  event :marry do
+    transition from: [:single, :in_relationship], to: :married
+  end
+
+  event :cheating do
+    transition from: :in_relationship, to: :single
+    transition from: :married, to: :divorced
+  end
+
+  event :divorce do
+    transition from: :married, to: :divorced
+  end
+end
+
+Jsm::Drawer::Graphviz.generate_url(UserStateMachine) #the arguments is class name
+```
+the result will be:
+
+![image](https://chart.googleapis.com/chart?cht=gv&chl=digraph{single-%3Ein_relationship[label=start_dating];single-%3Emarried[label=marry];in_relationship-%3Emarried[label=marry];in_relationship-%3Esingle[label=cheating];married-%3Edivorced[label=cheating];married-%3Edivorced[label=divorce]})
+
+[source]( https://chart.googleapis.com/chart?cht=gv&chl=digraph{single-%3Ein_relationship[label=start_dating];single-%3Emarried[label=marry];in_relationship-%3Emarried[label=marry];in_relationship-%3Esingle[label=cheating];married-%3Edivorced[label=cheating];married-%3Edivorced[label=divorce]}Â)
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/examples/active_record_state_machine.rb

@@ -25,6 +25,14 @@ class ActiveRecordSM < Jsm::Base
     transition from: "married", to: "divorced"
   end
 
+  before :marry do |user|
+    user.name = 'testBefore'
+  end
+
+  after :marry do |result, user|
+    user.name = ' testAfter'
+  end
+
   validate "married" do |user|
     unless user.approved_by_parents
       user.errors.add(:approved_by_parents, 'can not marry, you havent been approved')

data/examples/simple_state_machine.rb

@@ -23,6 +23,14 @@ class UserStateMachine < Jsm::Base
   event :divorce do
     transition from: :married, to: :divorced
   end
+
+  before :marry do |obj|
+    obj.name = 'testBefore'
+  end
+
+  after :marry do |result, obj|
+    obj.name += ' testAfterthis'
+  end
 end
 
 
@@ -30,7 +38,7 @@ class UserBasic
   include Jsm::Client
   jsm_use UserStateMachine
 
-  attr_accessor :relationship
+  attr_accessor :relationship, :name
   def initialize(relationship = nil)
     @relationship = relationship
   end

data/lib/jsm.rb

@@ -3,21 +3,27 @@ module Jsm
   require "jsm/states"
   require "jsm/event"
   require "jsm/exceptions"
-  require "jsm/machines"
+  module EventExecutor
+    require "jsm/event_executor/base"
+    require "jsm/event_executor/active_model"
+    require "jsm/event_executor/active_record"
+  end
+
+  require "jsm/callbacks"
+  module Callbacks
+    require 'jsm/callbacks/callback'
+    require "jsm/callbacks/chain"
+    require "jsm/callbacks/chain_collection"
+  end
   require "jsm/base"
   require "jsm/client"
   require "jsm/client/active_model"
   require "jsm/client/active_record"
+  require "jsm/machines"
   require "jsm/client_extension"
   require "jsm/validator"
   require "jsm/validators"
 
-  module EventExecutor
-    require "jsm/event_executor/base"
-    require "jsm/event_executor/active_model"
-    require "jsm/event_executor/active_record"
-  end
-
   module Drawer
     require "jsm/drawer/node"
     require "jsm/drawer/digraph"

data/lib/jsm/base.rb

@@ -1,7 +1,7 @@
 # this module used as extension for state machine class
 # The DSL is built to define the state, event, and transition that happen
 class Jsm::Base
-
+  include Jsm::Callbacks
   # define attribute name of state attribute in the client class
   def self.attribute_name(attribute_name = nil)
     if attribute_name.nil?
@@ -67,13 +67,18 @@ class Jsm::Base
       raise Jsm::InvalidStateError, "there is no state y"
     end
 
-    @validators ||= Jsm::Validators.new
-    @validators.add_validator(state_name, Jsm::Validator.new(:state, state_name, &block))
+    validators.add_validator(state_name, Jsm::Validator.new(:state, state_name, &block))
   end
 
   # list all validators that exist
   def self.validators
-    @validators
+    @validators ||= Jsm::Validators.new
+  end
+  # set a before callback for an event
+  def self.pre_before(event_name, &block)
+    if !events[event_name]
+      raise Jsm::InvalidEventError, "event #{event_name} has not been registered"
+    end
   end
 
   def initialize(klass)

data/lib/jsm/callbacks.rb

@@ -0,0 +1,38 @@
+module ::Jsm::Callbacks
+  def self.included(base)
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+    def jsm_callbacks
+      @jsm_callbacks ||= Jsm::Callbacks::ChainCollection.new(self)
+    end
+    #override this to do something before method `before`
+    def pre_before(context, &block)
+    end
+
+    #override this to do something before method `after`
+    def pre_after(context, &block)
+    end
+
+    # this method is to register a `before callback` to a jsm_callbacks
+    def before(context, &block)
+
+      pre_before(context, &block)
+      callback = Jsm::Callbacks::Callback.new(:before, &block)
+      jsm_callbacks[context] ||= Jsm::Callbacks::Chain.new(context)
+      jsm_callbacks[context].insert_callback(callback)
+    end
+
+    # this method is to register a `after callback` to a jsm_callbacks
+    def after(context, &block)
+      pre_after(context, &block)
+      callback = Jsm::Callbacks::Callback.new(:after, &block)
+      self.jsm_callbacks[context].insert_callback(callback)
+    end
+
+    def run_callback(context, *args, &block)
+      self.jsm_callbacks[context].compile(*args, &block)
+    end
+  end
+end

data/lib/jsm/callbacks/callback.rb

@@ -0,0 +1,25 @@
+# the purpose of this class is to store the block that will be used as callback
+# e.g:
+# Jsm::Callbacks::Callback.new(:before) do
+#   put 'me awesome'
+# end
+
+class Jsm::Callbacks::Callback
+  FILTER_TYPES = [:before, :after]
+  attr_reader :filter_type
+
+  # the allowed filter_type: :before, :after
+  def initialize(filter_type, &block)
+    if FILTER_TYPES.include?(filter_type)
+      @filter_type = filter_type
+    else
+      raise ArgumentError, "invalid type #{filter_type}, allowed: #{FILTER_TYPES.join(', ')}"
+    end
+    @block = block
+  end
+
+  # run callback
+  def execute(*obj)
+    @block.call(*obj)
+  end
+end

data/lib/jsm/callbacks/chain.rb

@@ -0,0 +1,54 @@
+# chain is a repository to store list of callbacks of an event, for example
+# store before and after callback of an event called `run`
+# e.g:
+# before_callback =  Jsm::Callbacks::Callback.new(:before) do |user|
+# log.info('before callback')
+# end
+# before_callback2 =  Jsm::Callbacks::Callback.new(:before) do |user|
+#  user.age = 20
+# end
+# after_callback =  Jsm::Callbacks::Callback.new(:after) do |result, user|
+#  log.info('after callback')
+# end
+# chain = Jsm::Callbacks::Chain.new(:run)
+# chain.insert_callback(before_callback)
+# chain.insert_callback(before_callback2)
+# chain.insert_callback(after_callback)
+# user = User.new
+# result = chain.compile user do |user|
+#  user.address = 'Indonesia'
+# end
+# result -> true
+# log -> before callback after callback
+# user.address -> 'Indonesia'
+
+class Jsm::Callbacks::Chain
+  attr_reader :context, :callbacks
+  FILTER_TYPES_POSITION = [:before, :after]
+  def initialize(context)
+    @context = context
+    @callbacks = []
+  end
+
+  def insert_callback(callback)
+    @callbacks.push(callback)
+  end
+
+  def compile(*args, &block)
+    arrange_callbacks(*args, &block)
+  end
+
+  private
+  #run callbacks from before, given block then after callback
+  # the return value is the original given block result
+  # before callback get arguments from *args
+  # after callback get result of block execution and *args
+  def arrange_callbacks(*args, &block)
+    before = @callbacks.select { |callback| callback.filter_type == :before }
+    after = @callbacks.select { |callback| callback.filter_type == :after }
+    before.each {|callback| callback.execute(*args) }
+    return_value = block.call(*args)
+    after.each { |callback| callback.execute(return_value, *args) }
+    return_value
+  end
+end

data/lib/jsm/callbacks/chain_collection.rb

@@ -0,0 +1,15 @@
+# collection of chain
+class Jsm::Callbacks::ChainCollection
+  def initialize(klass)
+    @klass = klass
+    @chains = {}
+  end
+
+  def add_chain(context,chain)
+    @chains[context] = chain
+  end
+
+  def [](context)
+    @chains[context] ||= Jsm::Callbacks::Chain.new(context)
+  end
+end

data/lib/jsm/client_extension.rb

@@ -8,10 +8,11 @@ class Jsm::ClientExtension
   end
 
   attr_reader :klass, :state_machine, :event_executor
+  # @param options with options state_machine. It contain state_machine class( class inherited from Jsm::Base)
   def initialize(klass, params = {})
     @klass = klass
     @state_machine = params[:state_machine]
-    @event_executor = klass.jsm_event_executor.new(validators: @state_machine.validators)
+    @event_executor = klass.jsm_event_executor.new(state_machine: @state_machine)
     unless @state_machine.attribute_name
       raise Jsm::NoAttributeError, "please assign the attribute_name first in class #{@state_machine.name}"
     end

data/lib/jsm/event_executor/active_record.rb

@@ -1,5 +1,5 @@
 class Jsm::EventExecutor::ActiveRecord < Jsm::EventExecutor::ActiveModel
-  def execute(event, obj)
+  def execute_action(event, obj)
     if can_be_executed?(event, obj)
       result = false
       # do transaction to prevent shit happen

data/lib/jsm/event_executor/base.rb

@@ -1,16 +1,21 @@
 # this class is the base for adapter
 # it can be extended for ActiveRecord adapter
 class Jsm::EventExecutor::Base
-  attr_reader :validators
+  attr_reader :validators, :state_machine
   def initialize(params = {})
-    @validators = params[:validators] || Jsm::Validators.new
+    @state_machine = params[:state_machine]
+    @validators = @state_machine.validators
+
   end
 
   # it execute event for the object.
   # If transition failed or invalid by validation toward the object,
   # then it will return false
+  # it also run callbacks of the event
   def execute(event, obj)
-    can_be_executed?(event, obj) ? event.execute(obj) : false
+    state_machine.run_callback event.name, obj do |obj|
+      execute_action(event, obj)
+    end
   end
 
   # check if the obj possible to execute the event(passed the validation and can do transition)
@@ -20,10 +25,19 @@ class Jsm::EventExecutor::Base
   end
 
   # same with execute, but if its failed raise error
+  # it also run callbacks of the event
+  # however after callbacks only run when success because if its failed will raise error
   def execute!(event, obj)
-    unless execute(event, obj)
-      raise Jsm::IllegalTransitionError, "there is no matching transitions or invalid, Cant do event #{event.name}"
+    state_machine.run_callback event.name, obj do |obj|
+      unless execute_action(event, obj)
+        raise Jsm::IllegalTransitionError, "there is no matching transitions or invalid, Cant do event #{event.name}"
+      end
+      true
     end
-    true
+  end
+
+  private
+  def execute_action(event, obj)
+    can_be_executed?(event, obj) ? event.execute(obj) : false
   end
 end

data/lib/jsm/version.rb

@@ -1,3 +1,3 @@
 module Jsm
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: just_state_machine
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - wendy0402
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-10-22 00:00:00.000000000 Z
+date: 2015-10-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -144,6 +144,10 @@ files:
 - jsm.gemspec
 - lib/jsm.rb
 - lib/jsm/base.rb
+- lib/jsm/callbacks.rb
+- lib/jsm/callbacks/callback.rb
+- lib/jsm/callbacks/chain.rb
+- lib/jsm/callbacks/chain_collection.rb
 - lib/jsm/client.rb
 - lib/jsm/client/active_model.rb
 - lib/jsm/client/active_record.rb