workflow 3.0.0 → 3.1.0.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a90286a0749bd94cabc4fab8cc89dc5c9fc7b05d60ea5cf58cd6493852159206
-  data.tar.gz: 8c4015a8ba91be4c4fc37bd5e8004534146d1daedfd290d32538edec33ac02a3
+  metadata.gz: ecf93e8750c9a77e512c840987b34f0616fd6304ed9f2bc98372aaea992fcfe9
+  data.tar.gz: 5e86611e43d7d49f61e814e3c6804664b2134c293c768ccb73ebd8bcb09b07c3
 SHA512:
-  metadata.gz: b72b7e1d8de350a9e5478d291d7ff6a1e0f6f192bff31eac6951f9f5e8fbf4941597e84e990838402902fb65fa79acabfffdfc5fd168d937967e5d63239dc7f1
-  data.tar.gz: 9aaea40918c7f2b55b9e51a8ae881708869af77e22995545a5e5017731b19575d7f0ed0a6ffbd5343a6c8883854d81e83749e7447abedd796d6c2d77345bebf8
+  metadata.gz: e77f206fc4206d3407e33b3d044b5c291784a4f544bc01a21aacc3f8f92db0fa011a02acfe0987b352e01ddf7b391337ae3a4bde8616d44dfa331c48cfa86595
+  data.tar.gz: 33042e85d5f98fbef4c43094da563fb7b22fa2d175220489a062a0295ed52dc2f1445ecc941ce8094c0b858c468431458fadb73f80ec7c56c2b53c813310f260

data/README.adoc

@@ -102,7 +102,7 @@ article.current_state.between? :awaiting_review, :rejected # => true
 ```
 
 Now we can call the submit event, which transitions to the
-<tt>:awaiting_review</tt> state:
+`:awaiting_review` state:
 
 ```rb
 article.submit!
@@ -131,7 +131,7 @@ gem install workflow
 install the `activesupport` and `ruby-graphviz` gems.
 
 Versions up to and including 1.0.0 are also available as a single file download -
