state_machine_updated_for_ruby_3_2 2.0.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/.gitignore +10 -0
- data/.travis.yml +72 -0
- data/.yardopts +5 -0
- data/Appraisals +491 -0
- data/CHANGELOG.md +506 -0
- data/Dockerfile +13 -0
- data/Gemfile +4 -0
- data/LICENSE +20 -0
- data/README.md +1244 -0
- data/Rakefile +41 -0
- data/examples/AutoShop_state.png +0 -0
- data/examples/Car_state.png +0 -0
- data/examples/Gemfile +5 -0
- data/examples/Gemfile.lock +14 -0
- data/examples/TrafficLight_state.png +0 -0
- data/examples/Vehicle_state.png +0 -0
- data/examples/auto_shop.rb +13 -0
- data/examples/car.rb +21 -0
- data/examples/doc/AutoShop.html +2856 -0
- data/examples/doc/AutoShop_state.png +0 -0
- data/examples/doc/Car.html +919 -0
- data/examples/doc/Car_state.png +0 -0
- data/examples/doc/TrafficLight.html +2230 -0
- data/examples/doc/TrafficLight_state.png +0 -0
- data/examples/doc/Vehicle.html +7921 -0
- data/examples/doc/Vehicle_state.png +0 -0
- data/examples/doc/_index.html +136 -0
- data/examples/doc/class_list.html +47 -0
- data/examples/doc/css/common.css +1 -0
- data/examples/doc/css/full_list.css +55 -0
- data/examples/doc/css/style.css +322 -0
- data/examples/doc/file_list.html +46 -0
- data/examples/doc/frames.html +13 -0
- data/examples/doc/index.html +136 -0
- data/examples/doc/js/app.js +205 -0
- data/examples/doc/js/full_list.js +173 -0
- data/examples/doc/js/jquery.js +16 -0
- data/examples/doc/method_list.html +734 -0
- data/examples/doc/top-level-namespace.html +105 -0
- data/examples/merb-rest/controller.rb +51 -0
- data/examples/merb-rest/model.rb +28 -0
- data/examples/merb-rest/view_edit.html.erb +24 -0
- data/examples/merb-rest/view_index.html.erb +23 -0
- data/examples/merb-rest/view_new.html.erb +13 -0
- data/examples/merb-rest/view_show.html.erb +17 -0
- data/examples/rails-rest/controller.rb +43 -0
- data/examples/rails-rest/migration.rb +7 -0
- data/examples/rails-rest/model.rb +23 -0
- data/examples/rails-rest/view__form.html.erb +34 -0
- data/examples/rails-rest/view_edit.html.erb +6 -0
- data/examples/rails-rest/view_index.html.erb +25 -0
- data/examples/rails-rest/view_new.html.erb +5 -0
- data/examples/rails-rest/view_show.html.erb +19 -0
- data/examples/traffic_light.rb +9 -0
- data/examples/vehicle.rb +33 -0
- data/gemfiles/active_model_3.0.0.gemfile +7 -0
- data/gemfiles/active_model_3.0.0.gemfile.lock +35 -0
- data/gemfiles/active_model_3.0.5.gemfile +7 -0
- data/gemfiles/active_model_3.0.5.gemfile.lock +35 -0
- data/gemfiles/active_model_3.1.1.gemfile +7 -0
- data/gemfiles/active_model_3.1.1.gemfile.lock +36 -0
- data/gemfiles/active_model_3.2.1.gemfile +7 -0
- data/gemfiles/active_model_3.2.12.gemfile +7 -0
- data/gemfiles/active_model_3.2.12.gemfile.lock +36 -0
- data/gemfiles/active_model_3.2.13.rc1.gemfile +7 -0
- data/gemfiles/active_model_3.2.13.rc1.gemfile.lock +36 -0
- data/gemfiles/active_model_4.0.0.gemfile +9 -0
- data/gemfiles/active_model_4.0.0.gemfile.lock +78 -0
- data/gemfiles/active_record_2.0.0.gemfile +9 -0
- data/gemfiles/active_record_2.0.0.gemfile.lock +39 -0
- data/gemfiles/active_record_2.0.5.gemfile +9 -0
- data/gemfiles/active_record_2.0.5.gemfile.lock +39 -0
- data/gemfiles/active_record_2.1.0.gemfile +9 -0
- data/gemfiles/active_record_2.1.0.gemfile.lock +39 -0
- data/gemfiles/active_record_2.1.2.gemfile +9 -0
- data/gemfiles/active_record_2.1.2.gemfile.lock +39 -0
- data/gemfiles/active_record_2.2.3.gemfile +9 -0
- data/gemfiles/active_record_2.2.3.gemfile.lock +39 -0
- data/gemfiles/active_record_2.3.12.gemfile +9 -0
- data/gemfiles/active_record_2.3.12.gemfile.lock +39 -0
- data/gemfiles/active_record_2.3.5.gemfile +9 -0
- data/gemfiles/active_record_2.3.5.gemfile.lock +39 -0
- data/gemfiles/active_record_3.0.0.gemfile +9 -0
- data/gemfiles/active_record_3.0.0.gemfile.lock +51 -0
- data/gemfiles/active_record_3.0.5.gemfile +9 -0
- data/gemfiles/active_record_3.0.5.gemfile.lock +50 -0
- data/gemfiles/active_record_3.1.1.gemfile +9 -0
- data/gemfiles/active_record_3.1.1.gemfile.lock +51 -0
- data/gemfiles/active_record_3.2.12.gemfile +9 -0
- data/gemfiles/active_record_3.2.12.gemfile.lock +51 -0
- data/gemfiles/active_record_3.2.13.rc1.gemfile +9 -0
- data/gemfiles/active_record_3.2.13.rc1.gemfile.lock +51 -0
- data/gemfiles/active_record_4.0.0.gemfile +11 -0
- data/gemfiles/active_record_4.0.0.gemfile.lock +83 -0
- data/gemfiles/data_mapper_0.10.2.gemfile +13 -0
- data/gemfiles/data_mapper_0.10.2.gemfile.lock +56 -0
- data/gemfiles/data_mapper_0.9.11.gemfile +13 -0
- data/gemfiles/data_mapper_0.9.11.gemfile.lock +71 -0
- data/gemfiles/data_mapper_0.9.4.gemfile +12 -0
- data/gemfiles/data_mapper_0.9.4.gemfile.lock +70 -0
- data/gemfiles/data_mapper_0.9.7.gemfile +13 -0
- data/gemfiles/data_mapper_0.9.7.gemfile.lock +67 -0
- data/gemfiles/data_mapper_1.0.0.gemfile +12 -0
- data/gemfiles/data_mapper_1.0.0.gemfile.lock +63 -0
- data/gemfiles/data_mapper_1.0.1.gemfile +12 -0
- data/gemfiles/data_mapper_1.0.1.gemfile.lock +63 -0
- data/gemfiles/data_mapper_1.0.2.gemfile +12 -0
- data/gemfiles/data_mapper_1.0.2.gemfile.lock +63 -0
- data/gemfiles/data_mapper_1.1.0.gemfile +12 -0
- data/gemfiles/data_mapper_1.1.0.gemfile.lock +61 -0
- data/gemfiles/data_mapper_1.2.0.gemfile +12 -0
- data/gemfiles/data_mapper_1.2.0.gemfile.lock +61 -0
- data/gemfiles/default.gemfile +7 -0
- data/gemfiles/default.gemfile.lock +27 -0
- data/gemfiles/graphviz_0.9.17.gemfile +7 -0
- data/gemfiles/graphviz_0.9.17.gemfile.lock +29 -0
- data/gemfiles/graphviz_0.9.21.gemfile +7 -0
- data/gemfiles/graphviz_0.9.21.gemfile.lock +29 -0
- data/gemfiles/graphviz_1.0.0.gemfile +7 -0
- data/gemfiles/graphviz_1.0.0.gemfile.lock +29 -0
- data/gemfiles/graphviz_1.0.3.gemfile +7 -0
- data/gemfiles/graphviz_1.0.3.gemfile.lock +29 -0
- data/gemfiles/graphviz_1.0.8.gemfile +7 -0
- data/gemfiles/graphviz_1.0.8.gemfile.lock +29 -0
- data/gemfiles/mongo_mapper_0.10.0.gemfile +8 -0
- data/gemfiles/mongo_mapper_0.10.0.gemfile.lock +47 -0
- data/gemfiles/mongo_mapper_0.11.2.gemfile +9 -0
- data/gemfiles/mongo_mapper_0.11.2.gemfile.lock +48 -0
- data/gemfiles/mongo_mapper_0.12.0.gemfile +9 -0
- data/gemfiles/mongo_mapper_0.12.0.gemfile.lock +48 -0
- data/gemfiles/mongo_mapper_0.5.5.gemfile +8 -0
- data/gemfiles/mongo_mapper_0.5.5.gemfile.lock +36 -0
- data/gemfiles/mongo_mapper_0.5.8.gemfile +8 -0
- data/gemfiles/mongo_mapper_0.5.8.gemfile.lock +36 -0
- data/gemfiles/mongo_mapper_0.6.0.gemfile +8 -0
- data/gemfiles/mongo_mapper_0.6.0.gemfile.lock +36 -0
- data/gemfiles/mongo_mapper_0.6.10.gemfile +8 -0
- data/gemfiles/mongo_mapper_0.6.10.gemfile.lock +36 -0
- data/gemfiles/mongo_mapper_0.7.0.gemfile +8 -0
- data/gemfiles/mongo_mapper_0.7.0.gemfile.lock +36 -0
- data/gemfiles/mongo_mapper_0.7.5.gemfile +8 -0
- data/gemfiles/mongo_mapper_0.7.5.gemfile.lock +39 -0
- data/gemfiles/mongo_mapper_0.8.0.gemfile +10 -0
- data/gemfiles/mongo_mapper_0.8.0.gemfile.lock +43 -0
- data/gemfiles/mongo_mapper_0.8.3.gemfile +10 -0
- data/gemfiles/mongo_mapper_0.8.3.gemfile.lock +43 -0
- data/gemfiles/mongo_mapper_0.8.4.gemfile +8 -0
- data/gemfiles/mongo_mapper_0.8.4.gemfile.lock +42 -0
- data/gemfiles/mongo_mapper_0.8.6.gemfile +8 -0
- data/gemfiles/mongo_mapper_0.8.6.gemfile.lock +42 -0
- data/gemfiles/mongo_mapper_0.9.0.gemfile +7 -0
- data/gemfiles/mongo_mapper_0.9.0.gemfile.lock +45 -0
- data/gemfiles/mongoid_2.0.0.gemfile +9 -0
- data/gemfiles/mongoid_2.0.0.gemfile.lock +49 -0
- data/gemfiles/mongoid_2.1.4.gemfile +9 -0
- data/gemfiles/mongoid_2.1.4.gemfile.lock +47 -0
- data/gemfiles/mongoid_2.2.4.gemfile +9 -0
- data/gemfiles/mongoid_2.2.4.gemfile.lock +47 -0
- data/gemfiles/mongoid_2.3.3.gemfile +9 -0
- data/gemfiles/mongoid_2.3.3.gemfile.lock +47 -0
- data/gemfiles/mongoid_2.4.0.gemfile +9 -0
- data/gemfiles/mongoid_2.4.0.gemfile.lock +47 -0
- data/gemfiles/mongoid_2.4.10.gemfile +9 -0
- data/gemfiles/mongoid_2.4.10.gemfile.lock +47 -0
- data/gemfiles/mongoid_2.5.2.gemfile +9 -0
- data/gemfiles/mongoid_2.5.2.gemfile.lock +47 -0
- data/gemfiles/mongoid_2.6.0.gemfile +9 -0
- data/gemfiles/mongoid_2.6.0.gemfile.lock +47 -0
- data/gemfiles/mongoid_3.0.0.gemfile +8 -0
- data/gemfiles/mongoid_3.0.0.gemfile.lock +45 -0
- data/gemfiles/mongoid_3.0.22.gemfile +8 -0
- data/gemfiles/mongoid_3.0.22.gemfile.lock +45 -0
- data/gemfiles/mongoid_3.1.0.gemfile +8 -0
- data/gemfiles/mongoid_3.1.0.gemfile.lock +45 -0
- data/gemfiles/sequel_2.11.0.gemfile +9 -0
- data/gemfiles/sequel_2.11.0.gemfile.lock +33 -0
- data/gemfiles/sequel_2.12.0.gemfile +9 -0
- data/gemfiles/sequel_2.12.0.gemfile.lock +33 -0
- data/gemfiles/sequel_2.8.0.gemfile +9 -0
- data/gemfiles/sequel_2.8.0.gemfile.lock +33 -0
- data/gemfiles/sequel_3.0.0.gemfile +9 -0
- data/gemfiles/sequel_3.0.0.gemfile.lock +33 -0
- data/gemfiles/sequel_3.10.0.gemfile +9 -0
- data/gemfiles/sequel_3.10.0.gemfile.lock +33 -0
- data/gemfiles/sequel_3.13.0.gemfile +9 -0
- data/gemfiles/sequel_3.13.0.gemfile.lock +33 -0
- data/gemfiles/sequel_3.14.0.gemfile +9 -0
- data/gemfiles/sequel_3.14.0.gemfile.lock +33 -0
- data/gemfiles/sequel_3.23.0.gemfile +9 -0
- data/gemfiles/sequel_3.23.0.gemfile.lock +33 -0
- data/gemfiles/sequel_3.24.0.gemfile +9 -0
- data/gemfiles/sequel_3.24.0.gemfile.lock +33 -0
- data/gemfiles/sequel_3.29.0.gemfile +9 -0
- data/gemfiles/sequel_3.29.0.gemfile.lock +33 -0
- data/gemfiles/sequel_3.34.0.gemfile +9 -0
- data/gemfiles/sequel_3.34.0.gemfile.lock +33 -0
- data/gemfiles/sequel_3.35.0.gemfile +9 -0
- data/gemfiles/sequel_3.35.0.gemfile.lock +33 -0
- data/gemfiles/sequel_3.4.0.gemfile +9 -0
- data/gemfiles/sequel_3.4.0.gemfile.lock +33 -0
- data/gemfiles/sequel_3.44.0.gemfile +9 -0
- data/gemfiles/sequel_3.44.0.gemfile.lock +33 -0
- data/init.rb +1 -0
- data/lib/state_machine/assertions.rb +36 -0
- data/lib/state_machine/branch.rb +225 -0
- data/lib/state_machine/callback.rb +236 -0
- data/lib/state_machine/core.rb +12 -0
- data/lib/state_machine/core_ext/class/state_machine.rb +5 -0
- data/lib/state_machine/core_ext.rb +2 -0
- data/lib/state_machine/error.rb +13 -0
- data/lib/state_machine/eval_helpers.rb +87 -0
- data/lib/state_machine/event.rb +257 -0
- data/lib/state_machine/event_collection.rb +141 -0
- data/lib/state_machine/extensions.rb +149 -0
- data/lib/state_machine/graph.rb +92 -0
- data/lib/state_machine/helper_module.rb +17 -0
- data/lib/state_machine/initializers/merb.rb +1 -0
- data/lib/state_machine/initializers/rails.rb +25 -0
- data/lib/state_machine/initializers.rb +4 -0
- data/lib/state_machine/integrations/active_model/locale.rb +11 -0
- data/lib/state_machine/integrations/active_model/observer.rb +33 -0
- data/lib/state_machine/integrations/active_model/observer_update.rb +42 -0
- data/lib/state_machine/integrations/active_model/versions.rb +31 -0
- data/lib/state_machine/integrations/active_model.rb +585 -0
- data/lib/state_machine/integrations/active_record/locale.rb +20 -0
- data/lib/state_machine/integrations/active_record/versions.rb +123 -0
- data/lib/state_machine/integrations/active_record.rb +548 -0
- data/lib/state_machine/integrations/base.rb +100 -0
- data/lib/state_machine/integrations/data_mapper/observer.rb +210 -0
- data/lib/state_machine/integrations/data_mapper/versions.rb +85 -0
- data/lib/state_machine/integrations/data_mapper.rb +511 -0
- data/lib/state_machine/integrations/mongo_mapper/locale.rb +4 -0
- data/lib/state_machine/integrations/mongo_mapper/versions.rb +89 -0
- data/lib/state_machine/integrations/mongo_mapper.rb +389 -0
- data/lib/state_machine/integrations/mongoid/locale.rb +4 -0
- data/lib/state_machine/integrations/mongoid/versions.rb +81 -0
- data/lib/state_machine/integrations/mongoid.rb +461 -0
- data/lib/state_machine/integrations/sequel/versions.rb +95 -0
- data/lib/state_machine/integrations/sequel.rb +486 -0
- data/lib/state_machine/integrations.rb +121 -0
- data/lib/state_machine/machine.rb +2292 -0
- data/lib/state_machine/machine_collection.rb +86 -0
- data/lib/state_machine/macro_methods.rb +522 -0
- data/lib/state_machine/matcher.rb +123 -0
- data/lib/state_machine/matcher_helpers.rb +54 -0
- data/lib/state_machine/node_collection.rb +222 -0
- data/lib/state_machine/path.rb +120 -0
- data/lib/state_machine/path_collection.rb +90 -0
- data/lib/state_machine/state.rb +297 -0
- data/lib/state_machine/state_collection.rb +112 -0
- data/lib/state_machine/state_context.rb +138 -0
- data/lib/state_machine/transition.rb +470 -0
- data/lib/state_machine/transition_collection.rb +245 -0
- data/lib/state_machine/version.rb +3 -0
- data/lib/state_machine/yard/handlers/base.rb +32 -0
- data/lib/state_machine/yard/handlers/event.rb +25 -0
- data/lib/state_machine/yard/handlers/machine.rb +344 -0
- data/lib/state_machine/yard/handlers/state.rb +25 -0
- data/lib/state_machine/yard/handlers/transition.rb +47 -0
- data/lib/state_machine/yard/handlers.rb +12 -0
- data/lib/state_machine/yard/templates/default/class/html/setup.rb +30 -0
- data/lib/state_machine/yard/templates/default/class/html/state_machines.erb +12 -0
- data/lib/state_machine/yard/templates.rb +3 -0
- data/lib/state_machine/yard.rb +8 -0
- data/lib/state_machine.rb +8 -0
- data/lib/tasks/state_machine.rake +1 -0
- data/lib/tasks/state_machine.rb +30 -0
- data/lib/yard-state_machine.rb +2 -0
- data/state_machine.gemspec +23 -0
- data/test/files/en.yml +17 -0
- data/test/files/switch.rb +15 -0
- data/test/functional/state_machine_test.rb +1066 -0
- data/test/test_helper.rb +7 -0
- data/test/unit/assertions_test.rb +40 -0
- data/test/unit/branch_test.rb +969 -0
- data/test/unit/callback_test.rb +704 -0
- data/test/unit/error_test.rb +43 -0
- data/test/unit/eval_helpers_test.rb +272 -0
- data/test/unit/event_collection_test.rb +398 -0
- data/test/unit/event_test.rb +1196 -0
- data/test/unit/graph_test.rb +98 -0
- data/test/unit/helper_module_test.rb +17 -0
- data/test/unit/integrations/active_model_test.rb +1245 -0
- data/test/unit/integrations/active_record_test.rb +2551 -0
- data/test/unit/integrations/base_test.rb +104 -0
- data/test/unit/integrations/data_mapper_test.rb +2194 -0
- data/test/unit/integrations/mongo_mapper_test.rb +2026 -0
- data/test/unit/integrations/mongoid_test.rb +2309 -0
- data/test/unit/integrations/sequel_test.rb +1896 -0
- data/test/unit/integrations_test.rb +83 -0
- data/test/unit/invalid_event_test.rb +20 -0
- data/test/unit/invalid_parallel_transition_test.rb +18 -0
- data/test/unit/invalid_transition_test.rb +115 -0
- data/test/unit/machine_collection_test.rb +603 -0
- data/test/unit/machine_test.rb +3407 -0
- data/test/unit/matcher_helpers_test.rb +37 -0
- data/test/unit/matcher_test.rb +155 -0
- data/test/unit/node_collection_test.rb +362 -0
- data/test/unit/path_collection_test.rb +266 -0
- data/test/unit/path_test.rb +485 -0
- data/test/unit/state_collection_test.rb +352 -0
- data/test/unit/state_context_test.rb +441 -0
- data/test/unit/state_machine_test.rb +31 -0
- data/test/unit/state_test.rb +1101 -0
- data/test/unit/transition_collection_test.rb +2168 -0
- data/test/unit/transition_test.rb +1558 -0
- metadata +450 -0
@@ -0,0 +1,236 @@
|
|
1
|
+
require 'state_machine/branch'
|
2
|
+
require 'state_machine/eval_helpers'
|
3
|
+
|
4
|
+
module StateMachine
|
5
|
+
# Callbacks represent hooks into objects that allow logic to be triggered
|
6
|
+
# before, after, or around a specific set of transitions.
|
7
|
+
class Callback
|
8
|
+
include EvalHelpers
|
9
|
+
|
10
|
+
class << self
|
11
|
+
# Determines whether to automatically bind the callback to the object
|
12
|
+
# being transitioned. This only applies to callbacks that are defined as
|
13
|
+
# lambda blocks (or Procs). Some integrations, such as DataMapper, handle
|
14
|
+
# callbacks by executing them bound to the object involved, while other
|
15
|
+
# integrations, such as ActiveRecord, pass the object as an argument to
|
16
|
+
# the callback. This can be configured on an application-wide basis by
|
17
|
+
# setting this configuration to +true+ or +false+. The default value
|
18
|
+
# is +false+.
|
19
|
+
#
|
20
|
+
# *Note* that the DataMapper and Sequel integrations automatically
|
21
|
+
# configure this value on a per-callback basis, so it does not have to
|
22
|
+
# be enabled application-wide.
|
23
|
+
#
|
24
|
+
# == Examples
|
25
|
+
#
|
26
|
+
# When not bound to the object:
|
27
|
+
#
|
28
|
+
# class Vehicle
|
29
|
+
# state_machine do
|
30
|
+
# before_transition do |vehicle|
|
31
|
+
# vehicle.set_alarm
|
32
|
+
# end
|
33
|
+
# end
|
34
|
+
#
|
35
|
+
# def set_alarm
|
36
|
+
# ...
|
37
|
+
# end
|
38
|
+
# end
|
39
|
+
#
|
40
|
+
# When bound to the object:
|
41
|
+
#
|
42
|
+
# StateMachine::Callback.bind_to_object = true
|
43
|
+
#
|
44
|
+
# class Vehicle
|
45
|
+
# state_machine do
|
46
|
+
# before_transition do
|
47
|
+
# self.set_alarm
|
48
|
+
# end
|
49
|
+
# end
|
50
|
+
#
|
51
|
+
# def set_alarm
|
52
|
+
# ...
|
53
|
+
# end
|
54
|
+
# end
|
55
|
+
attr_accessor :bind_to_object
|
56
|
+
|
57
|
+
# The application-wide terminator to use for callbacks when not
|
58
|
+
# explicitly defined. Terminators determine whether to cancel a
|
59
|
+
# callback chain based on the return value of the callback.
|
60
|
+
#
|
61
|
+
# See StateMachine::Callback#terminator for more information.
|
62
|
+
attr_accessor :terminator
|
63
|
+
end
|
64
|
+
|
65
|
+
# The type of callback chain this callback is for. This can be one of the
|
66
|
+
# following:
|
67
|
+
# * +before+
|
68
|
+
# * +after+
|
69
|
+
# * +around+
|
70
|
+
# * +failure+
|
71
|
+
attr_accessor :type
|
72
|
+
|
73
|
+
# An optional block for determining whether to cancel the callback chain
|
74
|
+
# based on the return value of the callback. By default, the callback
|
75
|
+
# chain never cancels based on the return value (i.e. there is no implicit
|
76
|
+
# terminator). Certain integrations, such as ActiveRecord and Sequel,
|
77
|
+
# change this default value.
|
78
|
+
#
|
79
|
+
# == Examples
|
80
|
+
#
|
81
|
+
# Canceling the callback chain without a terminator:
|
82
|
+
#
|
83
|
+
# class Vehicle
|
84
|
+
# state_machine do
|
85
|
+
# before_transition do |vehicle|
|
86
|
+
# throw :halt
|
87
|
+
# end
|
88
|
+
# end
|
89
|
+
# end
|
90
|
+
#
|
91
|
+
# Canceling the callback chain with a terminator value of +false+:
|
92
|
+
#
|
93
|
+
# class Vehicle
|
94
|
+
# state_machine do
|
95
|
+
# before_transition do |vehicle|
|
96
|
+
# false
|
97
|
+
# end
|
98
|
+
# end
|
99
|
+
# end
|
100
|
+
attr_reader :terminator
|
101
|
+
|
102
|
+
# The branch that determines whether or not this callback can be invoked
|
103
|
+
# based on the context of the transition. The event, from state, and
|
104
|
+
# to state must all match in order for the branch to pass.
|
105
|
+
#
|
106
|
+
# See StateMachine::Branch for more information.
|
107
|
+
attr_reader :branch
|
108
|
+
|
109
|
+
# Creates a new callback that can get called based on the configured
|
110
|
+
# options.
|
111
|
+
#
|
112
|
+
# In addition to the possible configuration options for branches, the
|
113
|
+
# following options can be configured:
|
114
|
+
# * <tt>:bind_to_object</tt> - Whether to bind the callback to the object involved.
|
115
|
+
# If set to false, the object will be passed as a parameter instead.
|
116
|
+
# Default is integration-specific or set to the application default.
|
117
|
+
# * <tt>:terminator</tt> - A block/proc that determines what callback
|
118
|
+
# results should cause the callback chain to halt (if not using the
|
119
|
+
# default <tt>throw :halt</tt> technique).
|
120
|
+
#
|
121
|
+
# More information about how those options affect the behavior of the
|
122
|
+
# callback can be found in their attribute definitions.
|
123
|
+
def initialize(type, *args, &block)
|
124
|
+
@type = type
|
125
|
+
raise ArgumentError, 'Type must be :before, :after, :around, or :failure' unless [:before, :after, :around, :failure].include?(type)
|
126
|
+
|
127
|
+
options = args.last.is_a?(Hash) ? args.pop : {}
|
128
|
+
@methods = args
|
129
|
+
@methods.concat(Array(options.delete(:do)))
|
130
|
+
@methods << block if block_given?
|
131
|
+
raise ArgumentError, 'Method(s) for callback must be specified' unless @methods.any?
|
132
|
+
|
133
|
+
options = {:bind_to_object => self.class.bind_to_object, :terminator => self.class.terminator}.merge(options)
|
134
|
+
|
135
|
+
# Proxy lambda blocks so that they're bound to the object
|
136
|
+
bind_to_object = options.delete(:bind_to_object)
|
137
|
+
@methods.map! do |method|
|
138
|
+
bind_to_object && method.is_a?(Proc) ? bound_method(method) : method
|
139
|
+
end
|
140
|
+
|
141
|
+
@terminator = options.delete(:terminator)
|
142
|
+
@branch = Branch.new(options)
|
143
|
+
end
|
144
|
+
|
145
|
+
# Gets a list of the states known to this callback by looking at the
|
146
|
+
# branch's known states
|
147
|
+
def known_states
|
148
|
+
branch.known_states
|
149
|
+
end
|
150
|
+
|
151
|
+
# Runs the callback as long as the transition context matches the branch
|
152
|
+
# requirements configured for this callback. If a block is provided, it
|
153
|
+
# will be called when the last method has run.
|
154
|
+
#
|
155
|
+
# If a terminator has been configured and it matches the result from the
|
156
|
+
# evaluated method, then the callback chain should be halted.
|
157
|
+
def call(object, context = {}, *args, &block)
|
158
|
+
if @branch.matches?(object, context)
|
159
|
+
run_methods(object, context, 0, *args, &block)
|
160
|
+
true
|
161
|
+
else
|
162
|
+
false
|
163
|
+
end
|
164
|
+
end
|
165
|
+
|
166
|
+
private
|
167
|
+
# Runs all of the methods configured for this callback.
|
168
|
+
#
|
169
|
+
# When running +around+ callbacks, this will evaluate each method and
|
170
|
+
# yield when the last method has yielded. The callback will only halt if
|
171
|
+
# one of the methods does not yield.
|
172
|
+
#
|
173
|
+
# For all other types of callbacks, this will evaluate each method in
|
174
|
+
# order. The callback will only halt if the resulting value from the
|
175
|
+
# method passes the terminator.
|
176
|
+
def run_methods(object, context = {}, index = 0, *args, &block)
|
177
|
+
if type == :around
|
178
|
+
if current_method = @methods[index]
|
179
|
+
yielded = false
|
180
|
+
evaluate_method(object, current_method, *args) do
|
181
|
+
yielded = true
|
182
|
+
run_methods(object, context, index + 1, *args, &block)
|
183
|
+
end
|
184
|
+
|
185
|
+
throw :halt unless yielded
|
186
|
+
else
|
187
|
+
yield if block_given?
|
188
|
+
end
|
189
|
+
else
|
190
|
+
@methods.each do |method|
|
191
|
+
result = evaluate_method(object, method, *args)
|
192
|
+
throw :halt if @terminator && @terminator.call(result)
|
193
|
+
end
|
194
|
+
end
|
195
|
+
end
|
196
|
+
|
197
|
+
# Generates a method that can be bound to the object being transitioned
|
198
|
+
# when the callback is invoked
|
199
|
+
def bound_method(block)
|
200
|
+
type = self.type
|
201
|
+
arity = block.arity
|
202
|
+
arity += 1 if arity >= 0 # Make sure the object gets passed
|
203
|
+
arity += 1 if arity == 1 && type == :around # Make sure the block gets passed
|
204
|
+
|
205
|
+
method = if RUBY_VERSION >= '1.9'
|
206
|
+
lambda do |object, *args|
|
207
|
+
object.instance_exec(*args, &block)
|
208
|
+
end
|
209
|
+
else
|
210
|
+
# Generate a thread-safe unbound method that can be used on any object.
|
211
|
+
# This is a workaround for not having Ruby 1.9's instance_exec
|
212
|
+
unbound_method = Object.class_eval do
|
213
|
+
time = Time.now
|
214
|
+
method_name = "__bind_#{time.to_i}_#{time.usec}"
|
215
|
+
define_method(method_name, &block)
|
216
|
+
method = instance_method(method_name)
|
217
|
+
remove_method(method_name)
|
218
|
+
method
|
219
|
+
end
|
220
|
+
|
221
|
+
# Proxy calls to the method so that the method can be bound *and*
|
222
|
+
# the arguments are adjusted
|
223
|
+
lambda do |object, *args|
|
224
|
+
unbound_method.bind(object).call(*args)
|
225
|
+
end
|
226
|
+
end
|
227
|
+
|
228
|
+
# Proxy arity to the original block
|
229
|
+
(class << method; self; end).class_eval do
|
230
|
+
define_method(:arity) { arity }
|
231
|
+
end
|
232
|
+
|
233
|
+
method
|
234
|
+
end
|
235
|
+
end
|
236
|
+
end
|
@@ -0,0 +1,12 @@
|
|
1
|
+
module StateMachine
|
2
|
+
# Graphing extensions aren't required, so they're loaded when referenced
|
3
|
+
autoload :Graph, 'state_machine/graph'
|
4
|
+
end
|
5
|
+
|
6
|
+
# Load all of the core implementation required to use state_machine. This
|
7
|
+
# includes:
|
8
|
+
# * StateMachine::MacroMethods which adds the state_machine DSL to your class
|
9
|
+
# * A set of initializers for setting state_machine defaults based on the current
|
10
|
+
# running environment (such as within Rails)
|
11
|
+
require 'state_machine/macro_methods'
|
12
|
+
require 'state_machine/initializers'
|
@@ -0,0 +1,13 @@
|
|
1
|
+
module StateMachine
|
2
|
+
# An error occurred during a state machine invocation
|
3
|
+
class Error < StandardError
|
4
|
+
# The object that failed
|
5
|
+
attr_reader :object
|
6
|
+
|
7
|
+
def initialize(object, message = nil) #:nodoc:
|
8
|
+
@object = object
|
9
|
+
|
10
|
+
super(message)
|
11
|
+
end
|
12
|
+
end
|
13
|
+
end
|
@@ -0,0 +1,87 @@
|
|
1
|
+
module StateMachine
|
2
|
+
# Provides a set of helper methods for evaluating methods within the context
|
3
|
+
# of an object.
|
4
|
+
module EvalHelpers
|
5
|
+
# Evaluates one of several different types of methods within the context
|
6
|
+
# of the given object. Methods can be one of the following types:
|
7
|
+
# * Symbol
|
8
|
+
# * Method / Proc
|
9
|
+
# * String
|
10
|
+
#
|
11
|
+
# == Examples
|
12
|
+
#
|
13
|
+
# Below are examples of the various ways that a method can be evaluated
|
14
|
+
# on an object:
|
15
|
+
#
|
16
|
+
# class Person
|
17
|
+
# def initialize(name)
|
18
|
+
# @name = name
|
19
|
+
# end
|
20
|
+
#
|
21
|
+
# def name
|
22
|
+
# @name
|
23
|
+
# end
|
24
|
+
# end
|
25
|
+
#
|
26
|
+
# class PersonCallback
|
27
|
+
# def self.run(person)
|
28
|
+
# person.name
|
29
|
+
# end
|
30
|
+
# end
|
31
|
+
#
|
32
|
+
# person = Person.new('John Smith')
|
33
|
+
#
|
34
|
+
# evaluate_method(person, :name) # => "John Smith"
|
35
|
+
# evaluate_method(person, PersonCallback.method(:run)) # => "John Smith"
|
36
|
+
# evaluate_method(person, Proc.new {|person| person.name}) # => "John Smith"
|
37
|
+
# evaluate_method(person, lambda {|person| person.name}) # => "John Smith"
|
38
|
+
# evaluate_method(person, '@name') # => "John Smith"
|
39
|
+
#
|
40
|
+
# == Additional arguments
|
41
|
+
#
|
42
|
+
# Additional arguments can be passed to the methods being evaluated. If
|
43
|
+
# the method defines additional arguments other than the object context,
|
44
|
+
# then all arguments are required.
|
45
|
+
#
|
46
|
+
# For example,
|
47
|
+
#
|
48
|
+
# person = Person.new('John Smith')
|
49
|
+
#
|
50
|
+
# evaluate_method(person, lambda {|person| person.name}, 21) # => "John Smith"
|
51
|
+
# evaluate_method(person, lambda {|person, age| "#{person.name} is #{age}"}, 21) # => "John Smith is 21"
|
52
|
+
# evaluate_method(person, lambda {|person, age| "#{person.name} is #{age}"}, 21, 'male') # => ArgumentError: wrong number of arguments (3 for 2)
|
53
|
+
def evaluate_method(object, method, *args, &block)
|
54
|
+
case method
|
55
|
+
when Symbol
|
56
|
+
klass = (class << object; self; end)
|
57
|
+
args = [] if (klass.method_defined?(method) || klass.private_method_defined?(method)) && object.method(method).arity == 0
|
58
|
+
object.send(method, *args, &block)
|
59
|
+
when Proc, Method
|
60
|
+
args.unshift(object)
|
61
|
+
arity = method.arity
|
62
|
+
|
63
|
+
# Procs don't support blocks in < Ruby 1.9, so it's tacked on as an
|
64
|
+
# argument for consistency across versions of Ruby
|
65
|
+
if block_given? && Proc === method && arity != 0
|
66
|
+
if [1, 2].include?(arity)
|
67
|
+
# Force the block to be either the only argument or the 2nd one
|
68
|
+
# after the object (may mean additional arguments get discarded)
|
69
|
+
args = args[0, arity - 1] + [block]
|
70
|
+
else
|
71
|
+
# Tack the block to the end of the args
|
72
|
+
args << block
|
73
|
+
end
|
74
|
+
else
|
75
|
+
# These method types are only called with 0, 1, or n arguments
|
76
|
+
args = args[0, arity] if [0, 1].include?(arity)
|
77
|
+
end
|
78
|
+
|
79
|
+
method.is_a?(Proc) ? method.call(*args) : method.call(*args, &block)
|
80
|
+
when String
|
81
|
+
eval(method, object.instance_eval {binding}, &block)
|
82
|
+
else
|
83
|
+
raise ArgumentError, 'Methods must be a symbol denoting the method to call, a block to be invoked, or a string to be evaluated'
|
84
|
+
end
|
85
|
+
end
|
86
|
+
end
|
87
|
+
end
|
@@ -0,0 +1,257 @@
|
|
1
|
+
require 'state_machine/transition'
|
2
|
+
require 'state_machine/branch'
|
3
|
+
require 'state_machine/assertions'
|
4
|
+
require 'state_machine/matcher_helpers'
|
5
|
+
require 'state_machine/error'
|
6
|
+
|
7
|
+
module StateMachine
|
8
|
+
# An invalid event was specified
|
9
|
+
class InvalidEvent < Error
|
10
|
+
# The event that was attempted to be run
|
11
|
+
attr_reader :event
|
12
|
+
|
13
|
+
def initialize(object, event_name) #:nodoc:
|
14
|
+
@event = event_name
|
15
|
+
|
16
|
+
super(object, "#{event.inspect} is an unknown state machine event")
|
17
|
+
end
|
18
|
+
end
|
19
|
+
|
20
|
+
# An event defines an action that transitions an attribute from one state to
|
21
|
+
# another. The state that an attribute is transitioned to depends on the
|
22
|
+
# branches configured for the event.
|
23
|
+
class Event
|
24
|
+
include Assertions
|
25
|
+
include MatcherHelpers
|
26
|
+
|
27
|
+
# The state machine for which this event is defined
|
28
|
+
attr_accessor :machine
|
29
|
+
|
30
|
+
# The name of the event
|
31
|
+
attr_reader :name
|
32
|
+
|
33
|
+
# The fully-qualified name of the event, scoped by the machine's namespace
|
34
|
+
attr_reader :qualified_name
|
35
|
+
|
36
|
+
# The human-readable name for the event
|
37
|
+
attr_writer :human_name
|
38
|
+
|
39
|
+
# The list of branches that determine what state this event transitions
|
40
|
+
# objects to when fired
|
41
|
+
attr_reader :branches
|
42
|
+
|
43
|
+
# A list of all of the states known to this event using the configured
|
44
|
+
# branches/transitions as the source
|
45
|
+
attr_reader :known_states
|
46
|
+
|
47
|
+
# Creates a new event within the context of the given machine
|
48
|
+
#
|
49
|
+
# Configuration options:
|
50
|
+
# * <tt>:human_name</tt> - The human-readable version of this event's name
|
51
|
+
def initialize(machine, name, options = {}) #:nodoc:
|
52
|
+
assert_valid_keys(options, :human_name)
|
53
|
+
|
54
|
+
@machine = machine
|
55
|
+
@name = name
|
56
|
+
@qualified_name = machine.namespace ? :"#{name}_#{machine.namespace}" : name
|
57
|
+
@human_name = options[:human_name] || @name.to_s.tr('_', ' ')
|
58
|
+
reset
|
59
|
+
|
60
|
+
# Output a warning if another event has a conflicting qualified name
|
61
|
+
if conflict = machine.owner_class.state_machines.detect {|other_name, other_machine| other_machine != @machine && other_machine.events[qualified_name, :qualified_name]}
|
62
|
+
name, other_machine = conflict
|
63
|
+
warn "Event #{qualified_name.inspect} for #{machine.name.inspect} is already defined in #{other_machine.name.inspect}"
|
64
|
+
else
|
65
|
+
add_actions
|
66
|
+
end
|
67
|
+
end
|
68
|
+
|
69
|
+
# Creates a copy of this event in addition to the list of associated
|
70
|
+
# branches to prevent conflicts across events within a class hierarchy.
|
71
|
+
def initialize_copy(orig) #:nodoc:
|
72
|
+
super
|
73
|
+
@branches = @branches.dup
|
74
|
+
@known_states = @known_states.dup
|
75
|
+
end
|
76
|
+
|
77
|
+
# Transforms the event name into a more human-readable format, such as
|
78
|
+
# "turn on" instead of "turn_on"
|
79
|
+
def human_name(klass = @machine.owner_class)
|
80
|
+
@human_name.is_a?(Proc) ? @human_name.call(self, klass) : @human_name
|
81
|
+
end
|
82
|
+
|
83
|
+
# Evaluates the given block within the context of this event. This simply
|
84
|
+
# provides a DSL-like syntax for defining transitions.
|
85
|
+
def context(&block)
|
86
|
+
instance_eval(&block)
|
87
|
+
end
|
88
|
+
|
89
|
+
# Creates a new transition that determines what to change the current state
|
90
|
+
# to when this event fires.
|
91
|
+
#
|
92
|
+
# Since this transition is being defined within an event context, you do
|
93
|
+
# *not* need to specify the <tt>:on</tt> option for the transition. For
|
94
|
+
# example:
|
95
|
+
#
|
96
|
+
# state_machine do
|
97
|
+
# event :ignite do
|
98
|
+
# transition :parked => :idling, :idling => same, :if => :seatbelt_on? # Transitions to :idling if seatbelt is on
|
99
|
+
# transition all => :parked, :unless => :seatbelt_on? # Transitions to :parked if seatbelt is off
|
100
|
+
# end
|
101
|
+
# end
|
102
|
+
#
|
103
|
+
# See StateMachine::Machine#transition for a description of the possible
|
104
|
+
# configurations for defining transitions.
|
105
|
+
def transition(options)
|
106
|
+
raise ArgumentError, 'Must specify as least one transition requirement' if options.empty?
|
107
|
+
|
108
|
+
# Only a certain subset of explicit options are allowed for transition
|
109
|
+
# requirements
|
110
|
+
assert_valid_keys(options, :from, :to, :except_from, :except_to, :if, :unless) if (options.keys - [:from, :to, :on, :except_from, :except_to, :except_on, :if, :unless]).empty?
|
111
|
+
|
112
|
+
branches << branch = Branch.new(options.merge(:on => name))
|
113
|
+
@known_states |= branch.known_states
|
114
|
+
branch
|
115
|
+
end
|
116
|
+
|
117
|
+
# Determines whether any transitions can be performed for this event based
|
118
|
+
# on the current state of the given object.
|
119
|
+
#
|
120
|
+
# If the event can't be fired, then this will return false, otherwise true.
|
121
|
+
#
|
122
|
+
# *Note* that this will not take the object context into account. Although
|
123
|
+
# a transition may be possible based on the state machine definition,
|
124
|
+
# object-specific behaviors (like validations) may prevent it from firing.
|
125
|
+
def can_fire?(object, requirements = {})
|
126
|
+
!transition_for(object, requirements).nil?
|
127
|
+
end
|
128
|
+
|
129
|
+
# Finds and builds the next transition that can be performed on the given
|
130
|
+
# object. If no transitions can be made, then this will return nil.
|
131
|
+
#
|
132
|
+
# Valid requirement options:
|
133
|
+
# * <tt>:from</tt> - One or more states being transitioned from. If none
|
134
|
+
# are specified, then this will be the object's current state.
|
135
|
+
# * <tt>:to</tt> - One or more states being transitioned to. If none are
|
136
|
+
# specified, then this will match any to state.
|
137
|
+
# * <tt>:guard</tt> - Whether to guard transitions with the if/unless
|
138
|
+
# conditionals defined for each one. Default is true.
|
139
|
+
def transition_for(object, requirements = {})
|
140
|
+
assert_valid_keys(requirements, :from, :to, :guard)
|
141
|
+
requirements[:from] = machine.states.match!(object).name unless custom_from_state = requirements.include?(:from)
|
142
|
+
|
143
|
+
branches.each do |branch|
|
144
|
+
if match = branch.match(object, requirements)
|
145
|
+
# Branch allows for the transition to occur
|
146
|
+
from = requirements[:from]
|
147
|
+
to = if match[:to].is_a?(LoopbackMatcher)
|
148
|
+
from
|
149
|
+
else
|
150
|
+
values = requirements.include?(:to) ? [requirements[:to]].flatten : [from] | machine.states.map {|state| state.name}
|
151
|
+
|
152
|
+
match[:to].filter(values).first
|
153
|
+
end
|
154
|
+
|
155
|
+
return Transition.new(object, machine, name, from, to, !custom_from_state)
|
156
|
+
end
|
157
|
+
end
|
158
|
+
|
159
|
+
# No transition matched
|
160
|
+
nil
|
161
|
+
end
|
162
|
+
|
163
|
+
# Attempts to perform the next available transition on the given object.
|
164
|
+
# If no transitions can be made, then this will return false, otherwise
|
165
|
+
# true.
|
166
|
+
#
|
167
|
+
# Any additional arguments are passed to the StateMachine::Transition#perform
|
168
|
+
# instance method.
|
169
|
+
def fire(object, *args)
|
170
|
+
machine.reset(object)
|
171
|
+
|
172
|
+
if transition = transition_for(object)
|
173
|
+
transition.perform(*args)
|
174
|
+
else
|
175
|
+
on_failure(object)
|
176
|
+
false
|
177
|
+
end
|
178
|
+
end
|
179
|
+
|
180
|
+
# Marks the object as invalid and runs any failure callbacks associated with
|
181
|
+
# this event. This should get called anytime this event fails to transition.
|
182
|
+
def on_failure(object)
|
183
|
+
state = machine.states.match!(object)
|
184
|
+
machine.invalidate(object, :state, :invalid_transition, [[:event, human_name(object.class)], [:state, state.human_name(object.class)]])
|
185
|
+
|
186
|
+
Transition.new(object, machine, name, state.name, state.name).run_callbacks(:before => false)
|
187
|
+
end
|
188
|
+
|
189
|
+
# Resets back to the initial state of the event, with no branches / known
|
190
|
+
# states associated. This allows you to redefine an event in situations
|
191
|
+
# where you either are re-using an existing state machine implementation
|
192
|
+
# or are subclassing machines.
|
193
|
+
def reset
|
194
|
+
@branches = []
|
195
|
+
@known_states = []
|
196
|
+
end
|
197
|
+
|
198
|
+
# Draws a representation of this event on the given graph. This will
|
199
|
+
# create 1 or more edges on the graph for each branch (i.e. transition)
|
200
|
+
# configured.
|
201
|
+
#
|
202
|
+
# Configuration options:
|
203
|
+
# * <tt>:human_name</tt> - Whether to use the event's human name for the
|
204
|
+
# node's label that gets drawn on the graph
|
205
|
+
def draw(graph, options = {})
|
206
|
+
valid_states = machine.states.by_priority.map {|state| state.name}
|
207
|
+
branches.each do |branch|
|
208
|
+
branch.draw(graph, options[:human_name] ? human_name : name, valid_states)
|
209
|
+
end
|
210
|
+
|
211
|
+
true
|
212
|
+
end
|
213
|
+
|
214
|
+
# Generates a nicely formatted description of this event's contents.
|
215
|
+
#
|
216
|
+
# For example,
|
217
|
+
#
|
218
|
+
# event = StateMachine::Event.new(machine, :park)
|
219
|
+
# event.transition all - :idling => :parked, :idling => same
|
220
|
+
# event # => #<StateMachine::Event name=:park transitions=[all - :idling => :parked, :idling => same]>
|
221
|
+
def inspect
|
222
|
+
transitions = branches.map do |branch|
|
223
|
+
branch.state_requirements.map do |state_requirement|
|
224
|
+
"#{state_requirement[:from].description} => #{state_requirement[:to].description}"
|
225
|
+
end * ', '
|
226
|
+
end
|
227
|
+
|
228
|
+
"#<#{self.class} name=#{name.inspect} transitions=[#{transitions * ', '}]>"
|
229
|
+
end
|
230
|
+
|
231
|
+
protected
|
232
|
+
# Add the various instance methods that can transition the object using
|
233
|
+
# the current event
|
234
|
+
def add_actions
|
235
|
+
# Checks whether the event can be fired on the current object
|
236
|
+
machine.define_helper(:instance, "can_#{qualified_name}?") do |machine, object, *args|
|
237
|
+
machine.event(name).can_fire?(object, *args)
|
238
|
+
end
|
239
|
+
|
240
|
+
# Gets the next transition that would be performed if the event were
|
241
|
+
# fired now
|
242
|
+
machine.define_helper(:instance, "#{qualified_name}_transition") do |machine, object, *args|
|
243
|
+
machine.event(name).transition_for(object, *args)
|
244
|
+
end
|
245
|
+
|
246
|
+
# Fires the event
|
247
|
+
machine.define_helper(:instance, qualified_name) do |machine, object, *args|
|
248
|
+
machine.event(name).fire(object, *args)
|
249
|
+
end
|
250
|
+
|
251
|
+
# Fires the event, raising an exception if it fails
|
252
|
+
machine.define_helper(:instance, "#{qualified_name}!") do |machine, object, *args|
|
253
|
+
object.send(qualified_name, *args) || raise(StateMachine::InvalidTransition.new(object, machine, name))
|
254
|
+
end
|
255
|
+
end
|
256
|
+
end
|
257
|
+
end
|