workflow 2.0.2 → 3.1.0.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4834f20238e73dbf0304747da6f098612e395c92a6b839908c7c0a613ad272b8
-  data.tar.gz: 40a8fa57362ed445be012847fe283db2b417225ea3db4ea4c02bcad957630b57
+  metadata.gz: ecf93e8750c9a77e512c840987b34f0616fd6304ed9f2bc98372aaea992fcfe9
+  data.tar.gz: 5e86611e43d7d49f61e814e3c6804664b2134c293c768ccb73ebd8bcb09b07c3
 SHA512:
-  metadata.gz: 9cb4cd4a9738529cdffc867d04716dbe0bce0df361e84fe55570563624441728e41d2bfec5639cbae6e64dbcf86f047abd73adb542140cb0ecdf92f92be39237
-  data.tar.gz: 1cbbddb5014d83e9ace2b03e2d5e60cf01acbc8f1579d942b68267d144b3513f01fb23797219450e44aca85ae476e4675d57e97fcb149043be16d951c17608c1
+  metadata.gz: e77f206fc4206d3407e33b3d044b5c291784a4f544bc01a21aacc3f8f92db0fa011a02acfe0987b352e01ddf7b391337ae3a4bde8616d44dfa331c48cfa86595
+  data.tar.gz: 33042e85d5f98fbef4c43094da563fb7b22fa2d175220489a062a0295ed52dc2f1445ecc941ce8094c0b858c468431458fadb73f80ec7c56c2b53c813310f260

data/README.adoc

