spree-state_machine 2.0.0.beta1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (140) hide show
  1. checksums.yaml +7 -0
  2. data/.gitignore +8 -0
  3. data/.travis.yml +12 -0
  4. data/.yardopts +5 -0
  5. data/CHANGELOG.md +502 -0
  6. data/Gemfile +3 -0
  7. data/LICENSE +20 -0
  8. data/README.md +1246 -0
  9. data/Rakefile +20 -0
  10. data/examples/AutoShop_state.png +0 -0
  11. data/examples/Car_state.png +0 -0
  12. data/examples/Gemfile +5 -0
  13. data/examples/Gemfile.lock +14 -0
  14. data/examples/TrafficLight_state.png +0 -0
  15. data/examples/Vehicle_state.png +0 -0
  16. data/examples/auto_shop.rb +13 -0
  17. data/examples/car.rb +21 -0
  18. data/examples/doc/AutoShop.html +2856 -0
  19. data/examples/doc/AutoShop_state.png +0 -0
  20. data/examples/doc/Car.html +919 -0
  21. data/examples/doc/Car_state.png +0 -0
  22. data/examples/doc/TrafficLight.html +2230 -0
  23. data/examples/doc/TrafficLight_state.png +0 -0
  24. data/examples/doc/Vehicle.html +7921 -0
  25. data/examples/doc/Vehicle_state.png +0 -0
  26. data/examples/doc/_index.html +136 -0
  27. data/examples/doc/class_list.html +47 -0
  28. data/examples/doc/css/common.css +1 -0
  29. data/examples/doc/css/full_list.css +55 -0
  30. data/examples/doc/css/style.css +322 -0
  31. data/examples/doc/file_list.html +46 -0
  32. data/examples/doc/frames.html +13 -0
  33. data/examples/doc/index.html +136 -0
  34. data/examples/doc/js/app.js +205 -0
  35. data/examples/doc/js/full_list.js +173 -0
  36. data/examples/doc/js/jquery.js +16 -0
  37. data/examples/doc/method_list.html +734 -0
  38. data/examples/doc/top-level-namespace.html +105 -0
  39. data/examples/merb-rest/controller.rb +51 -0
  40. data/examples/merb-rest/model.rb +28 -0
  41. data/examples/merb-rest/view_edit.html.erb +24 -0
  42. data/examples/merb-rest/view_index.html.erb +23 -0
  43. data/examples/merb-rest/view_new.html.erb +13 -0
  44. data/examples/merb-rest/view_show.html.erb +17 -0
  45. data/examples/rails-rest/controller.rb +43 -0
  46. data/examples/rails-rest/migration.rb +7 -0
  47. data/examples/rails-rest/model.rb +23 -0
  48. data/examples/rails-rest/view__form.html.erb +34 -0
  49. data/examples/rails-rest/view_edit.html.erb +6 -0
  50. data/examples/rails-rest/view_index.html.erb +25 -0
  51. data/examples/rails-rest/view_new.html.erb +5 -0
  52. data/examples/rails-rest/view_show.html.erb +19 -0
  53. data/examples/traffic_light.rb +9 -0
  54. data/examples/vehicle.rb +33 -0
  55. data/lib/state_machine/assertions.rb +36 -0
  56. data/lib/state_machine/branch.rb +225 -0
  57. data/lib/state_machine/callback.rb +236 -0
  58. data/lib/state_machine/core.rb +7 -0
  59. data/lib/state_machine/core_ext/class/state_machine.rb +5 -0
  60. data/lib/state_machine/core_ext.rb +2 -0
  61. data/lib/state_machine/error.rb +13 -0
  62. data/lib/state_machine/eval_helpers.rb +87 -0
  63. data/lib/state_machine/event.rb +257 -0
  64. data/lib/state_machine/event_collection.rb +141 -0
  65. data/lib/state_machine/extensions.rb +149 -0
  66. data/lib/state_machine/graph.rb +92 -0
  67. data/lib/state_machine/helper_module.rb +17 -0
  68. data/lib/state_machine/initializers/rails.rb +25 -0
  69. data/lib/state_machine/initializers.rb +4 -0
  70. data/lib/state_machine/integrations/active_model/locale.rb +11 -0
  71. data/lib/state_machine/integrations/active_model/observer.rb +33 -0
  72. data/lib/state_machine/integrations/active_model/observer_update.rb +42 -0
  73. data/lib/state_machine/integrations/active_model/versions.rb +31 -0
  74. data/lib/state_machine/integrations/active_model.rb +585 -0
  75. data/lib/state_machine/integrations/active_record/locale.rb +20 -0
  76. data/lib/state_machine/integrations/active_record/versions.rb +123 -0
  77. data/lib/state_machine/integrations/active_record.rb +525 -0
  78. data/lib/state_machine/integrations/base.rb +100 -0
  79. data/lib/state_machine/integrations.rb +121 -0
  80. data/lib/state_machine/machine.rb +2287 -0
  81. data/lib/state_machine/machine_collection.rb +74 -0
  82. data/lib/state_machine/macro_methods.rb +522 -0
  83. data/lib/state_machine/matcher.rb +123 -0
  84. data/lib/state_machine/matcher_helpers.rb +54 -0
  85. data/lib/state_machine/node_collection.rb +222 -0
  86. data/lib/state_machine/path.rb +120 -0
  87. data/lib/state_machine/path_collection.rb +90 -0
  88. data/lib/state_machine/state.rb +297 -0
  89. data/lib/state_machine/state_collection.rb +112 -0
  90. data/lib/state_machine/state_context.rb +138 -0
  91. data/lib/state_machine/transition.rb +470 -0
  92. data/lib/state_machine/transition_collection.rb +245 -0
  93. data/lib/state_machine/version.rb +3 -0
  94. data/lib/state_machine/yard/handlers/base.rb +32 -0
  95. data/lib/state_machine/yard/handlers/event.rb +25 -0
  96. data/lib/state_machine/yard/handlers/machine.rb +344 -0
  97. data/lib/state_machine/yard/handlers/state.rb +25 -0
  98. data/lib/state_machine/yard/handlers/transition.rb +47 -0
  99. data/lib/state_machine/yard/handlers.rb +12 -0
  100. data/lib/state_machine/yard/templates/default/class/html/setup.rb +30 -0
  101. data/lib/state_machine/yard/templates/default/class/html/state_machines.erb +12 -0
  102. data/lib/state_machine/yard/templates.rb +3 -0
  103. data/lib/state_machine/yard.rb +8 -0
  104. data/lib/state_machine.rb +8 -0
  105. data/lib/yard-state_machine.rb +2 -0
  106. data/state_machine.gemspec +22 -0
  107. data/test/files/en.yml +17 -0
  108. data/test/files/switch.rb +15 -0
  109. data/test/functional/state_machine_test.rb +1066 -0
  110. data/test/test_helper.rb +7 -0
  111. data/test/unit/assertions_test.rb +40 -0
  112. data/test/unit/branch_test.rb +969 -0
  113. data/test/unit/callback_test.rb +704 -0
  114. data/test/unit/error_test.rb +43 -0
  115. data/test/unit/eval_helpers_test.rb +270 -0
  116. data/test/unit/event_collection_test.rb +398 -0
  117. data/test/unit/event_test.rb +1196 -0
  118. data/test/unit/graph_test.rb +98 -0
  119. data/test/unit/helper_module_test.rb +17 -0
  120. data/test/unit/integrations/active_model_test.rb +1245 -0
  121. data/test/unit/integrations/active_record_test.rb +2551 -0
  122. data/test/unit/integrations/base_test.rb +104 -0
  123. data/test/unit/integrations_test.rb +71 -0
  124. data/test/unit/invalid_event_test.rb +20 -0
  125. data/test/unit/invalid_parallel_transition_test.rb +18 -0
  126. data/test/unit/invalid_transition_test.rb +115 -0
  127. data/test/unit/machine_collection_test.rb +603 -0
  128. data/test/unit/machine_test.rb +3395 -0
  129. data/test/unit/matcher_helpers_test.rb +37 -0
  130. data/test/unit/matcher_test.rb +155 -0
  131. data/test/unit/node_collection_test.rb +362 -0
  132. data/test/unit/path_collection_test.rb +266 -0
  133. data/test/unit/path_test.rb +485 -0
  134. data/test/unit/state_collection_test.rb +352 -0
  135. data/test/unit/state_context_test.rb +441 -0
  136. data/test/unit/state_machine_test.rb +31 -0
  137. data/test/unit/state_test.rb +1101 -0
  138. data/test/unit/transition_collection_test.rb +2168 -0
  139. data/test/unit/transition_test.rb +1558 -0
  140. metadata +264 -0
