argon 1.0.3 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0a64d4d65fc896c5d490a0ccc2c8fa44961c4020
-  data.tar.gz: '08e4cb3f3bd20952613b23c06e15b9838dc12883'
+  metadata.gz: f4bc7f87bd0b3e31f15e1c194ea49faac796ba68
+  data.tar.gz: 2dced65f814d1d838b57800dd7336bf30f1fbd1d
 SHA512:
-  metadata.gz: a9ad8ad56aed3f86e3ac838a766588ccf58ed57cddc408fbc640ef4196145b200a7fb1cf762a7a18add9d3c50836d5961ee17531869c4e11f8c0eaa8add50d19
-  data.tar.gz: 90f0f026e7e8f04e8c53bf8fa3fbb4eb285ea767f97c61500982519c93e00cc5a6836c284bd30a845262b5e563ee98c4ea788ebfb772ea37942dc292f656890d
+  metadata.gz: e87960bccf2ec34fe5cf927566c8f714325ea79fe9e42eed57b374c5570148289f29e1ad44ccc0af0453b03620b92514c3008df551994c99bcedc5c9c476cdf0
+  data.tar.gz: '0619768228c23bba7e01dd756e99d66d82c14be9d0d30c2d14987341fea1d9bd5450854b9cb942e509910f912aeedc9c04be8d0cb13836cab098b6bc6604e03a'

data/.gitignore

@@ -11,3 +11,4 @@
 # rspec failure tracking
 .rspec_status
 *.gem
+.byebug_history

data/README.md

@@ -26,12 +26,12 @@ The `Maxim` module provides a `state_machine` class method which expects the fol
   class Report
     include Argon
 
-    def on_cancel
-      # This is called from inside the lock, after the edge transitions. If an exception is thrown here, the entire transition is rolled back
+    def on_cancel(action:, message:)
+      # This is called from inside the lock, after the edge transitions, with the name of the action. If an exception is thrown here, the entire transition is rolled back
     end
 
-    def after_cancel
-      # This is called after a successful transition
+    def after_cancel(action:, message:)
+      # This is called after a successful transition, with the action which actually succeeded
     end
 
     state_machine state: {
@@ -46,10 +46,16 @@ The `Maxim` module provides a `state_machine` class method which expects the fol
         :cancel,
       ],
       edges: [
-        { from: :draft,     to: :submitted, action: :submit,           callbacks: {on: false, after: false}                       },
-        { from: :draft,     to: :cancelled, action: :cancel_draft,     callbacks: {on: false, after: false}, on_events: [:cancel] },
-        { from: :submitted, to: :cancelled, action: :cancel_submitted, callbacks: {on: false, after: false}, on_events: [:cancel] },
+        { from: :draft,     to: :submitted, action: :submit,           callbacks: {on: false, after: false}                                                     },
+        { from: :draft,     to: :cancelled, action: :cancel_draft,     callbacks: {on: false, after: false}, on_events: [:cancel], parameters: [:message_param] },
+        { from: :submitted, to: :cancelled, action: :cancel_submitted, callbacks: {on: false, after: false}, on_events: [:cancel], parameters: [:message_param] },
       ],
+      parameters: {
+        message_param: {
+          name:   :message,
+          check:  ->(message) { !message.nil? },
+        }
+      },
       on_successful_transition: ->(from:, to:) { /* Do something here */ },
       on_failed_transition:     ->(from:, to:) { /* Do something else */ },
     }

data/lib/argon/invalid_parameter_error.rb

@@ -0,0 +1,2 @@
+class Argon::InvalidParameterError < StandardError
+end

data/lib/argon/version.rb

@@ -1,3 +1,3 @@
 module Argon
-  VERSION = "1.0.3"
+  VERSION = "1.1.0"
 end

data/lib/argon.rb

@@ -1,22 +1,26 @@
 require 'argon/version'
 require 'argon/error'
 require 'argon/invalid_transition_error'