-[lib/workflow.rb file](https://github.com/geekq/workflow/blob/v1.0.0/lib/workflow.rb).
+link:https://github.com/geekq/workflow/blob/v1.0.0/lib/workflow.rb[lib/workflow.rb file].
 
 
 === Examples
@@ -345,43 +345,6 @@ favorite database.
 Advanced usage
 --------------
 
-### Accessing your workflow specification
-
-You can easily reflect on workflow specification programmatically - for
-the whole class or for the current object. Examples:
-
-```rb
-article2.current_state.events # lists possible events from here
-article2.current_state.events[:reject].transitions_to # => :rejected
-
-Article.workflow_spec.states.keys
-#=> [:rejected, :awaiting_review, :being_reviewed, :accepted, :new]
-
-Article.workflow_spec.state_names
-#=> [:rejected, :awaiting_review, :being_reviewed, :accepted, :new]
-
-# list all events for all states
-Article.workflow_spec.states.values.collect &:events
-```
-
-You can also store and later retrieve additional meta data for every
-state and every event:
-
-```rb
-class MyProcess
-  include Workflow
-  workflow do
-    state :main, :meta => {:importance => 8}
-    state :supplemental, :meta => {:importance => 1}
-  end
-end
-puts MyProcess.workflow_spec.states[:supplemental].meta[:importance] # => 1
-```
-
-The workflow library itself uses this feature to tweak the graphical
-representation of the workflow. See below.
-
-
 ### Conditional event transitions
 
 Conditions can be a "method name symbol" with a corresponding instance method, a `proc` or `lambda` which are added to events, like so:
@@ -407,6 +370,8 @@ When calling a `device.can_<fire_event>?` check, or attempting a `device.<event>
 * If an `:if` check is present, proceed if it evaluates to true, or drop to the next event.
 * If you've run out of events to check (eg. `battery_level == 0`), then the transition isn't possible.
 
+You can also pass additional arguments, which can be evaluated by :if methods or procs. See examples in
+link:test/conditionals_test.rb#L45[conditionals_test.rb]
 
 ### Advanced transition hooks
 
@@ -487,11 +452,60 @@ The whole event sequence is as follows:
     * event specific action
     * on_transition (if action did not halt)
     * on_exit
-    * PERSIST WORKFLOW STATE, i.e. transition
+    * PERSIST WORKFLOW STATE (i.e. transition) or on_error
     * on_entry
     * after_transition
 
 
+### Accessing your workflow specification
+
+You can easily reflect on workflow specification programmatically - for
+the whole class or for the current object. Examples:
+
+```rb
+article2.current_state.events # lists possible events from here
+article2.current_state.events[:reject].transitions_to # => :rejected
+
+Article.workflow_spec.states.keys
+#=> [:rejected, :awaiting_review, :being_reviewed, :accepted, :new]
+
+Article.workflow_spec.state_names
+#=> [:rejected, :awaiting_review, :being_reviewed, :accepted, :new]
+
+# list all events for all states
+Article.workflow_spec.states.values.collect &:events
+```
+
+You can also store and later retrieve additional meta data for every
+state and every event:
+
+```rb
+class MyProcess
+  include Workflow
+  workflow do
+    state :main, :meta => {:importance => 8}
+    state :supplemental, :meta => {:importance => 1}
+  end
+end
+puts MyProcess.workflow_spec.states[:supplemental].meta[:importance] # => 1
+```
+
+The workflow library itself uses this feature to tweak the graphical
+representation of the workflow. See below.
+
+
+### Defining workflow dynamically from JSON
+
+For an advance example please see
+link:https://github.com/geekq/workflow/blob/develop/test/workflow_from_json_test.rb[workflow_from_json_test.rb].
+
+
+### Compose workflow definition with `include`
+
+In case you have very extensive workflow definition or would like to reuse
+workflow definition for different classes, you can include parts like in
+the link:https://github.com/geekq/workflow/blob/develop/test/main_test.rb#L95-L110[`including a child workflow definition` example].
+
 Documenting with diagrams
 -------------------------
 
@@ -513,11 +527,17 @@ end
 Changelog
 ---------
 
+=== New in the version 3.1.0
+
+* link:https://github.com/geekq/workflow/pull/227[#227] Allow event arguments to be taken into account when selecting the event
+* link:https://github.com/geekq/workflow/pull/232[#232] Add ability to include partial workflow definitions for composability
+* link:https://github.com/geekq/workflow/pull/241[#241] Example for defining workflow dynamically from JSON
+
 === New in the version 3.0.0
 
-* gh-228 Support for Ruby 3 keyword args, provided by @agirling
+* link:https://github.com/geekq/workflow/pull/228[#228] Support for Ruby 3 keyword args, provided by @agirling
 * retire Ruby 2.6 since it has reached end of live; please use workflow 2.x, if you still depend on that Ruby version
-* gh-229 Switch from travis CI to GihHub actions for continuous integration
+* link:https://github.com/geekq/workflow/pull/229[#229] Switch from travis CI to GihHub actions for continuous integration
 
 ### New in the versions 2.x
 
@@ -543,6 +563,11 @@ bundle install
 bundle exec rake test
 ```
 
+### Check list for you pull request
+
+* [ ] unit tests for the new behavior provided: new tests fail without you change, all tests succeed with your change
+* [ ] documentation update included
+
 ### Other 3rd party libraries
 
 https://github.com/kwent/active_admin-workflow[ActiveAdmin-Workflow] - is an
@@ -552,7 +577,7 @@ integration with https://github.com/activeadmin/activeadmin[ActiveAdmin].
 
 Author: Vladimir Dobriakov, <https://infrastructure-as-code.de>
 
-Copyright (c) 2010-2022 Vladimir Dobriakov and Contributors
+Copyright (c) 2010-2024 Vladimir Dobriakov and Contributors
 
 Copyright (c) 2008-2009 Vodafone
 
@@ -561,4 +586,3 @@ Copyright (c) 2007-2008 Ryan Allen, FlashDen Pty Ltd
 Based on the work of Ryan Allen and Scott Barron
 
 Licensed under MIT license, see the MIT-LICENSE file.
-

data/lib/workflow/event.rb

@@ -15,12 +15,22 @@ module Workflow
                    end
     end
 
-    def condition_applicable?(object)
+    def condition_applicable?(object, event_arguments)
       if condition
         if condition.is_a?(Symbol)
-          object.send(condition)
+          m = object.method(condition)
+          # Conditionals can now take the arguments of the trasition action into account #227
+          # But in case the current conditional wants to ignore any event_argument on its decision -
+          # does not accept parameters, also support that.
+          if m.arity == 0 # no additional parameters accepted
+            object.send(condition)
+          else
+            object.send(condition, *event_arguments)
+          end
         else
-          condition.call(object)
+          # since blocks can ignore extra arguments without raising an error in Ruby,
+          # no `if` is needed - compare with `arity` switch in above methods handling
+          condition.call(object, *event_arguments)
         end
       else
         true

data/lib/workflow/event_collection.rb

@@ -26,9 +26,9 @@ module Workflow
       end
     end
 
-    def first_applicable(name, object_context)
+    def first_applicable(name, object_context, event_arguments)
       (self[name] || []).detect do |event|
-        event.condition_applicable?(object_context) && event
+        event.condition_applicable?(object_context, event_arguments) && event
       end
     end
 

data/lib/workflow/specification.rb

@@ -20,6 +20,10 @@ module Workflow
 
     private
 
+    def include(proc)
+      instance_eval(&proc)
+    end
+
     def state(name, meta = {:meta => {}}, &events_and_etc)
       # meta[:meta] to keep the API consistent..., gah
       new_state = Workflow::State.new(name, self, meta[:meta])

data/lib/workflow/version.rb

@@ -1,3 +1,3 @@
 module Workflow
-  VERSION = "3.0.0"
+  VERSION = "3.1.0.pre"
 end

data/lib/workflow.rb

@@ -65,8 +65,8 @@ module Workflow
               process_event!(event_name, *args, **kwargs)
             end
 
-            define_method "can_#{event_name}?" do
-              return !!current_state.events.first_applicable(event_name, self)
+            define_method "can_#{event_name}?".to_sym do |*args, **kwargs|
+              return !!current_state.events.first_applicable(event_name, self, args)
             end
           end
         end
@@ -95,7 +95,7 @@ module Workflow
     end
 
     def process_event!(name, *args, **kwargs)
-      event = current_state.events.first_applicable(name, self)
+      event = current_state.events.first_applicable(name, self, args)
       raise NoTransitionAllowed.new(
         "There is no event #{name.to_sym} defined for the #{current_state} state") \
         if event.nil?

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: workflow
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0.pre
 platform: ruby
 authors:
 - Vladimir Dobriakov
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-05-29 00:00:00.000000000 Z
+date: 2024-05-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rdoc
@@ -16,70 +16,70 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '6.4'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '6.4'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.3'
 - !ruby/object:Gem::Dependency
   name: mocha
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.8'
+        version: '2.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.8'
+        version: '2.2'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.3'
+        version: '13.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.3'
+        version: '13.1'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.11'
+        version: '5.21'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.11'
+        version: '5.21'
 - !ruby/object:Gem::Dependency
   name: ruby-graphviz
   requirement: !ruby/object:Gem::Requirement
@@ -122,7 +122,7 @@ homepage: https://github.com/geekq/workflow
 licenses:
 - MIT
 metadata: {}
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -133,12 +133,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubygems_version: 3.1.2
-signing_key:
+rubygems_version: 3.3.7
+signing_key: 
 specification_version: 4
 summary: A replacement for acts_as_state_machine.
 test_files: []