enum_state_machine 0.0.2 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. checksums.yaml +4 -4
  2. data/.gitignore +0 -12
  3. data/.ruby-version +1 -1
  4. data/.ruby-version.orig +5 -0
  5. data/Gemfile +0 -1
  6. data/Rakefile +0 -18
  7. data/enum_state_machine.gemspec +35 -0
  8. data/enum_state_machine.gemspec.orig +43 -0
  9. data/lib/enum_state_machine/assertions.rb +36 -0
  10. data/lib/enum_state_machine/branch.rb +225 -0
  11. data/lib/enum_state_machine/callback.rb +232 -0
  12. data/lib/enum_state_machine/core.rb +12 -0
  13. data/lib/enum_state_machine/core_ext/class/state_machine.rb +5 -0
  14. data/lib/enum_state_machine/core_ext.rb +2 -0
  15. data/lib/enum_state_machine/error.rb +13 -0
  16. data/lib/enum_state_machine/eval_helpers.rb +87 -0
  17. data/lib/enum_state_machine/event.rb +257 -0
  18. data/lib/enum_state_machine/event_collection.rb +141 -0
  19. data/lib/enum_state_machine/extensions.rb +149 -0
  20. data/lib/enum_state_machine/graph.rb +93 -0
  21. data/lib/enum_state_machine/helper_module.rb +17 -0
  22. data/lib/enum_state_machine/initializers/rails.rb +22 -0
  23. data/lib/enum_state_machine/initializers.rb +4 -0
  24. data/lib/enum_state_machine/integrations/active_model/locale.rb +11 -0
  25. data/lib/enum_state_machine/integrations/active_model/observer.rb +33 -0
  26. data/lib/enum_state_machine/integrations/active_model/observer_update.rb +42 -0
  27. data/lib/enum_state_machine/integrations/active_model/versions.rb +31 -0
  28. data/lib/enum_state_machine/integrations/active_model.rb +585 -0
  29. data/lib/enum_state_machine/integrations/active_record/locale.rb +20 -0
  30. data/lib/enum_state_machine/integrations/active_record/versions.rb +123 -0
  31. data/lib/enum_state_machine/integrations/active_record.rb +548 -0
  32. data/lib/enum_state_machine/integrations/base.rb +100 -0
  33. data/lib/enum_state_machine/integrations.rb +97 -0
  34. data/lib/enum_state_machine/machine.rb +2292 -0
  35. data/lib/enum_state_machine/machine_collection.rb +86 -0
  36. data/lib/enum_state_machine/macro_methods.rb +518 -0
  37. data/lib/enum_state_machine/matcher.rb +123 -0
  38. data/lib/enum_state_machine/matcher_helpers.rb +54 -0
  39. data/lib/enum_state_machine/node_collection.rb +222 -0
  40. data/lib/enum_state_machine/path.rb +120 -0
  41. data/lib/enum_state_machine/path_collection.rb +90 -0
  42. data/lib/enum_state_machine/state.rb +297 -0
  43. data/lib/enum_state_machine/state_collection.rb +112 -0
  44. data/lib/enum_state_machine/state_context.rb +138 -0
  45. data/lib/enum_state_machine/state_enum.rb +23 -0
  46. data/lib/enum_state_machine/transition.rb +470 -0
  47. data/lib/enum_state_machine/transition_collection.rb +245 -0
  48. data/lib/enum_state_machine/version.rb +3 -0
  49. data/lib/enum_state_machine/yard/handlers/base.rb +32 -0
  50. data/lib/enum_state_machine/yard/handlers/event.rb +25 -0
  51. data/lib/enum_state_machine/yard/handlers/machine.rb +344 -0
  52. data/lib/enum_state_machine/yard/handlers/state.rb +25 -0
  53. data/lib/enum_state_machine/yard/handlers/transition.rb +47 -0
  54. data/lib/enum_state_machine/yard/handlers.rb +12 -0
  55. data/lib/enum_state_machine/yard/templates/default/class/html/setup.rb +30 -0
  56. data/lib/enum_state_machine/yard/templates/default/class/html/state_machines.erb +12 -0
  57. data/lib/enum_state_machine/yard/templates.rb +3 -0
  58. data/lib/enum_state_machine/yard.rb +8 -0
  59. data/lib/enum_state_machine.rb +9 -0
  60. data/lib/tasks/enum_state_machine.rake +1 -0
  61. data/lib/tasks/enum_state_machine.rb +24 -0
  62. data/lib/yard-enum_state_machine.rb +2 -0
  63. data/test/functional/state_machine_test.rb +1066 -0
  64. data/test/unit/graph_test.rb +9 -5
  65. data/test/unit/integrations/active_model_test.rb +1245 -0
  66. data/test/unit/integrations/active_record_test.rb +2551 -0
  67. data/test/unit/integrations/base_test.rb +104 -0
  68. data/test/unit/integrations_test.rb +71 -0
  69. data/test/unit/invalid_event_test.rb +20 -0
  70. data/test/unit/invalid_parallel_transition_test.rb +18 -0
  71. data/test/unit/invalid_transition_test.rb +115 -0
  72. data/test/unit/machine_collection_test.rb +603 -0
  73. data/test/unit/machine_test.rb +3395 -0
  74. data/test/unit/state_machine_test.rb +31 -0
  75. metadata +212 -44
  76. data/Appraisals +0 -28
  77. data/gemfiles/active_model_4.0.4.gemfile +0 -9
  78. data/gemfiles/active_model_4.0.4.gemfile.lock +0 -51
  79. data/gemfiles/active_record_4.0.4.gemfile +0 -11
  80. data/gemfiles/active_record_4.0.4.gemfile.lock +0 -61
  81. data/gemfiles/default.gemfile +0 -7
  82. data/gemfiles/default.gemfile.lock +0 -27
  83. data/gemfiles/graphviz_1.0.9.gemfile +0 -7
  84. data/gemfiles/graphviz_1.0.9.gemfile.lock +0 -30
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: d0a9a300870e2fe8f7dad7efadeb2f0412090d9f
4
- data.tar.gz: 4e4302f4aa155d84292e840b73845b1a3225bbc7
3
+ metadata.gz: f4cd89a1c0e7dcc934de771658dee378243ba3db
4
+ data.tar.gz: d9b5d3384324934e06562fc683d6eecb74473a09
5
5
  SHA512:
6
- metadata.gz: e7d269d54907828b2b4f1569c649acb83988b99df821d8eaab07cca000857febefbb1b9afdf96d7614a5a0b8bc003ccf24c5824756e6f17123a22d1b20b7bdca
7
- data.tar.gz: 55c85d9036a2ba634dfdb46ffdb662a23815098098ac0edb2e0088d2c73a58e12e52ac7bb2862f5423d684087ff1f41ab7a51e2804ded514bfff18e5ec31ce0c
6
+ metadata.gz: 742eb30aa793272273bfadd298d2e9a3d52af82c9c8037030e127e9b22bdc3c340c5b20439de6714d504a663432ee69fc6c0de562b29c4be6f20e6b2a15d0122
7
+ data.tar.gz: f63428fcf59e6fd181b00c33d040b65b2210137626192dacb1461e9f02cdb0b9b5695446694634af680804c42e026c49ac1cff32b6134683e500c9253f63f34f
data/.gitignore CHANGED
@@ -7,15 +7,3 @@ coverage/
7
7
  /doc/
8
8
  test/*.log
9
9
  /Gemfile.lock
10
-
11
- # jeweler generated
12
- pkg
13
-
14
- # exclude everything in tmp
15
- tmp/*
16
- # except the metric_fu directory
17
- !tmp/metric_fu/
18
- # but exclude everything *in* the metric_fu directory
19
- tmp/metric_fu/*
20
- # except for the _data directory to track metrical outputs
21
- !tmp/metric_fu/_data/
data/.ruby-version CHANGED
@@ -1 +1 @@
1
- 2.0.0
1
+ 2.1.2
@@ -0,0 +1,5 @@
1
+ <<<<<<< HEAD
2
+ 2.0.0
3
+ =======
4
+ 2.1.2
5
+ >>>>>>> origin/ruby_2.1.2
data/Gemfile CHANGED
@@ -1,4 +1,3 @@
1
1
  source "https://www.rubygems.org"
2
2
 
3
3
  gemspec
4
-
data/Rakefile CHANGED
@@ -5,8 +5,6 @@ Bundler.setup
5
5
  require 'rake'
6
6
  require 'rake/testtask'
7
7
 
8
- require 'appraisal'
9
-
10
8
  desc 'Default: run all tests.'
11
9
  task :default => :test
12
10
 
@@ -22,22 +20,6 @@ Rake::TestTask.new(:test) do |t|
22
20
  t.warning = true if ENV['WARNINGS']
23
21
  end
24
22
 
25
- namespace :appraisal do
26
- desc "Run the given task for a particular integration's appraisals"
27
- task :integration do
28
- integration = ENV['INTEGRATION']
29
-
30
- Appraisal::File.each do |appraisal|
31
- if appraisal.name.include?(integration)
32
- appraisal.install
33
- Appraisal::Command.from_args(appraisal.gemfile_path).run
34
- end
35
- end
36
-
37
- exit
38
- end
39
- end
40
-
41
23
  load File.dirname(__FILE__) + '/lib/tasks/enum_state_machine.rake'
42
24
 
43
25
  Bundler::GemHelper.install_tasks
@@ -0,0 +1,35 @@
1
+ $LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
2
+ require 'enum_state_machine/version'
3
+
4
+ Gem::Specification.new do |s|
5
+ s.name = "enum_state_machine"
6
+ s.version = EnumStateMachine::VERSION
7
+ s.authors = ["The HornsAndHooves Team"]
8
+ s.email = ["arthur.shagall@gmail.com"]
9
+ s.homepage = "https://github.com/HornsAndHooves/enum_state_machine"
10
+ s.description = "Adds support for creating enum state machines for attributes on any Ruby class"
11
+ s.summary = "Enum State machines for attributes"
12
+ s.require_paths = ["lib"]
13
+ ignores = File.read(".gitignore").split.map {|i| i.sub(/\/$/, "/*").sub(/^[^\/]/, "**/\\0")}
14
+ s.files = (Dir[".*"] + Dir["**/*"]).select {|f| File.file?(f) && !ignores.any? {|i| File.fnmatch(i, "/#{f}")}}
15
+ s.test_files = s.files.grep(/^test\//)
16
+ s.rdoc_options = %w(--line-numbers --inline-source --title enum_state_machine --main README.md)
17
+ s.extra_rdoc_files = %w(README.md CHANGELOG.md LICENSE)
18
+ s.license = 'MIT'
19
+
20
+ s.add_dependency "rails", "~> 4.0.13"
21
+
22
+ s.add_dependency "sqlite3", "~> 1.3.9"
23
+ s.add_dependency "activemodel", "~> 4.0.5"
24
+ s.add_dependency "activerecord", "~> 4.0.5"
25
+ s.add_dependency "activerecord-deprecated_finders", "~> 1.0.3"
26
+ s.add_dependency "protected_attributes", "~> 1.0.7"
27
+ s.add_dependency "rails-observers", "~> 0.1.2"
28
+ s.add_dependency "power_enum", "~> 2.7"
29
+ s.add_dependency "ruby-graphviz", "~> 1.0.9"
30
+
31
+ s.add_development_dependency "rake"
32
+ s.add_development_dependency "minitest", "~> 4.7.5"
33
+ s.add_development_dependency "simplecov"
34
+ s.add_development_dependency "yard"
35
+ end
@@ -0,0 +1,43 @@
1
+ $LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
2
+ require 'enum_state_machine/version'
3
+
4
+ Gem::Specification.new do |s|
5
+ s.name = "enum_state_machine"
6
+ s.version = EnumStateMachine::VERSION
7
+ s.authors = ["The HornsAndHooves Team"]
8
+ s.email = ["arthur.shagall@gmail.com"]
9
+ s.homepage = "https://github.com/HornsAndHooves/enum_state_machine"
10
+ s.description = "Adds support for creating enum state machines for attributes on any Ruby class"
11
+ s.summary = "Enum State machines for attributes"
12
+ s.require_paths = ["lib"]
13
+ ignores = File.read(".gitignore").split.map {|i| i.sub(/\/$/, "/*").sub(/^[^\/]/, "**/\\0")}
14
+ s.files = (Dir[".*"] + Dir["**/*"]).select {|f| File.file?(f) && !ignores.any? {|i| File.fnmatch(i, "/#{f}")}}
15
+ s.test_files = s.files.grep(/^test\//)
16
+ s.rdoc_options = %w(--line-numbers --inline-source --title enum_state_machine --main README.md)
17
+ s.extra_rdoc_files = %w(README.md CHANGELOG.md LICENSE)
18
+ s.license = 'MIT'
19
+
20
+ <<<<<<< HEAD
21
+ s.add_dependency "power_enum", "~> 2.4"
22
+ s.add_dependency "rails", "~> 4.0.13"
23
+
24
+ s.add_development_dependency "rake"
25
+ s.add_development_dependency "simplecov"
26
+ s.add_development_dependency "appraisal", "~> 0.5.0"
27
+ s.add_development_dependency "yard"
28
+ =======
29
+
30
+ s.add_dependency "sqlite3", "~> 1.3.9"
31
+ s.add_dependency "activemodel", "~> 4.0.5"
32
+ s.add_dependency "activerecord", "~> 4.0.5"
33
+ s.add_dependency "activerecord-deprecated_finders", "~> 1.0.3"
34
+ s.add_dependency "protected_attributes", "~> 1.0.7"
35
+ s.add_dependency "rails-observers", "~> 0.1.2"
36
+ s.add_dependency "power_enum", "~> 2.7"
37
+ s.add_dependency "ruby-graphviz", "~> 1.0.9"
38
+
39
+ s.add_development_dependency "rake"
40
+ s.add_development_dependency "minitest", "~> 4.7.5"
41
+ s.add_development_dependency "simplecov"
42
+ >>>>>>> origin/ruby_2.1.2
43
+ end
@@ -0,0 +1,36 @@
1
+ module EnumStateMachine
2
+ # Provides a set of helper methods for making assertions about the content
3
+ # of various objects
4
+ module Assertions
5
+ # Validates that the given hash *only* includes the specified valid keys.
6
+ # If any invalid keys are found, an ArgumentError will be raised.
7
+ #
8
+ # == Examples
9
+ #
10
+ # options = {:name => 'John Smith', :age => 30}
11
+ #
12
+ # assert_valid_keys(options, :name) # => ArgumentError: Invalid key(s): age
13
+ # assert_valid_keys(options, 'name', 'age') # => ArgumentError: Invalid key(s): age, name
14
+ # assert_valid_keys(options, :name, :age) # => nil
15
+ def assert_valid_keys(hash, *valid_keys)
16
+ invalid_keys = hash.keys - valid_keys
17
+ raise ArgumentError, "Invalid key(s): #{invalid_keys.join(', ')}" unless invalid_keys.empty?
18
+ end
19
+
20
+ # Validates that the given hash only includes at *most* one of a set of
21
+ # exclusive keys. If more than one key is found, an ArgumentError will be
22
+ # raised.
23
+ #
24
+ # == Examples
25
+ #
26
+ # options = {:only => :on, :except => :off}
27
+ # assert_exclusive_keys(options, :only) # => nil
28
+ # assert_exclusive_keys(options, :except) # => nil
29
+ # assert_exclusive_keys(options, :only, :except) # => ArgumentError: Conflicting keys: only, except
30
+ # assert_exclusive_keys(options, :only, :except, :with) # => ArgumentError: Conflicting keys: only, except
31
+ def assert_exclusive_keys(hash, *exclusive_keys)
32
+ conflicting_keys = exclusive_keys & hash.keys
33
+ raise ArgumentError, "Conflicting keys: #{conflicting_keys.join(', ')}" unless conflicting_keys.length <= 1
34
+ end
35
+ end
36
+ end
@@ -0,0 +1,225 @@
1
+ require 'enum_state_machine/matcher'
2
+ require 'enum_state_machine/eval_helpers'
3
+ require 'enum_state_machine/assertions'
4
+
5
+ module EnumStateMachine
6
+ # Represents a set of requirements that must be met in order for a transition
7
+ # or callback to occur. Branches verify that the event, from state, and to
8
+ # state of the transition match, in addition to if/unless conditionals for
9
+ # an object's state.
10
+ class Branch
11
+ include Assertions
12
+ include EvalHelpers
13
+
14
+ # The condition that must be met on an object
15
+ attr_reader :if_condition
16
+
17
+ # The condition that must *not* be met on an object
18
+ attr_reader :unless_condition
19
+
20
+ # The requirement for verifying the event being matched
21
+ attr_reader :event_requirement
22
+
23
+ # One or more requirements for verifying the states being matched. All
24
+ # requirements contain a mapping of {:from => matcher, :to => matcher}.
25
+ attr_reader :state_requirements
26
+
27
+ # A list of all of the states known to this branch. This will pull states
28
+ # from the following options (in the same order):
29
+ # * +from+ / +except_from+
30
+ # * +to+ / +except_to+
31
+ attr_reader :known_states
32
+
33
+ # Creates a new branch
34
+ def initialize(options = {}) #:nodoc:
35
+ # Build conditionals
36
+ @if_condition = options.delete(:if)
37
+ @unless_condition = options.delete(:unless)
38
+
39
+ # Build event requirement
40
+ @event_requirement = build_matcher(options, :on, :except_on)
41
+
42
+ if (options.keys - [:from, :to, :on, :except_from, :except_to, :except_on]).empty?
43
+ # Explicit from/to requirements specified
44
+ @state_requirements = [{:from => build_matcher(options, :from, :except_from), :to => build_matcher(options, :to, :except_to)}]
45
+ else
46
+ # Separate out the event requirement
47
+ options.delete(:on)
48
+ options.delete(:except_on)
49
+
50
+ # Implicit from/to requirements specified
51
+ @state_requirements = options.collect do |from, to|
52
+ from = WhitelistMatcher.new(from) unless from.is_a?(Matcher)
53
+ to = WhitelistMatcher.new(to) unless to.is_a?(Matcher)
54
+ {:from => from, :to => to}
55
+ end
56
+ end
57
+
58
+ # Track known states. The order that requirements are iterated is based
59
+ # on the priority in which tracked states should be added.
60
+ @known_states = []
61
+ @state_requirements.each do |state_requirement|
62
+ [:from, :to].each {|option| @known_states |= state_requirement[option].values}
63
+ end
64
+ end
65
+
66
+ # Determines whether the given object / query matches the requirements
67
+ # configured for this branch. In addition to matching the event, from state,
68
+ # and to state, this will also check whether the configured :if/:unless
69
+ # conditions pass on the given object.
70
+ #
71
+ # == Examples
72
+ #
73
+ # branch = EnumStateMachine::Branch.new(:parked => :idling, :on => :ignite)
74
+ #
75
+ # # Successful
76
+ # branch.matches?(object, :on => :ignite) # => true
77
+ # branch.matches?(object, :from => nil) # => true
78
+ # branch.matches?(object, :from => :parked) # => true
79
+ # branch.matches?(object, :to => :idling) # => true
80
+ # branch.matches?(object, :from => :parked, :to => :idling) # => true
81
+ # branch.matches?(object, :on => :ignite, :from => :parked, :to => :idling) # => true
82
+ #
83
+ # # Unsuccessful
84
+ # branch.matches?(object, :on => :park) # => false
85
+ # branch.matches?(object, :from => :idling) # => false
86
+ # branch.matches?(object, :to => :first_gear) # => false
87
+ # branch.matches?(object, :from => :parked, :to => :first_gear) # => false
88
+ # branch.matches?(object, :on => :park, :from => :parked, :to => :idling) # => false
89
+ def matches?(object, query = {})
90
+ !match(object, query).nil?
91
+ end
92
+
93
+ # Attempts to match the given object / query against the set of requirements
94
+ # configured for this branch. In addition to matching the event, from state,
95
+ # and to state, this will also check whether the configured :if/:unless
96
+ # conditions pass on the given object.
97
+ #
98
+ # If a match is found, then the event/state requirements that the query
99
+ # passed successfully will be returned. Otherwise, nil is returned if there
100
+ # was no match.
101
+ #
102
+ # Query options:
103
+ # * <tt>:from</tt> - One or more states being transitioned from. If none
104
+ # are specified, then this will always match.
105
+ # * <tt>:to</tt> - One or more states being transitioned to. If none are
106
+ # specified, then this will always match.
107
+ # * <tt>:on</tt> - One or more events that fired the transition. If none
108
+ # are specified, then this will always match.
109
+ # * <tt>:guard</tt> - Whether to guard matches with the if/unless
110
+ # conditionals defined for this branch. Default is true.
111
+ #
112
+ # == Examples
113
+ #
114
+ # branch = EnumStateMachine::Branch.new(:parked => :idling, :on => :ignite)
115
+ #
116
+ # branch.match(object, :on => :ignite) # => {:to => ..., :from => ..., :on => ...}
117
+ # branch.match(object, :on => :park) # => nil
118
+ def match(object, query = {})
119
+ assert_valid_keys(query, :from, :to, :on, :guard)
120
+
121
+ if (match = match_query(query)) && matches_conditions?(object, query)
122
+ match
123
+ end
124
+ end
125
+
126
+ # Draws a representation of this branch on the given graph. This will draw
127
+ # an edge between every state this branch matches *from* to either the
128
+ # configured to state or, if none specified, then a loopback to the from
129
+ # state.
130
+ #
131
+ # For example, if the following from states are configured:
132
+ # * +idling+
133
+ # * +first_gear+
134
+ # * +backing_up+
135
+ #
136
+ # ...and the to state is +parked+, then the following edges will be created:
137
+ # * +idling+ -> +parked+
138
+ # * +first_gear+ -> +parked+
139
+ # * +backing_up+ -> +parked+
140
+ #
141
+ # Each edge will be labeled with the name of the event that would cause the
142
+ # transition.
143
+ def draw(graph, event, valid_states)
144
+ state_requirements.each do |state_requirement|
145
+ # From states determined based on the known valid states
146
+ from_states = state_requirement[:from].filter(valid_states)
147
+
148
+ # If a to state is not specified, then it's a loopback and each from
149
+ # state maps back to itself
150
+ if state_requirement[:to].values.empty?
151
+ loopback = true
152
+ else
153
+ to_state = state_requirement[:to].values.first
154
+ to_state = to_state ? to_state.to_s : 'nil'
155
+ loopback = false
156
+ end
157
+
158
+ # Generate an edge between each from and to state
159
+ from_states.each do |from_state|
160
+ from_state = from_state ? from_state.to_s : 'nil'
161
+ graph.add_edges(from_state, loopback ? from_state : to_state, :label => event.to_s)
162
+ end
163
+ end
164
+
165
+ true
166
+ end
167
+
168
+ protected
169
+ # Builds a matcher strategy to use for the given options. If neither a
170
+ # whitelist nor a blacklist option is specified, then an AllMatcher is
171
+ # built.
172
+ def build_matcher(options, whitelist_option, blacklist_option)
173
+ assert_exclusive_keys(options, whitelist_option, blacklist_option)
174
+
175
+ if options.include?(whitelist_option)
176
+ value = options[whitelist_option]
177
+ value.is_a?(Matcher) ? value : WhitelistMatcher.new(options[whitelist_option])
178
+ elsif options.include?(blacklist_option)
179
+ value = options[blacklist_option]
180
+ raise ArgumentError, ":#{blacklist_option} option cannot use matchers; use :#{whitelist_option} instead" if value.is_a?(Matcher)
181
+ BlacklistMatcher.new(value)
182
+ else
183
+ AllMatcher.instance
184
+ end
185
+ end
186
+
187
+ # Verifies that all configured requirements (event and state) match the
188
+ # given query. If a match is found, then a hash containing the
189
+ # event/state requirements that passed will be returned; otherwise, nil.
190
+ def match_query(query)
191
+ query ||= {}
192
+
193
+ if match_event(query) && (state_requirement = match_states(query))
194
+ state_requirement.merge(:on => event_requirement)
195
+ end
196
+ end
197
+
198
+ # Verifies that the event requirement matches the given query
199
+ def match_event(query)
200
+ matches_requirement?(query, :on, event_requirement)
201
+ end
202
+
203
+ # Verifies that the state requirements match the given query. If a
204
+ # matching requirement is found, then it is returned.
205
+ def match_states(query)
206
+ state_requirements.detect do |state_requirement|
207
+ [:from, :to].all? {|option| matches_requirement?(query, option, state_requirement[option])}
208
+ end
209
+ end
210
+
211
+ # Verifies that an option in the given query matches the values required
212
+ # for that option
213
+ def matches_requirement?(query, option, requirement)
214
+ !query.include?(option) || requirement.matches?(query[option], query)
215
+ end
216
+
217
+ # Verifies that the conditionals for this branch evaluate to true for the
218
+ # given object
219
+ def matches_conditions?(object, query)
220
+ query[:guard] == false ||
221
+ Array(if_condition).all? {|condition| evaluate_method(object, condition)} &&
222
+ !Array(unless_condition).any? {|condition| evaluate_method(object, condition)}
223
+ end
224
+ end
225
+ end
@@ -0,0 +1,232 @@
1
+ require 'enum_state_machine/branch'
2
+ require 'enum_state_machine/eval_helpers'
3
+
4
+ module EnumStateMachine
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 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
+ # == Examples
21
+ #
22
+ # When not bound to the object:
23
+ #
24
+ # class Vehicle
25
+ # state_machine do
26
+ # before_transition do |vehicle|
27
+ # vehicle.set_alarm
28
+ # end
29
+ # end
30
+ #
31
+ # def set_alarm
32
+ # ...
33
+ # end
34
+ # end
35
+ #
36
+ # When bound to the object:
37
+ #
38
+ # EnumStateMachine::Callback.bind_to_object = true
39
+ #
40
+ # class Vehicle
41
+ # state_machine do
42
+ # before_transition do
43
+ # self.set_alarm
44
+ # end
45
+ # end
46
+ #
47
+ # def set_alarm
48
+ # ...
49
+ # end
50
+ # end
51
+ attr_accessor :bind_to_object
52
+
53
+ # The application-wide terminator to use for callbacks when not
54
+ # explicitly defined. Terminators determine whether to cancel a
55
+ # callback chain based on the return value of the callback.
56
+ #
57
+ # See EnumStateMachine::Callback#terminator for more information.
58
+ attr_accessor :terminator
59
+ end
60
+
61
+ # The type of callback chain this callback is for. This can be one of the
62
+ # following:
63
+ # * +before+
64
+ # * +after+
65
+ # * +around+
66
+ # * +failure+
67
+ attr_accessor :type
68
+
69
+ # An optional block for determining whether to cancel the callback chain
70
+ # based on the return value of the callback. By default, the callback
71
+ # chain never cancels based on the return value (i.e. there is no implicit
72
+ # terminator). Certain integrations, such as ActiveRecord,
73
+ # change this default value.
74
+ #
75
+ # == Examples
76
+ #
77
+ # Canceling the callback chain without a terminator:
78
+ #
79
+ # class Vehicle
80
+ # state_machine do
81
+ # before_transition do |vehicle|
82
+ # throw :halt
83
+ # end
84
+ # end
85
+ # end
86
+ #
87
+ # Canceling the callback chain with a terminator value of +false+:
88
+ #
89
+ # class Vehicle
90
+ # state_machine do
91
+ # before_transition do |vehicle|
92
+ # false
93
+ # end
94
+ # end
95
+ # end
96
+ attr_reader :terminator
97
+
98
+ # The branch that determines whether or not this callback can be invoked
99
+ # based on the context of the transition. The event, from state, and
100
+ # to state must all match in order for the branch to pass.
101
+ #
102
+ # See EnumStateMachine::Branch for more information.
103
+ attr_reader :branch
104
+
105
+ # Creates a new callback that can get called based on the configured
106
+ # options.
107
+ #
108
+ # In addition to the possible configuration options for branches, the
109
+ # following options can be configured:
110
+ # * <tt>:bind_to_object</tt> - Whether to bind the callback to the object involved.
111
+ # If set to false, the object will be passed as a parameter instead.
112
+ # Default is integration-specific or set to the application default.
113
+ # * <tt>:terminator</tt> - A block/proc that determines what callback
114
+ # results should cause the callback chain to halt (if not using the
115
+ # default <tt>throw :halt</tt> technique).
116
+ #
117
+ # More information about how those options affect the behavior of the
118
+ # callback can be found in their attribute definitions.
119
+ def initialize(type, *args, &block)
120
+ @type = type
121
+ raise ArgumentError, 'Type must be :before, :after, :around, or :failure' unless [:before, :after, :around, :failure].include?(type)
122
+
123
+ options = args.last.is_a?(Hash) ? args.pop : {}
124
+ @methods = args
125
+ @methods.concat(Array(options.delete(:do)))
126
+ @methods << block if block_given?
127
+ raise ArgumentError, 'Method(s) for callback must be specified' unless @methods.any?
128
+
129
+ options = {:bind_to_object => self.class.bind_to_object, :terminator => self.class.terminator}.merge(options)
130
+
131
+ # Proxy lambda blocks so that they're bound to the object
132
+ bind_to_object = options.delete(:bind_to_object)
133
+ @methods.map! do |method|
134
+ bind_to_object && method.is_a?(Proc) ? bound_method(method) : method
135
+ end
136
+
137
+ @terminator = options.delete(:terminator)
138
+ @branch = Branch.new(options)
139
+ end
140
+
141
+ # Gets a list of the states known to this callback by looking at the
142
+ # branch's known states
143
+ def known_states
144
+ branch.known_states
145
+ end
146
+
147
+ # Runs the callback as long as the transition context matches the branch
148
+ # requirements configured for this callback. If a block is provided, it
149
+ # will be called when the last method has run.
150
+ #
151
+ # If a terminator has been configured and it matches the result from the
152
+ # evaluated method, then the callback chain should be halted.
153
+ def call(object, context = {}, *args, &block)
154
+ if @branch.matches?(object, context)
155
+ run_methods(object, context, 0, *args, &block)
156
+ true
157
+ else
158
+ false
159
+ end
160
+ end
161
+
162
+ private
163
+ # Runs all of the methods configured for this callback.
164
+ #
165
+ # When running +around+ callbacks, this will evaluate each method and
166
+ # yield when the last method has yielded. The callback will only halt if
167
+ # one of the methods does not yield.
168
+ #
169
+ # For all other types of callbacks, this will evaluate each method in
170
+ # order. The callback will only halt if the resulting value from the
171
+ # method passes the terminator.
172
+ def run_methods(object, context = {}, index = 0, *args, &block)
173
+ if type == :around
174
+ if current_method = @methods[index]
175
+ yielded = false
176
+ evaluate_method(object, current_method, *args) do
177
+ yielded = true
178
+ run_methods(object, context, index + 1, *args, &block)
179
+ end
180
+
181
+ throw :halt unless yielded
182
+ else
183
+ yield if block_given?
184
+ end
185
+ else
186
+ @methods.each do |method|
187
+ result = evaluate_method(object, method, *args)
188
+ throw :halt if @terminator && @terminator.call(result)
189
+ end
190
+ end
191
+ end
192
+
193
+ # Generates a method that can be bound to the object being transitioned
194
+ # when the callback is invoked
195
+ def bound_method(block)
196
+ type = self.type
197
+ arity = block.arity
198
+ arity += 1 if arity >= 0 # Make sure the object gets passed
199
+ arity += 1 if arity == 1 && type == :around # Make sure the block gets passed
200
+
201
+ method = if RUBY_VERSION >= '1.9'
202
+ lambda do |object, *args|
203
+ object.instance_exec(*args, &block)
204
+ end
205
+ else
206
+ # Generate a thread-safe unbound method that can be used on any object.
207
+ # This is a workaround for not having Ruby 1.9's instance_exec
208
+ unbound_method = Object.class_eval do
209
+ time = Time.now
210
+ method_name = "__bind_#{time.to_i}_#{time.usec}"
211
+ define_method(method_name, &block)
212
+ method = instance_method(method_name)
213
+ remove_method(method_name)
214
+ method
215
+ end
216
+
217
+ # Proxy calls to the method so that the method can be bound *and*
218
+ # the arguments are adjusted
219
+ lambda do |object, *args|
220
+ unbound_method.bind(object).call(*args)
221
+ end
222
+ end
223
+
224
+ # Proxy arity to the original block
225
+ (class << method; self; end).class_eval do
226
+ define_method(:arity) { arity }
227
+ end
228
+
229
+ method
230
+ end
231
+ end
232
+ end
@@ -0,0 +1,12 @@
1
+ module EnumStateMachine
2
+ # Graphing extensions aren't required, so they're loaded when referenced
3
+ autoload :Graph, 'enum_state_machine/graph'
4
+ end
5
+
6
+ # Load all of the core implementation required to use state_machine. This
7
+ # includes:
8
+ # * EnumStateMachine::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 'enum_state_machine/macro_methods'
12
+ require 'enum_state_machine/initializers'
@@ -0,0 +1,5 @@
1
+ require 'enum_state_machine/macro_methods'
2
+
3
+ Class.class_eval do
4
+ include EnumStateMachine::MacroMethods
5
+ end
@@ -0,0 +1,2 @@
1
+ # Loads all of the extensions to be made to Ruby core classes
2
+ require 'enum_state_machine/core_ext/class/state_machine'