+require 'argon/invalid_parameter_error'
 require 'active_support/concern'
 require 'active_support/inflector'
 require 'pry-byebug'
 
 module Argon
   extend ActiveSupport::Concern
+  extend ActiveSupport::Inflector
+  include ActiveSupport::Inflector
 
   module ClassMethods
     def state_machine(mapping)
       raise Argon::Error.new("state_machine() has to be called on a Hash") unless mapping.is_a?(Hash)
       raise Argon::Error.new("state_machine() has to specify a field and the mappings") unless mapping.keys.count == 1 && mapping.keys.first.is_a?(Symbol) && mapping.values.first.is_a?(Hash)
-      raise Argon::Error.new("state_machine() should have (only) the following mappings: states, events, edges, on_successful_transition, on_failed_transition") if mapping.values.first.keys.sort != %i(states events edges on_successful_transition on_failed_transition).sort
+      raise Argon::Error.new("state_machine() should have (only) the following mappings: states, events, edges, parameters (optional), on_successful_transition, on_failed_transition") unless mapping.values.first.keys.to_set.subset?(%i(states events edges on_successful_transition on_failed_transition parameters).to_set) && %i(states events edges on_successful_transition on_failed_transition).to_set.subset?(mapping.values.first.keys.to_set)
 
       field                    = mapping.keys.first
       states_map               = mapping.values.first[:states]
       events_list              = mapping.values.first[:events]
+      parameters               = mapping.values.first[:parameters]
       edges_list               = mapping.values.first[:edges]
       on_successful_transition = mapping.values.first[:on_successful_transition]
       on_failed_transition     = mapping.values.first[:on_failed_transition]
@@ -32,21 +36,44 @@ module Argon
       raise Argon::Error.new("`events` should be an Array of Symbols") if !events_list.is_a?(Array) || (events_list.length > 0 && events_list.map(&:class).uniq != [Symbol])
       events_list.each do |event_name|
         raise Argon::Error.new("`#{event_name}` is not a valid event name. `#{self.name}##{event_name}` method already exists") if self.instance_methods.include?(event_name)