@@ -0,0 +1,588 @@
+:doctype: book
+:toc: macro
+:toclevels: 1
+:sectlinks:
+:idprefix:
+
+# Workflow
+
+image:https://img.shields.io/gem/v/workflow.svg[link=https://rubygems.org/gems/workflow]
+image:https://github.com/geekq/workflow/actions/workflows/test.yml/badge.svg[link=https://github.com/geekq/workflow/actions/workflows/test.yml]
+image:https://codeclimate.com/github/geekq/workflow/badges/gpa.svg[link=https://codeclimate.com/github/geekq/workflow]
+image:https://codeclimate.com/github/geekq/workflow/badges/coverage.svg[link=https://codeclimate.com/github/geekq/workflow/coverage]
+
+Note: you can find documentation for specific workflow rubygem versions
+at http://rubygems.org/gems/workflow : select a version (optional,
+default is latest release), click "Documentation" link. When reading on
+github.com, the README refers to the upcoming release.
+
+toc::[]
+
+What is workflow?
+-----------------
+
+Workflow is a finite-state-machine-inspired API for modeling and
+interacting with what we tend to refer to as 'workflow'.
+
+A lot of business modeling tends to involve workflow-like concepts, and
+the aim of this library is to make the expression of these concepts as
+clear as possible, using similar terminology as found in state machine
+theory.
+
+So, a workflow has a state. It can only be in one state at a time. When
+a workflow changes state, we call that a transition. Transitions occur
+on an event, so events cause transitions to occur. Additionally, when an
+event fires, other arbitrary code can be executed, we call those actions.
+So any given state has a bunch of events, any event in a state causes a
+transition to another state and potentially causes code to be executed
+(an action). We can hook into states when they are entered, and exited
+from, and we can cause transitions to fail (guards), and we can hook in
+to every transition that occurs ever for whatever reason we can come up
+with.
+
+Now, all that's a mouthful, but we'll demonstrate the API bit by bit
+with a real-ish world example.
+
+Let's say we're modeling article submission from journalists. An article
+is written, then submitted. When it's submitted, it's awaiting review.
+Someone reviews the article, and then either accepts or rejects it.
+Here is the expression of this workflow using the API:
+
+```rb
+class Article
+  include Workflow
+  workflow do
+    state :new do
+      event :submit, :transitions_to => :awaiting_review
+    end
+    state :awaiting_review do
+      event :review, :transitions_to => :being_reviewed
+    end
+    state :being_reviewed do
+      event :accept, :transitions_to => :accepted
+      event :reject, :transitions_to => :rejected
+    end
+    state :accepted
+    state :rejected
+  end
+end
+```
+
+Nice, isn't it!
+
+Note: the first state in the definition (`:new` in the example, but you
+can name it as you wish) is used as the initial state - newly created
+objects start their life cycle in that state.
+
+Let's create an article instance and check in which state it is:
+
+```rb
+article = Article.new
+article.accepted? # => false
+article.new? # => true
+```
+
+You can also access the whole `current_state` object including the list
+of possible events and other meta information:
+
+    article.current_state
+    => #<Workflow::State:0x7f1e3d6731f0 @events={
+      :submit=>#<Workflow::Event:0x7f1e3d6730d8 @action=nil,
+        @transitions_to=:awaiting_review, @name=:submit, @meta={}>},
+      name:new, meta{}
+
+You can also check, whether a state comes before or after another state (by the
+order they were defined):
+
+```rb
+article.current_state # => being_reviewed
+article.current_state < :accepted # => true
+article.current_state >= :accepted # => false
+article.current_state.between? :awaiting_review, :rejected # => true
+```
+
+Now we can call the submit event, which transitions to the
+`:awaiting_review` state:
+
+```rb
+article.submit!
+article.awaiting_review? # => true
+```
+
+Events are actually instance methods on a workflow, and depending on the
+state you're in, you'll have a different set of events used to
+transition to other states.
+
+It is also easy to check, if a certain transition is possible from the
+current state . `article.can_submit?` checks if there is a `:submit`
+event (transition) defined for the current state.
+
+
+Getting started
+---------------
+
+=== Installation
+
+```sh
+gem install workflow
+```
+
+**Important**: If you're interested in graphing your workflow state machine, you will also need to
+install the `activesupport` and `ruby-graphviz` gems.
+
+Versions up to and including 1.0.0 are also available as a single file download -
+link:https://github.com/geekq/workflow/blob/v1.0.0/lib/workflow.rb[lib/workflow.rb file].
+
+
+=== Examples
+
+After installation or downloading the library you can easily try out
+all the example code from this README in irb.
+
+    $ irb
+    require 'rubygems'
+    require 'workflow'
+
+Now just copy and paste the source code from the beginning of this README
+file snippet by snippet and observe the output.
+
+
+### Transition event handler
+
+The best way is to use convention over configuration and to define a
+method with the same name as the event. Then it is automatically invoked
+when event is raised. For the Article workflow defined earlier it would
+be:
+
+```rb
+class Article
+  def reject
+    puts 'sending email to the author explaining the reason...'
+  end
+end
+```
+
+`article.review!; article.reject!` will cause state transition to
+`being_reviewed` state, persist the new state (if integrated with
+ActiveRecord), invoke this user defined `reject` method and finally
+persist the `rejected` state.
+
+Note: on successful transition from one state to another the workflow
+gem immediately persists the new workflow state with `update_column()`,
+bypassing any ActiveRecord callbacks including `updated_at` update.
+This way it is possible to deal with the validation and to save the
+pending changes to a record at some later point instead of the moment
+when transition occurs.
+
+You can also define event handler accepting/requiring additional
+arguments:
+
+```rb
+class Article
+  def review(reviewer = '')
+    puts "[#{reviewer}] is now reviewing the article"
+  end
+end
+
+article2 = Article.new
+article2.submit!
+article2.review!('Homer Simpson') # => [Homer Simpson] is now reviewing the article
+```
+
+Alternative way is to use a block (only recommended for short event
+implementation without further code nesting):
+
+```rb
+event :review, :transitions_to => :being_reviewed do |reviewer|
+  # store the reviewer
+end
+```
+
+We've noticed, that mixing the list of events and states with the blocks
+invoked for particular transitions leads to a bumpy and poorly readable code
+due to a deep nesting. We tried (and dismissed) lambdas for this. Eventually
+we decided to invoke an optional user defined callback method with the same
+name as the event (convention over configuration) as explained before.
+
+State persistence
+-----------------
+
+=== ActiveRecord
+
+Note: Workflow 2.0 is a major refactoring for the `worklow` library.
+If your application suddenly breaks after the workflow 2.0 release, you've
+probably got your Gemfile wrong ;-). workflow uses
+https://guides.rubygems.org/patterns/#semantic-versioning[semantic versioning].
+For highest compatibility please reference the desired major+minor version.
+
+Note on ActiveRecord/Rails 4.\*, 5.\* Support:
+
+Since integration with ActiveRecord makes over 90% of the issues and
+maintenance effort, and also to allow for an independent (faster) release cycle
+for Rails support, starting with workflow **version 2.0** in January 2019 the
+support for ActiveRecord (4.\*, 5.\* and newer) has been extracted into a separate
+gem. Read at
+https://github.com/geekq/workflow-activerecord[workflow-activerecord], how to
+include the right gem.
+
+To use legacy built-in ActiveRecord 2.3 - 4.* support, reference Workflow 1.2 in
+your Gemfile:
+
+    gem 'workflow', '~> 1.2'
+
+
+=== Custom workflow state persistence
+
+If you do not use a relational database and ActiveRecord, you can still
+integrate the workflow very easily. To implement persistence you just
+need to override `load_workflow_state` and
+`persist_workflow_state(new_value)` methods. Next section contains an example for
+using CouchDB, a document oriented database.
+
+http://tim.lossen.de/[Tim Lossen] implemented support
+for http://github.com/tlossen/remodel[remodel] / http://github.com/antirez/redis[redis]
+key-value store.
+
+=== Integration with CouchDB
+
+We are using the compact http://github.com/geekq/couchtiny[couchtiny library]
+here. But the implementation would look similar for the popular
+couchrest library.
+
+```rb
+require 'couchtiny'
+require 'couchtiny/document'
+require 'workflow'
+
+class User < CouchTiny::Document
+  include Workflow
+  workflow do
+    state :submitted do
+      event :activate_via_link, :transitions_to => :proved_email
+    end
+    state :proved_email
+  end
+
+  def load_workflow_state
+    self[:workflow_state]
+  end
+
+  def persist_workflow_state(new_value)
+    self[:workflow_state] = new_value
+    save!
+  end
+end
+```
+
+Please also have a look at
+http://github.com/geekq/workflow/blob/develop/test/couchtiny_example.rb[the full source code].
+
+
+=== Adapters to support other databases
+
+I get a lot of requests to integrate persistence support for different
+databases, object-relational adapters, column stores, document
+databases.
+
+To enable highest possible quality, avoid too many dependencies and to
+avoid unneeded maintenance burden on the `workflow` core it is best to
+implement such support as a separate gem.
+
+Only support for the ActiveRecord will remain for the foreseeable
+future. So Rails beginners can expect `workflow` to work with Rails out
+of the box. Other already included adapters stay for a while but should
+be extracted to separate gems.
+
+If you want to implement support for your favorite ORM mapper or your
+favorite NoSQL database, you just need to implement a module which
+overrides the persistence methods `load_workflow_state` and
+`persist_workflow_state`. Example:
+
+```rb
+module Workflow
+  module SuperCoolDb
+    module InstanceMethods
+      def load_workflow_state
+        # Load and return the workflow_state from some storage.
+        # You can use self.class.workflow_column configuration.
+      end
+
+      def persist_workflow_state(new_value)
+        # save the new_value workflow state
+      end
+    end
+
+    module ClassMethods
+      # class methods of your adapter go here
+    end
+
+    def self.included(klass)
+      klass.send :include, InstanceMethods
+      klass.extend ClassMethods
+    end
+  end
+end
+```
+
+The user of the adapter can use it then as:
+
+```rb
+class Article
+  include Workflow
+  include Workflow:SuperCoolDb
+  workflow do
+    state :submitted
+    # ...
+  end
+end
+```
+
+I can then link to your implementation from this README. Please let me
+also know, if you need any interface beyond `load_workflow_state` and
+`persist_workflow_state` methods to implement an adapter for your
+favorite database.
+
+Advanced usage
+--------------
+
+### 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:
+
+```rb
+state :off
+  event :turn_on, :transition_to => :on,
+                  :if => :sufficient_battery_level?
+
+  event :turn_on, :transition_to => :low_battery,
+                  :if => proc { |device| device.battery_level > 0 }
+end
+
+# corresponding instance method
+def sufficient_battery_level?
+  battery_level > 10
+end
+```
+
+When calling a `device.can_<fire_event>?` check, or attempting a `device.<event>!`, each event is checked in turn:
+
+* With no `:if` check, proceed as usual.
+* 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
+
+#### on_entry/on_exit
+
+We already had a look at the declaring callbacks for particular workflow
+events. If you would like to react to all transitions to/from the same state
+in the same way you can use the on_entry/on_exit hooks. You can either define it
+with a block inside the workflow definition or through naming
+convention, e.g. for the state :pending just define the method
+`on_pending_exit(new_state, event, *args)` somewhere in your class.
+
+#### on_transition
+
+If you want to be informed about everything happening everywhere, e.g. for
+logging then you can use the universal `on_transition` hook:
+
+```rb
+workflow do
+  state :one do
+    event :increment, :transitions_to => :two
+  end
+  state :two
+  on_transition do |from, to, triggering_event, *event_args|
+    Log.info "#{from} -> #{to}"
+  end
+end
+```
+
+#### on_error
+
+If you want to do custom exception handling internal to workflow, you can define an `on_error` hook in your workflow.
+For example:
+
+```rb
+workflow do
+  state :first do
+    event :forward, :transitions_to => :second
+  end
+  state :second
+
+  on_error do |error, from, to, event, *args|
+    Log.info "Exception(#{error.class}) on #{from} -> #{to}"
+  end
+end
+```
+
+If forward! results in an exception, `on_error` is invoked and the workflow stays in a 'first' state.  This capability
+is particularly useful if your errors are transient and you want to queue up a job to retry in the future without
+affecting the existing workflow state.
+
+### Guards
+
+If you want to halt the transition conditionally, you can just raise an
+exception in your [transition event handler](#transition_event_handler).
+There is a helper called `halt!`, which raises the
+Workflow::TransitionHalted exception. You can provide an additional
+`halted_because` parameter.
+
+```rb
+def reject(reason)
+  halt! 'We do not reject articles unless the reason is important' \
+    unless reason =~ /important/i
+end
+```
+
+The traditional `halt` (without the exclamation mark) is still supported
+too. This just prevents the state change without raising an
+exception.
+
+You can check `halted?` and `halted_because` values later.
+
+### Hook order
+
+The whole event sequence is as follows:
+
+    * before_transition
+    * event specific action
+    * on_transition (if action did not halt)
+    * on_exit
+    * 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
+-------------------------
+
+You can generate a graphical representation of the workflow for
+a particular class for documentation purposes.
+Use `Workflow::create_workflow_diagram(class)` in your rake task like:
+
+```rb
+namespace :doc do
+  desc "Generate a workflow graph for a model passed e.g. as 'MODEL=Order'."
+  task :workflow => :environment do
+    require 'workflow/draw'
+    Workflow::Draw::workflow_diagram(ENV['MODEL'].constantize)
+  end
+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
+
+* 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
+* 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
+
+* extract persistence adapters, Rails/ActiveRecord integration is now a separate gem
+  workflow-activerecord
+
+Support, Participation
+----------------------
+
+### Reporting bugs
+
+<http://github.com/geekq/workflow/issues>
+
+### Development Setup
+
+```sh
+sudo apt-get install graphviz # Linux
+brew install graphviz # Mac OS
+cd workflow
+gem install bundler
+bundle install
+# run all the tests
+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
+integration with https://github.com/activeadmin/activeadmin[ActiveAdmin].
+
+### About
+
+Author: Vladimir Dobriakov, <https://infrastructure-as-code.de>
+
+Copyright (c) 2010-2024 Vladimir Dobriakov and Contributors
+
+Copyright (c) 2008-2009 Vodafone
+
+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 = "2.0.2"
+  VERSION = "3.1.0.pre"
 end