@@ -0,0 +1,74 @@
1
+ require 'state_machine/assertions'
2
+
3
+ module StateMachine
4
+ # Represents a collection of state machines for a class
5
+ class MachineCollection < Hash
6
+ include Assertions
7
+
8
+ # Initializes the state of each machine in the given object. This can allow
9
+ # states to be initialized in two groups: static and dynamic. For example:
10
+ #
11
+ # machines.initialize_states(object) do
12
+ # # After static state initialization, before dynamic state initialization
13
+ # end
14
+ #
15
+ # If no block is provided, then all states will still be initialized.
16
+ #
17
+ # Valid configuration options:
18
+ # * <tt>:static</tt> - Whether to initialize static states. If set to
19
+ # :force, the state will be initialized regardless of its current value.
20
+ # Default is :force.
21
+ # * <tt>:dynamic</tt> - Whether to initialize dynamic states. If set to
22
+ # :force, the state will be initialized regardless of its current value.
23
+ # Default is true.
24
+ # * <tt>:to</tt> - A hash to write the initialized state to instead of
25
+ # writing to the object. Default is to write directly to the object.
26
+ def initialize_states(object, options = {})
27
+ options = { :force => false }.merge(options)
28
+ each_value { |machine| machine.initialize_state object, options }
29
+ end
30
+
31
+ # Runs one or more events in parallel on the given object. See
32
+ # StateMachine::InstanceMethods#fire_events for more information.
33
+ def fire_events(object, *events)
34
+ run_action = [true, false].include?(events.last) ? events.pop : true
35
+
36
+ # Generate the transitions to run for each event
37
+ transitions = events.collect do |event_name|
38
+ # Find the actual event being run
39
+ event = nil
40
+ detect {|name, machine| event = machine.events[event_name, :qualified_name]}
41
+
42
+ raise(InvalidEvent.new(object, event_name)) unless event
43
+
44
+ # Get the transition that will be performed for the event
45
+ unless transition = event.transition_for(object)
46
+ event.on_failure(object)
47
+ end
48
+
49
+ transition
50
+ end.compact
51
+
52
+ # Run the events in parallel only if valid transitions were found for
53
+ # all of them
54
+ if events.length == transitions.length
55
+ TransitionCollection.new(transitions, :actions => run_action).perform
56
+ else
57
+ false
58
+ end
59
+ end
60
+
61
+ # Builds the collection of transitions for all event attributes defined on
62
+ # the given object. This will only include events whose machine actions
63
+ # match the one specified.
64
+ #
65
+ # These should only be fired as a result of the action being run.
66
+ def transitions(object, action, options = {})
67
+ transitions = map do |name, machine|
68
+ machine.events.attribute_transition_for(object, true) if machine.action == action
69
+ end
70
+
71
+ AttributeTransitionCollection.new(transitions.compact, options)
72
+ end
73
+ end
74
+ end
@@ -0,0 +1,522 @@
1
+ require 'state_machine/machine'
2
+
3
+ # A state machine is a model of behavior composed of states, events, and
4
+ # transitions. This helper adds support for defining this type of
5
+ # functionality on any Ruby class.
6
+ module StateMachine
7
+ module MacroMethods
8
+ # Creates a new state machine with the given name. The default name, if not
9
+ # specified, is <tt>:state</tt>.
10
+ #
11
+ # Configuration options:
12
+ # * <tt>:attribute</tt> - The name of the attribute to store the state value
13
+ # in. By default, this is the same as the name of the machine.
14
+ # * <tt>:initial</tt> - The initial state of the attribute. This can be a
15
+ # static state or a lambda block which will be evaluated at runtime
16
+ # (e.g. lambda {|vehicle| vehicle.speed == 0 ? :parked : :idling}).
17
+ # Default is nil.
18
+ # * <tt>:initialize</tt> - Whether to automatically initialize the attribute
19
+ # by hooking into #initialize on the owner class. Default is true.
20
+ # * <tt>:action</tt> - The instance method to invoke when an object
21
+ # transitions. Default is nil unless otherwise specified by the
22
+ # configured integration.
23
+ # * <tt>:namespace</tt> - The name to use for namespacing all generated
24
+ # state / event instance methods (e.g. "heater" would generate
25
+ # :turn_on_heater and :turn_off_heater for the :turn_on/:turn_off events).
26
+ # Default is nil.
27
+ # * <tt>:integration</tt> - The name of the integration to use for adding
28
+ # library-specific behavior to the machine. Built-in integrations
29
+ # include :active_model, :active_record, :data_mapper, :mongo_mapper, and
30
+ # :sequel. By default, this is determined automatically.
31
+ #
32
+ # Configuration options relevant to ORM integrations:
33
+ # * <tt>:plural</tt> - The pluralized version of the name. By default, this
34
+ # will attempt to call +pluralize+ on the name. If this method is not
35
+ # available, an "s" is appended. This is used for generating scopes.
36
+ # * <tt>:messages</tt> - The error messages to use when invalidating
37
+ # objects due to failed transitions. Messages include:
38
+ # * <tt>:invalid</tt>
39
+ # * <tt>:invalid_event</tt>
40
+ # * <tt>:invalid_transition</tt>
41
+ # * <tt>:use_transactions</tt> - Whether transactions should be used when
42
+ # firing events. Default is true unless otherwise specified by the
43
+ # configured integration.
44
+ #
45
+ # This also expects a block which will be used to actually configure the
46
+ # states, events and transitions for the state machine. *Note* that this
47
+ # block will be executed within the context of the state machine. As a
48
+ # result, you will not be able to access any class methods unless you refer
49
+ # to them directly (i.e. specifying the class name).
50
+ #
51
+ # For examples on the types of state machine configurations and blocks, see
52
+ # the section below.
53
+ #
54
+ # == Examples
55
+ #
56
+ # With the default name/attribute and no configuration:
57
+ #
58
+ # class Vehicle
59
+ # state_machine do
60
+ # event :park do
61
+ # ...
62
+ # end
63
+ # end
64
+ # end
65
+ #
66
+ # The above example will define a state machine named "state" that will
67
+ # store the value in the +state+ attribute. Every vehicle will start
68
+ # without an initial state.
69
+ #
70
+ # With a custom name / attribute:
71
+ #
72
+ # class Vehicle
73
+ # state_machine :status, :attribute => :status_value do
74
+ # ...
75
+ # end
76
+ # end
77
+ #
78
+ # With a static initial state:
79
+ #
80
+ # class Vehicle
81
+ # state_machine :status, :initial => :parked do
82
+ # ...
83
+ # end
84
+ # end
85
+ #
86
+ # With a dynamic initial state:
87
+ #
88
+ # class Vehicle
89
+ # state_machine :status, :initial => lambda {|vehicle| vehicle.speed == 0 ? :parked : :idling} do
90
+ # ...
91
+ # end
92
+ # end
93
+ #
94
+ # == Class Methods
95
+ #
96
+ # The following class methods will be automatically generated by the
97
+ # state machine based on the *name* of the machine. Any existing methods
98
+ # will not be overwritten.
99
+ # * <tt>human_state_name(state)</tt> - Gets the humanized value for the
100
+ # given state. This may be generated by internationalization libraries if
101
+ # supported by the integration.
102
+ # * <tt>human_state_event_name(event)</tt> - Gets the humanized value for
103
+ # the given event. This may be generated by internationalization
104
+ # libraries if supported by the integration.
105
+ #
106
+ # For example,
107
+ #
108
+ # class Vehicle
109
+ # state_machine :state, :initial => :parked do
110
+ # event :ignite do
111
+ # transition :parked => :idling
112
+ # end
113
+ #
114
+ # event :shift_up do
115
+ # transition :idling => :first_gear
116
+ # end
117
+ # end
118
+ # end
119
+ #
120
+ # Vehicle.human_state_name(:parked) # => "parked"
121
+ # Vehicle.human_state_name(:first_gear) # => "first gear"
122
+ # Vehicle.human_state_event_name(:park) # => "park"
123
+ # Vehicle.human_state_event_name(:shift_up) # => "shift up"
124
+ #
125
+ # == Instance Methods
126
+ #
127
+ # The following instance methods will be automatically generated by the
128
+ # state machine based on the *name* of the machine. Any existing methods
129
+ # will not be overwritten.
130
+ # * <tt>state</tt> - Gets the current value for the attribute
131
+ # * <tt>state=(value)</tt> - Sets the current value for the attribute
132
+ # * <tt>state?(name)</tt> - Checks the given state name against the current
133
+ # state. If the name is not a known state, then an ArgumentError is raised.
134
+ # * <tt>state_name</tt> - Gets the name of the state for the current value
135
+ # * <tt>human_state_name</tt> - Gets the human-readable name of the state
136
+ # for the current value
137
+ # * <tt>state_events(requirements = {})</tt> - Gets the list of events that
138
+ # can be fired on the current object's state (uses the *unqualified* event
139
+ # names)
140
+ # * <tt>state_transitions(requirements = {})</tt> - Gets the list of
141
+ # transitions that can be made on the current object's state
142
+ # * <tt>state_paths(requirements = {})</tt> - Gets the list of sequences of
143
+ # transitions that can be run from the current object's state
144
+ # * <tt>fire_state_event(name, *args)</tt> - Fires an arbitrary event with
145
+ # the given argument list. This is essentially the same as calling the
146
+ # actual event method itself.
147
+ #
148
+ # The <tt>state_events</tt>, <tt>state_transitions</tt>, and <tt>state_paths</tt>
149
+ # helpers all take an optional set of requirements for determining what's
150
+ # available for the current object. These requirements include:
151
+ # * <tt>:from</tt> - One or more states to transition from. If none are
152
+ # specified, then this will be the object's current state.
153
+ # * <tt>:to</tt> - One or more states to transition to. If none are
154
+ # specified, then this will match any to state.
155
+ # * <tt>:on</tt> - One or more events to transition on. If none are
156
+ # specified, then this will match any event.
157
+ # * <tt>:guard</tt> - Whether to guard transitions with the if/unless
158
+ # conditionals defined for each one. Default is true.
159
+ #
160
+ # For example,
161
+ #
162
+ # class Vehicle
163
+ # state_machine :state, :initial => :parked do
164
+ # event :ignite do
165
+ # transition :parked => :idling
166
+ # end
167
+ #
168
+ # event :park do
169
+ # transition :idling => :parked
170
+ # end
171
+ # end
172
+ # end
173
+ #
174
+ # vehicle = Vehicle.new
175
+ # vehicle.state # => "parked"
176
+ # vehicle.state_name # => :parked
177
+ # vehicle.human_state_name # => "parked"
178
+ # vehicle.state?(:parked) # => true
179
+ #
180
+ # # Changing state
181
+ # vehicle.state = 'idling'
182
+ # vehicle.state # => "idling"
183
+ # vehicle.state_name # => :idling
184
+ # vehicle.state?(:parked) # => false
185
+ #
186
+ # # Getting current event / transition availability
187
+ # vehicle.state_events # => [:park]
188
+ # vehicle.park # => true
189
+ # vehicle.state_events # => [:ignite]
190
+ # vehicle.state_events(:from => :idling) # => [:park]
191
+ # vehicle.state_events(:to => :parked) # => []
192
+ #
193
+ # vehicle.state_transitions # => [#<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
194
+ # vehicle.ignite # => true
195
+ # vehicle.state_transitions # => [#<StateMachine::Transition attribute=:state event=:park from="idling" from_name=:idling to="parked" to_name=:parked>]
196
+ #
197
+ # vehicle.state_transitions(:on => :ignite) # => []
198
+ #
199
+ # # Getting current path availability
200
+ # vehicle.state_paths # => [
201
+ # # [#<StateMachine::Transition attribute=:state event=:park from="idling" from_name=:idling to="parked" to_name=:parked>,
202
+ # # #<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
203
+ # # ]
204
+ # vehicle.state_paths(:guard => false) # =>
205
+ # # [#<StateMachine::Transition attribute=:state event=:park from="idling" from_name=:idling to="parked" to_name=:parked>,
206
+ # # #<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
207
+ # # ]
208
+ #
209
+ # # Fire arbitrary events
210
+ # vehicle.fire_state_event(:park) # => true
211
+ #
212
+ # == Attribute initialization
213
+ #
214
+ # For most classes, the initial values for state machine attributes are
215
+ # automatically assigned when a new object is created. However, this
216
+ # behavior will *not* work if the class defines an +initialize+ method
217
+ # without properly calling +super+.
218
+ #
219
+ # For example,
220
+ #
221
+ # class Vehicle
222
+ # state_machine :state, :initial => :parked do
223
+ # ...
224
+ # end
225
+ # end
226
+ #
227
+ # vehicle = Vehicle.new # => #<Vehicle:0xb7c8dbf8 @state="parked">
228
+ # vehicle.state # => "parked"
229
+ #
230
+ # In the above example, no +initialize+ method is defined. As a result,
231
+ # the default behavior of initializing the state machine attributes is used.
232
+ #
233
+ # In the following example, a custom +initialize+ method is defined:
234
+ #
235
+ # class Vehicle
236
+ # state_machine :state, :initial => :parked do
237
+ # ...
238
+ # end
239
+ #
240
+ # def initialize
241
+ # end
242
+ # end
243
+ #
244
+ # vehicle = Vehicle.new # => #<Vehicle:0xb7c77678>
245
+ # vehicle.state # => nil
246
+ #
247
+ # Since the +initialize+ method is defined, the state machine attributes
248
+ # never get initialized. In order to ensure that all initialization hooks
249
+ # are called, the custom method *must* call +super+ without any arguments
250
+ # like so:
251
+ #
252
+ # class Vehicle
253
+ # state_machine :state, :initial => :parked do
254
+ # ...
255
+ # end
256
+ #
257
+ # def initialize(attributes = {})
258
+ # ...
259
+ # super()
260
+ # end
261
+ # end
262
+ #
263
+ # vehicle = Vehicle.new # => #<Vehicle:0xb7c8dbf8 @state="parked">
264
+ # vehicle.state # => "parked"
265
+ #
266
+ # Because of the way the inclusion of modules works in Ruby, calling
267
+ # <tt>super()</tt> will not only call the superclass's +initialize+, but
268
+ # also +initialize+ on all included modules. This allows the original state
269
+ # machine hook to get called properly.
270
+ #
271
+ # If you want to avoid calling the superclass's constructor, but still want
272
+ # to initialize the state machine attributes:
273
+ #
274
+ # class Vehicle
275
+ # state_machine :state, :initial => :parked do
276
+ # ...
277
+ # end
278
+ #
279
+ # def initialize(attributes = {})
280
+ # ...
281
+ # initialize_state_machines
282
+ # end
283
+ # end
284
+ #
285
+ # vehicle = Vehicle.new # => #<Vehicle:0xb7c8dbf8 @state="parked">
286
+ # vehicle.state # => "parked"
287
+ #
288
+ # You may also need to call the +initialize_state_machines+ helper manually
289
+ # in cases where you want to change how static / dynamic initial states get
290
+ # set. For example, the following example forces the initialization of
291
+ # static states regardless of their current value:
292
+ #
293
+ # class Vehicle
294
+ # state_machine :state, :initial => :parked do
295
+ # state nil, :idling
296
+ # ...
297
+ # end
298
+ #
299
+ # def initialize(attributes = {})
300
+ # @state = 'idling'
301
+ # initialize_state_machines(:static => :force) do
302
+ # ...
303
+ # end
304
+ # end
305
+ # end
306
+ #
307
+ # vehicle = Vehicle.new # => #<Vehicle:0xb7c8dbf8 @state="parked">
308
+ # vehicle.state # => "parked"
309
+ #
310
+ # The above example is also noteworthy because it demonstrates how to avoid
311
+ # initialization issues when +nil+ is a valid state. Without passing in
312
+ # <tt>:static => :force</tt>, state_machine would never have initialized
313
+ # the state because +nil+ (the default attribute value) would have been
314
+ # interpreted as a valid current state. As a result, state_machine would
315
+ # have simply skipped initialization.
316
+ #
317
+ # == States
318
+ #
319
+ # All of the valid states for the machine are automatically tracked based
320
+ # on the events, transitions, and callbacks defined for the machine. If
321
+ # there are additional states that are never referenced, these should be
322
+ # explicitly added using the StateMachine::Machine#state or
323
+ # StateMachine::Machine#other_states helpers.
324
+ #
325
+ # When a new state is defined, a predicate method for that state is
326
+ # generated on the class. For example,
327
+ #
328
+ # class Vehicle
329
+ # state_machine :initial => :parked do
330
+ # event :ignite do
331
+ # transition all => :idling
332
+ # end
333
+ # end
334
+ # end
335
+ #
336
+ # ...will generate the following instance methods (assuming they're not
337
+ # already defined in the class):
338
+ # * <tt>parked?</tt>
339
+ # * <tt>idling?</tt>
340
+ #
341
+ # Each predicate method will return true if it matches the object's
342
+ # current state. Otherwise, it will return false.
343
+ #
344
+ # == Attribute access
345
+ #
346
+ # The actual value for a state is stored in the attribute configured for the
347
+ # state machine. In most cases, this is the same as the name of the state
348
+ # machine. For example:
349
+ #
350
+ # class Vehicle
351
+ # attr_accessor :state
352
+ #
353
+ # state_machine :state, :initial => :parked do
354
+ # ...
355
+ # state :parked, :value => 0
356
+ # start :idling, :value => 1
357
+ # end
358
+ # end
359
+ #
360
+ # vehicle = Vehicle.new # => #<Vehicle:0xb712da60 @state=0>
361
+ # vehicle.state # => 0
362
+ # vehicle.parked? # => true
363
+ # vehicle.state = 1
364
+ # vehicle.idling? # => true
365
+ #
366
+ # The most important thing to note from the example above is what it means
367
+ # to read from and write to the state machine's attribute. In particular,
368
+ # state_machine treats the attribute (+state+ in this case) like a basic
369
+ # attr_accessor that's been defined on the class. There are no special
370
+ # behaviors added, such as allowing the attribute to be written to based on
371
+ # the name of a state in the machine. This is the case for a few reasons:
372
+ # * Setting the attribute directly is an edge case that is meant to only be
373
+ # used when you want to skip state_machine altogether. This means that
374
+ # state_machine shouldn't have any effect on the attribute accessor
375
+ # methods. If you want to change the state, you should be using one of
376
+ # the events defined in the state machine.
377
+ # * Many ORMs provide custom behavior for the attribute reader / writer - it
378
+ # may even be defined by your own framework / method implementation just
379
+ # the example above showed. In order to avoid having to worry about the
380
+ # different ways an attribute can get written, state_machine just makes
381
+ # sure that the configured value for a state is always used when writing
382
+ # to the attribute.
383
+ #
384
+ # If you were interested in accessing the name of a state (instead of its
385
+ # actual value through the attribute), you could do the following:
386
+ #
387
+ # vehicle.state_name # => :idling
388
+ #
389
+ # == Events and Transitions
390
+ #
391
+ # Events defined on the machine are the interface to transitioning states
392
+ # for an object. Events can be fired either directly (through the method
393
+ # generated for the event) or indirectly (through attributes defined on
394
+ # the machine).
395
+ #
396
+ # For example,
397
+ #
398
+ # class Vehicle
399
+ # include DataMapper::Resource
400
+ # property :id, Serial
401
+ #
402
+ # state_machine :initial => :parked do
403
+ # event :ignite do
404
+ # transition :parked => :idling
405
+ # end
406
+ # end
407
+ #
408
+ # state_machine :alarm_state, :initial => :active do
409
+ # event :disable do
410
+ # transition all => :off
411
+ # end
412
+ # end
413
+ # end
414
+ #
415
+ # # Fire +ignite+ event directly
416
+ # vehicle = Vehicle.create # => #<Vehicle id=1 state="parked" alarm_state="active">
417
+ # vehicle.ignite # => true
418
+ # vehicle.state # => "idling"
419
+ # vehicle.alarm_state # => "active"
420
+ #
421
+ # # Fire +disable+ event automatically
422
+ # vehicle.alarm_state_event = 'disable'
423
+ # vehicle.save # => true
424
+ # vehicle.alarm_state # => "off"
425
+ #
426
+ # In the above example, the +state+ attribute is transitioned using the
427
+ # +ignite+ action that's generated from the state machine. On the other
428
+ # hand, the +alarm_state+ attribute is transitioned using the +alarm_state_event+
429
+ # attribute that automatically gets fired when the machine's action (+save+)
430
+ # is invoked.
431
+ #
432
+ # For more information about how to configure an event and its associated
433
+ # transitions, see StateMachine::Machine#event.
434
+ #
435
+ # == Defining callbacks
436
+ #
437
+ # Within the +state_machine+ block, you can also define callbacks for
438
+ # transitions. For more information about defining these callbacks,
439
+ # see StateMachine::Machine#before_transition, StateMachine::Machine#after_transition,
440
+ # and StateMachine::Machine#around_transition, and StateMachine::Machine#after_failure.
441
+ #
442
+ # == Namespaces
443
+ #
444
+ # When a namespace is configured for a state machine, the name provided
445
+ # will be used in generating the instance methods for interacting with
446
+ # states/events in the machine. This is particularly useful when a class
447
+ # has multiple state machines and it would be difficult to differentiate
448
+ # between the various states / events.
449
+ #
450
+ # For example,
451
+ #
452
+ # class Vehicle
453
+ # state_machine :heater_state, :initial => :off, :namespace => 'heater' do
454
+ # event :turn_on do
455
+ # transition all => :on
456
+ # end
457
+ #
458
+ # event :turn_off do
459
+ # transition all => :off
460
+ # end
461
+ # end
462
+ #
463
+ # state_machine :alarm_state, :initial => :active, :namespace => 'alarm' do
464
+ # event :turn_on do
465
+ # transition all => :active
466
+ # end
467
+ #
468
+ # event :turn_off do
469
+ # transition all => :off
470
+ # end
471
+ # end
472
+ # end
473
+ #
474
+ # The above class defines two state machines: +heater_state+ and +alarm_state+.
475
+ # For the +heater_state+ machine, the following methods are generated since
476
+ # it's namespaced by "heater":
477
+ # * <tt>can_turn_on_heater?</tt>
478
+ # * <tt>turn_on_heater</tt>
479
+ # * ...
480
+ # * <tt>can_turn_off_heater?</tt>
481
+ # * <tt>turn_off_heater</tt>
482
+ # * ..
483
+ # * <tt>heater_off?</tt>
484
+ # * <tt>heater_on?</tt>
485
+ #
486
+ # As shown, each method is unique to the state machine so that the states
487
+ # and events don't conflict. The same goes for the +alarm_state+ machine:
488
+ # * <tt>can_turn_on_alarm?</tt>
489
+ # * <tt>turn_on_alarm</tt>
490
+ # * ...
491
+ # * <tt>can_turn_off_alarm?</tt>
492
+ # * <tt>turn_off_alarm</tt>
493
+ # * ..
494
+ # * <tt>alarm_active?</tt>
495
+ # * <tt>alarm_off?</tt>
496
+ #
497
+ # == Scopes
498
+ #
499
+ # For integrations that support it, a group of default scope filters will
500
+ # be automatically created for assisting in finding objects that have the
501
+ # attribute set to one of a given set of states.
502
+ #
503
+ # For example,
504
+ #
505
+ # Vehicle.with_state(:parked) # => All vehicles where the state is parked
506
+ # Vehicle.with_states(:parked, :idling) # => All vehicles where the state is either parked or idling
507
+ #
508
+ # Vehicle.without_state(:parked) # => All vehicles where the state is *not* parked
509
+ # Vehicle.without_states(:parked, :idling) # => All vehicles where the state is *not* parked or idling
510
+ #
511
+ # *Note* that if class methods already exist with those names (i.e.
512
+ # :with_state, :with_states, :without_state, or :without_states), then a
513
+ # scope will not be defined for that name.
514
+ #
515
+ # See StateMachine::Machine for more information about using integrations
516
+ # and the individual integration docs for information about the actual
517
+ # scopes that are generated.
518
+ def state_machine(*args, &block)
519
+ StateMachine::Machine.find_or_create(self, *args, &block)
520
+ end
521
+ end
522
+ end