-        raise Argon::Error.new("`on_#{event_name}(action:)` not found") if !self.instance_methods.include?("on_#{event_name}".to_sym) || self.instance_method("on_#{event_name}".to_sym).parameters.to_set != [[:keyreq, :action]].to_set
-        raise Argon::Error.new("`after_#{event_name}(action:)` not found") if !self.instance_methods.include?("after_#{event_name}".to_sym) || self.instance_method("after_#{event_name}".to_sym).parameters.to_set != [[:keyreq, :action]].to_set
+
+        event_edges = edges_list.select{|e| !e[:on_events].nil? && e[:on_events].include?(event_name)}
+
+        if event_edges.empty?
+          raise Argon::Error.new("`on_#{event_name}(action:)` not found") if !self.instance_methods.include?("on_#{event_name}".to_sym) || self.instance_method("on_#{event_name}".to_sym).parameters.to_set != [[:keyreq, :action]].to_set
+          raise Argon::Error.new("`after_#{event_name}(action:)` not found") if !self.instance_methods.include?("after_#{event_name}".to_sym) || self.instance_method("after_#{event_name}".to_sym).parameters.to_set != [[:keyreq, :action]].to_set
+        else
+          raise Argon::Error.new("Event `#{event_name}` is being used by edges (#{ event_edges.map{|e| "`#{e[:action]}`"}.join(", ") }) with mixed lists of parameters") if event_edges.map{|e| (e[:parameters] || []).to_set}.uniq.length > 1
+          expected_parameters = %i(action)
+          if !event_edges[0][:parameters].nil?
+            expected_parameters += parameters.values_at(*event_edges[0][:parameters]).map{|p| p[:name]}
+          end
+          raise Argon::Error.new("`on_#{event_name}(#{ expected_parameters.map{|p| "#{p}:"}.join(", ") })` not found") if !self.instance_methods.include?("on_#{event_name}".to_sym) || self.instance_method("on_#{event_name}".to_sym).parameters.to_set != expected_parameters.map{|name| [:keyreq, name]}.to_set
+          raise Argon::Error.new("`after_#{event_name}(#{ expected_parameters.map{|p| "#{p}:"}.join(", ") })` not found") if !self.instance_methods.include?("after_#{event_name}".to_sym) || self.instance_method("after_#{event_name}".to_sym).parameters.to_set != expected_parameters.map{|name| [:keyreq, name]}.to_set
+        end
+      end
+      raise Argon::Error.new("`parameters` should be a Hash with keys as the parameter identifier, with value as a Hash as {name: Symbol, check: lambda(object)}") if !parameters.nil? && !parameters.is_a?(Hash) && parameters.keys.map(&:class).to_set != [Symbol].to_set
+      if !parameters.nil?
+        parameters.each_pair do |param_name, param_details|
+          raise Argon::Error.new("`parameters.#{param_name}` should be a Hash with keys as the parameter identifier, with value as a Hash as {name: Symbol, check: lambda(object)}") if param_details.keys.to_set != %i(name check).to_set
+          raise Argon::Error.new("`parameters.#{param_name}.name` should be a Symbol") unless param_details[:name].is_a?(Symbol)
+          raise Argon::Error.new("`parameters.#{param_name}.check` should be a lambda that takes one arg") if !param_details[:check].is_a?(Proc) || !(param_details[:check].parameters.length == 1 && param_details[:check].parameters[0].length == 2 && param_details[:check].parameters[0][0] == :req && param_details[:check].parameters[0][1].is_a?(Symbol))
+        end
       end
 
-      raise Argon::Error.new("`edges` should be an Array of Hashes, with keys: from, to, action, callbacks{on: true/false, after: true/false}, on_events (optional)") if !edges_list.is_a?(Array) || edges_list.map(&:class).uniq != [Hash]
+      raise Argon::Error.new("`edges` should be an Array of Hashes, with keys: from, to, action, callbacks{on: true/false, after: true/false}, on_events (optional), parameters (optional)") if !edges_list.is_a?(Array) || edges_list.map(&:class).to_set != [Hash].to_set
 
       registered_edge_pairs = [].to_set
       edges_list.each_with_index do |edge_details, index|
-        from         = edge_details[:from]
-        to           = edge_details[:to]
-        action       = edge_details[:action]
-        do_action    = "#{action}!".to_sym
-        check_action = "can_#{action}?".to_sym
-
-        raise Argon::Error.new("`edges` should be an Array of Hashes, with keys: from, to, action, callbacks{on: true/false, after: true/false}, on_events (optional)") unless edge_details.keys.to_set.subset?([:from, :to, :action, :callbacks, :on_events].to_set) && [:from, :to, :action, :callbacks].to_set.subset?(edge_details.keys.to_set)
+        from                   = edge_details[:from]
+        to                     = edge_details[:to]
+        action                 = edge_details[:action]
+        do_action              = "#{action}!".to_sym
+        check_action           = "can_#{action}?".to_sym
+        action_parameters      = edge_details[:parameters]
+        action_parameter_names = (action_parameters.nil? || parameters.nil?) ? [] : parameters.values_at(*action_parameters).compact.map{|p| p[:name]}
+
+        raise Argon::Error.new("`edges` should be an Array of Hashes, with keys: from, to, action, callbacks{on: true/false, after: true/false}, on_events (optional), parameters (optional)") unless edge_details.keys.to_set.subset?([:from, :to, :action, :callbacks, :on_events, :parameters].to_set) && [:from, :to, :action, :callbacks].to_set.subset?(edge_details.keys.to_set)
         raise Argon::Error.new("`edges[#{index}].from` is not a valid state") unless states_map.keys.include?(from)
         raise Argon::Error.new("`edges[#{index}].to` is not a valid state") unless states_map.keys.include?(to)
         raise Argon::Error.new("`edges[#{index}].action` is not a Symbol") unless action.is_a?(Symbol)
@@ -54,10 +81,10 @@ module Argon
         raise Argon::Error.new("`#{edge_details[:action]}` is an invalid action name. `#{self.name}##{check_action}` method already exists") if self.instance_methods.include?(check_action)
         raise Argon::Error.new("`edges[#{index}].callbacks` must be {on: true/false, after: true/false}") if !edge_details[:callbacks].is_a?(Hash) || edge_details[:callbacks].keys.to_set != [:after, :on].to_set || !edge_details[:callbacks].values.to_set.subset?([true, false].to_set)
         if edge_details[:callbacks][:on]
-          raise Argon::Error.new("`on_#{edge_details[:action]}()` not found") if !self.instance_methods.include?("on_#{edge_details[:action]}".to_sym) || self.instance_method("on_#{edge_details[:action]}".to_sym).parameters.to_set != [].to_set
+          raise Argon::Error.new("`on_#{edge_details[:action]}(#{ action_parameter_names.map{|p| "#{p}:"}.join(", ") })` not found") if !self.instance_methods.include?("on_#{edge_details[:action]}".to_sym) || self.instance_method("on_#{edge_details[:action]}".to_sym).parameters.to_set != action_parameter_names.map{|name| [:keyreq, name]}.to_set
         end
         if edge_details[:callbacks][:after]
-          raise Argon::Error.new("`after_#{edge_details[:action]}()` not found") if !self.instance_methods.include?("after_#{edge_details[:action]}".to_sym) || self.instance_method("after_#{edge_details[:action]}".to_sym).parameters.to_set != [].to_set
+          raise Argon::Error.new("`after_#{edge_details[:action]}(#{ action_parameter_names.map{|p| "#{p}:"}.join(",") })` not found") if !self.instance_methods.include?("after_#{edge_details[:action]}".to_sym) || self.instance_method("after_#{edge_details[:action]}".to_sym).parameters.to_set != action_parameter_names.map{|name| [:keyreq, name]}.to_set
         end
         raise Argon::Error.new("`#{edge_details[:on_events]}` (`edges[#{index}].on_events`) is not a valid list of events") if !edge_details[:on_events].nil? && !edge_details[:on_events].is_a?(Array)
         unless edge_details[:on_events].nil?
@@ -65,6 +92,14 @@ module Argon
             raise Argon::Error.new("`#{ event_name }` (`edges[#{index}].on_events[#{event_index}]`) is not a registered event") unless events_list.include?(event_name)
           end
         end
+
+        raise Argon::Error.new("`edges[#{index}].parameters` lists multiple parameters with the same name") if action_parameter_names.length != action_parameter_names.uniq.length
+
+        unless edge_details[:parameters].nil?
+          edge_details[:parameters].each_with_index do |param_name, param_index|
+            raise Argon::Error.new("`#{ param_name }` (`edges[#{index}].parameters[#{param_index}]`) is not a registered parameter") unless parameters.keys.include?(param_name)
+          end
+        end
         raise Argon::Error.new("`edges[#{index}]` is a duplicate edge") if registered_edge_pairs.include?([from,to])
         registered_edge_pairs << [from, to]
       end
@@ -75,6 +110,9 @@ module Argon
       raise Argon::Error.new("`on_failed_transition` must be a lambda of signature `(from:, to:)`") if !on_failed_transition.nil? && !on_failed_transition.is_a?(Proc)
       raise Argon::Error.new("`on_failed_transition` must be a lambda of signature `(from:, to:)`") if on_failed_transition.parameters.to_set != [[:keyreq, :from],[:keyreq, :to]].to_set
 
+      events_list.each do |event_name|
+      end
+
       state_machines = {}
       begin
         state_machines = self.class_variable_get(:@@state_machines)
@@ -115,6 +153,7 @@ module Argon
         from               = edge_details[:from]
         to                 = edge_details[:to]
         action             = edge_details[:action]
+        action_parameters  = edge_details[:parameters] || []
         on_lock_callback   = "on_#{action}".to_sym if edge_details[:callbacks][:on] == true
         after_lock_callback = "after_#{action}".to_sym if edge_details[:callbacks][:after] == true
 
@@ -122,7 +161,20 @@ module Argon
           self.send(field) == from
         end
 
-        define_method("#{action}!".to_sym) do |&block|
+        define_method("#{action}!".to_sym) do |**args, &block|
+          required_keywords = !parameters.nil? ? parameters.values_at(*action_parameters).map{|p| p[:name]} : []
+          available_keywords = args.keys
+
+          raise ArgumentError.new("wrong number of arguments (given 1, expected 0)") if required_keywords.to_set.empty? && !available_keywords.to_set.empty?
+          raise ArgumentError.new("missing #{ pluralize("keyword", (required_keywords - available_keywords).length) }: #{ (required_keywords - available_keywords).join(", ") }") if !required_keywords.to_set.subset?(available_keywords.to_set)
+          raise ArgumentError.new("unknown #{ pluralize("keyword", (available_keywords - required_keywords).length) }: #{ (available_keywords - required_keywords).join(", ") }") if !available_keywords.to_set.subset?(required_keywords.to_set)
+
+          if !parameters.nil? && !action_parameters.empty?
+            parameters.select{ |k,v| action_parameters.include?(k) }.each_pair do |param_name, param_details|
+              raise Argon::InvalidParameterError.new("incorrect value for `#{ param_name }`") if !param_details[:check].call(args[:param_name])
+            end
+          end
+
           if self.send(field) != from
             on_failed_transition.call(from: self.send(field), to: to)
             raise Argon::InvalidTransitionError.new("Invalid state transition")
@@ -134,7 +186,11 @@ module Argon
               self.touch
 
               unless on_lock_callback.nil?
-                self.send(on_lock_callback)
+                if args.empty?
+                  self.send(on_lock_callback)
+                else
+                  self.send(on_lock_callback, args)
+                end
               end
 
               unless block.nil?
@@ -149,23 +205,33 @@ module Argon
           on_successful_transition.call(from: from, to: to)
 
           unless after_lock_callback.nil?
-            self.send(after_lock_callback)
+            if args.empty?
+              self.send(after_lock_callback)
+            else
+              self.send(after_lock_callback, args)
+            end
           end
         end
       end
 
       events_list.each do |event_name|
-        define_method("#{event_name}!".to_sym) do
+        define_method("#{event_name}!".to_sym) do |**args|
           matching_edges = edges_list.select{ |edge| !edge[:on_events].nil? && edge[:on_events].to_set.include?(event_name) }
 
           matching_edges.each do |edge|
             action = edge[:action]
 
             if self.send("can_#{ action }?")
-              self.send("#{ action }!") do
-                self.send("on_#{ event_name }", action: action)
+              if args.empty?
+                self.send("#{ action }!") do
+                  self.send("on_#{ event_name }", {action: action})
+                end
+              else
+                self.send("#{ action }!", args) do
+                  self.send("on_#{ event_name }", {action: action}.merge(args))
+                end
               end
-              self.send("after_#{ event_name }", action: action)
+              self.send("after_#{ event_name }", {action: action}.merge(args))
               return
             end
           end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: argon
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.1.0
 platform: ruby
 authors:
 - Ajith Hussain
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-10-07 00:00:00.000000000 Z
+date: 2017-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -114,6 +114,7 @@ files:
 - bin/setup
 - lib/argon.rb
 - lib/argon/error.rb
+- lib/argon/invalid_parameter_error.rb
 - lib/argon/invalid_transition_error.rb
 - lib/argon/version.rb
 homepage: https://github.com/sparkymat/argon