state_machines-yard 0.0.1 → 0.3.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.
- checksums.yaml +5 -5
- data/.github/workflows/ci.yml +32 -0
- data/.github/workflows/release.yml +18 -0
- data/.release-please-manifest.json +3 -0
- data/.rubocop.yml +38 -0
- data/CHANGELOG.md +44 -0
- data/Gemfile +13 -0
- data/LICENSE.txt +1 -1
- data/README.md +50 -1
- data/Rakefile +29 -0
- data/lib/state_machines/yard/description.rb +74 -0
- data/lib/state_machines/yard/handlers/base.rb +122 -21
- data/lib/state_machines/yard/handlers/callback.rb +96 -0
- data/lib/state_machines/yard/handlers/event.rb +20 -11
- data/lib/state_machines/yard/handlers/machine.rb +263 -241
- data/lib/state_machines/yard/handlers/requirements.rb +92 -0
- data/lib/state_machines/yard/handlers/state.rb +20 -11
- data/lib/state_machines/yard/handlers/transition.rb +26 -31
- data/lib/state_machines/yard/handlers.rb +4 -6
- data/lib/state_machines/yard/renderer.rb +62 -0
- data/lib/state_machines/yard/templates/default/class/html/setup.rb +14 -7
- data/lib/state_machines/yard/templates/default/class/html/state_machines.erb +33 -0
- data/lib/state_machines/yard/templates.rb +2 -0
- data/lib/state_machines/yard/version.rb +3 -1
- data/lib/state_machines/yard.rb +15 -4
- data/release-please-config.json +11 -0
- data/state_machines-yard.gemspec +19 -11
- data/test/description_test.rb +99 -0
- data/test/handlers/base_test.rb +83 -0
- data/test/handlers/callback_test.rb +137 -0
- data/test/handlers/event_test.rb +97 -0
- data/test/handlers/guards_test.rb +180 -0
- data/test/handlers/machine_test.rb +156 -0
- data/test/handlers/review_test.rb +192 -0
- data/test/handlers/state_test.rb +73 -0
- data/test/handlers/transition_test.rb +142 -0
- data/test/integration_test.rb +163 -0
- data/test/templates_test.rb +95 -0
- data/test/test_helper.rb +51 -0
- metadata +146 -16
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module StateMachines
|
|
4
|
+
module Yard
|
|
5
|
+
module Handlers
|
|
6
|
+
# Reads the requirements and guards a transition or callback declares,
|
|
7
|
+
# as the core reads them, for handlers built on Base
|
|
8
|
+
module Requirements
|
|
9
|
+
# Conditions on the object
|
|
10
|
+
CONDITIONS = %i[if unless].freeze
|
|
11
|
+
# Conditions on the states of other machines, each a group of
|
|
12
|
+
# machine => state requirements
|
|
13
|
+
STATE_GUARDS = %i[if_state unless_state if_all_states unless_all_states if_any_state
|
|
14
|
+
unless_any_state].freeze
|
|
15
|
+
# The matchers the DSL names
|
|
16
|
+
MATCHERS = { all: AllMatcher, any: AllMatcher, same: LoopbackMatcher }.freeze
|
|
17
|
+
|
|
18
|
+
private
|
|
19
|
+
|
|
20
|
+
def option_value(name, node)
|
|
21
|
+
if CONDITIONS.include?(name) then condition(node)
|
|
22
|
+
elsif STATE_GUARDS.include?(name) then state_guard(node)
|
|
23
|
+
else requirement(node)
|
|
24
|
+
end
|
|
25
|
+
end
|
|
26
|
+
|
|
27
|
+
# A state or event requirement: a name, an Array of names, or a
|
|
28
|
+
# matcher (all, any, same, all - names)
|
|
29
|
+
def requirement(node)
|
|
30
|
+
case node
|
|
31
|
+
when Prism::CallNode then matcher(node)
|
|
32
|
+
when Prism::ArrayNode then node.elements.map { name_literal(it, nil_allowed: true) }
|
|
33
|
+
else name_literal(node, nil_allowed: true)
|
|
34
|
+
end
|
|
35
|
+
end
|
|
36
|
+
|
|
37
|
+
def matcher(node)
|
|
38
|
+
return MATCHERS.fetch(node.name).instance if bare_call?(node) && MATCHERS.key?(node.name)
|
|
39
|
+
return AllMatcher.instance - names_in(node.arguments.arguments.first, nil_allowed: true) if exclusion?(node)
|
|
40
|
+
|
|
41
|
+
unreadable(node)
|
|
42
|
+
end
|
|
43
|
+
|
|
44
|
+
# all - names, any - names
|
|
45
|
+
def exclusion?(node)
|
|
46
|
+
node.name == :- && all_matcher?(node.receiver) && node.arguments&.arguments&.one?
|
|
47
|
+
end
|
|
48
|
+
|
|
49
|
+
def all_matcher?(node)
|
|
50
|
+
node.is_a?(Prism::CallNode) && bare_call?(node) && MATCHERS[node.name] == AllMatcher
|
|
51
|
+
end
|
|
52
|
+
|
|
53
|
+
def bare_call?(node)
|
|
54
|
+
node.receiver.nil? && node.arguments.nil? && node.block.nil?
|
|
55
|
+
end
|
|
56
|
+
|
|
57
|
+
# An if:/unless: condition as the core reads it: nil and false are no
|
|
58
|
+
# condition, an Array is several, a Symbol names a method, a String is
|
|
59
|
+
# code. Anything else is code (a lambda, a method call) only known
|
|
60
|
+
# when it runs, so its source is documented as the condition
|
|
61
|
+
# (#condition_term).
|
|
62
|
+
def condition(node)
|
|
63
|
+
case node
|
|
64
|
+
when Prism::NilNode then nil
|
|
65
|
+
when Prism::FalseNode then false
|
|
66
|
+
when Prism::ArrayNode then node.elements.map { condition_term(it) }
|
|
67
|
+
else condition_term(node)
|
|
68
|
+
end
|
|
69
|
+
end
|
|
70
|
+
|
|
71
|
+
# A Symbol or String condition as written. Code (a lambda, a method
|
|
72
|
+
# call) is kept as a Symbol of its source: diagrams show it as
|
|
73
|
+
# written, and it is never taken for a String condition, which the
|
|
74
|
+
# core (and diagram introspection) validates and evaluates as code.
|
|
75
|
+
def condition_term(node)
|
|
76
|
+
case node
|
|
77
|
+
when Prism::SymbolNode, Prism::StringNode then literal(node)
|
|
78
|
+
else node.slice.to_sym
|
|
79
|
+
end
|
|
80
|
+
end
|
|
81
|
+
|
|
82
|
+
# A state guard: a Hash of machine => state, kept as one group
|
|
83
|
+
def state_guard(node)
|
|
84
|
+
guard = literal(node)
|
|
85
|
+
unreadable(node) unless guard.is_a?(Hash)
|
|
86
|
+
|
|
87
|
+
guard
|
|
88
|
+
end
|
|
89
|
+
end
|
|
90
|
+
end
|
|
91
|
+
end
|
|
92
|
+
end
|
|
@@ -1,23 +1,32 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module StateMachines
|
|
4
|
+
module Yard
|
|
3
5
|
module Handlers
|
|
4
6
|
# Handles and processes #state
|
|
5
7
|
class State < Base
|
|
6
8
|
handles method_call(:state)
|
|
7
9
|
|
|
10
|
+
# Store the handled method name for testing
|
|
11
|
+
@handles_method = :state
|
|
12
|
+
|
|
8
13
|
def process
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
14
|
+
return unless owner.is_a?(StateMachines::Machine)
|
|
15
|
+
|
|
16
|
+
handler = self
|
|
17
|
+
block = statement.block
|
|
18
|
+
names = positional_arguments.flat_map { names_in(it, nil_allowed: true) }
|
|
19
|
+
options = literal_options(%i[value human_name], code: %i[value human_name])
|
|
13
20
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
handler.parse_block(statement.last.last, owner: self)
|
|
18
|
-
end
|
|
21
|
+
names.each do |name|
|
|
22
|
+
owner.state(name, **options) do
|
|
23
|
+
handler.parse_block(block.last, owner: self) if block
|
|
19
24
|
end
|
|
20
25
|
end
|
|
26
|
+
rescue Unreadable, ArgumentError => e
|
|
27
|
+
# One the core refuses (a name of another type than the others) is
|
|
28
|
+
# not documented as something else
|
|
29
|
+
skip('state', e)
|
|
21
30
|
end
|
|
22
31
|
end
|
|
23
32
|
end
|
|
@@ -1,44 +1,39 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module StateMachines
|
|
4
|
+
module Yard
|
|
3
5
|
module Handlers
|
|
4
|
-
# Handles and processes #transition
|
|
6
|
+
# Handles and processes #transition. The documented machine gets the
|
|
7
|
+
# transition with the guards the core runs: if:/unless: conditions
|
|
8
|
+
# (each one of an Array, a String as the code it is, any other code
|
|
9
|
+
# by its source) and state guards with the requirements of each group.
|
|
5
10
|
class Transition < Base
|
|
6
11
|
handles method_call(:transition)
|
|
7
12
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
options = {}
|
|
13
|
+
# Store the handled method name for testing
|
|
14
|
+
@handles_method = :transition
|
|
11
15
|
|
|
12
|
-
|
|
13
|
-
ast = statement.parameters.first
|
|
14
|
-
ast.children.each do |assoc|
|
|
15
|
-
# Skip conditionals
|
|
16
|
-
next if %w(if unless).include?(assoc[0].jump(:ident).source)
|
|
16
|
+
include Requirements
|
|
17
17
|
|
|
18
|
-
|
|
19
|
-
|
|
18
|
+
def process
|
|
19
|
+
return unless [StateMachines::Machine, StateMachines::Event, StateMachines::State].include?(owner.class)
|
|
20
20
|
|
|
21
|
-
|
|
22
|
-
|
|
21
|
+
owner.transition(requirements)
|
|
22
|
+
rescue Unreadable, ArgumentError => e
|
|
23
|
+
# A transition that cannot be read, or that the core refuses, would
|
|
24
|
+
# be documented with other requirements or guards than it has
|
|
25
|
+
skip('transition', e)
|
|
23
26
|
end
|
|
24
27
|
|
|
25
28
|
private
|
|
26
|
-
|
|
27
|
-
def
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
case ast.source
|
|
35
|
-
when 'nil'
|
|
36
|
-
nil
|
|
37
|
-
when 'same'
|
|
38
|
-
LoopbackMatcher.instance
|
|
39
|
-
else
|
|
40
|
-
AllMatcher.instance
|
|
41
|
-
end
|
|
29
|
+
|
|
30
|
+
def requirements
|
|
31
|
+
pairs = option_pairs
|
|
32
|
+
unreadable(call_node) if pairs.empty?
|
|
33
|
+
|
|
34
|
+
pairs.to_h do |key, value|
|
|
35
|
+
name = requirement(key)
|
|
36
|
+
[name, option_value(name, value)]
|
|
42
37
|
end
|
|
43
38
|
end
|
|
44
39
|
end
|
|
@@ -1,12 +1,10 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module StateMachines
|
|
4
|
+
module Yard
|
|
3
5
|
# YARD custom handlers for integrating the state_machine DSL with the
|
|
4
6
|
# YARD documentation system
|
|
5
7
|
module Handlers
|
|
6
8
|
end
|
|
7
9
|
end
|
|
8
10
|
end
|
|
9
|
-
|
|
10
|
-
Dir["#{File.dirname(__FILE__)}/handlers/*.rb"].sort.each do |path|
|
|
11
|
-
require "state_machines/yard/handlers/#{File.basename(path)}"
|
|
12
|
-
end
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'stringio'
|
|
4
|
+
require 'tmpdir'
|
|
5
|
+
|
|
6
|
+
module StateMachines
|
|
7
|
+
module Yard
|
|
8
|
+
# Draws a documented machine with the renderer STATE_MACHINES_RENDERER
|
|
9
|
+
# names (graphviz, mermaid or none), guards included
|
|
10
|
+
module Renderer
|
|
11
|
+
module_function
|
|
12
|
+
|
|
13
|
+
def selection
|
|
14
|
+
env = ENV.fetch('STATE_MACHINES_RENDERER', nil)
|
|
15
|
+
return env.to_sym if %w[graphviz mermaid none].include?(env)
|
|
16
|
+
|
|
17
|
+
:none
|
|
18
|
+
end
|
|
19
|
+
|
|
20
|
+
# The diagram, or nil. A renderer that fails on a machine leaves its
|
|
21
|
+
# diagram out with a warning; the rest of its documentation stands.
|
|
22
|
+
def render(machine)
|
|
23
|
+
case selection
|
|
24
|
+
when :graphviz then render_graphviz(machine)
|
|
25
|
+
when :mermaid then render_mermaid(machine)
|
|
26
|
+
end
|
|
27
|
+
rescue StandardError, SecurityError => e
|
|
28
|
+
log.warn "state_machines-yard: no #{selection} diagram for #{machine.owner_class} #{machine.name}: " \
|
|
29
|
+
"#{e.class}: #{e.message}"
|
|
30
|
+
nil
|
|
31
|
+
end
|
|
32
|
+
|
|
33
|
+
# The machine as a PNG. Drawn with the GraphViz renderer itself:
|
|
34
|
+
# Machine#draw goes through whichever renderer is global.
|
|
35
|
+
def render_graphviz(machine)
|
|
36
|
+
require 'state_machines/graphviz'
|
|
37
|
+
|
|
38
|
+
Dir.mktmpdir('state_machines-yard') do |dir|
|
|
39
|
+
graph = StateMachines::Graphviz::Renderer.draw_machine(
|
|
40
|
+
machine, name: 'state_machine', path: dir, format: 'png', orientation: 'landscape'
|
|
41
|
+
)
|
|
42
|
+
{ image: File.binread(graph.file_path) }
|
|
43
|
+
end
|
|
44
|
+
rescue LoadError
|
|
45
|
+
nil
|
|
46
|
+
end
|
|
47
|
+
|
|
48
|
+
def render_mermaid(machine)
|
|
49
|
+
require 'state_machines-mermaid'
|
|
50
|
+
|
|
51
|
+
io = StringIO.new
|
|
52
|
+
StateMachines::Mermaid::Renderer.draw_machine(machine, io: io, show_conditions: true, show_callbacks: true)
|
|
53
|
+
mermaid = io.string
|
|
54
|
+
return nil if mermaid.strip.empty?
|
|
55
|
+
|
|
56
|
+
{ mermaid: mermaid }
|
|
57
|
+
rescue LoadError
|
|
58
|
+
nil
|
|
59
|
+
end
|
|
60
|
+
end
|
|
61
|
+
end
|
|
62
|
+
end
|
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
1
3
|
# Define where state machine descriptions will be rendered
|
|
2
4
|
def init
|
|
3
5
|
super
|
|
@@ -11,13 +13,18 @@ end
|
|
|
11
13
|
|
|
12
14
|
# Gets a list of state machines for this class
|
|
13
15
|
def state_machines
|
|
14
|
-
@state_machines ||=
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
16
|
+
@state_machines ||= if (state_machines = object['state_machines'])
|
|
17
|
+
@has_mermaid = state_machines.any? { |_name, machine| machine[:mermaid] }
|
|
18
|
+
state_machines.each_value do |machine|
|
|
19
|
+
serializer.serialize(state_machine_image_path(machine), machine[:image]) if machine[:image]
|
|
20
|
+
end
|
|
21
|
+
state_machines
|
|
22
|
+
end
|
|
23
|
+
end
|
|
24
|
+
|
|
25
|
+
def mermaid?
|
|
26
|
+
state_machines
|
|
27
|
+
@has_mermaid
|
|
21
28
|
end
|
|
22
29
|
|
|
23
30
|
# Generates the image path for the given machine's visualization
|
|
@@ -2,11 +2,44 @@
|
|
|
2
2
|
|
|
3
3
|
This class contains <%= state_machines.count %> state machine(s).
|
|
4
4
|
|
|
5
|
+
<% if mermaid? %>
|
|
6
|
+
<script src="https://cdn.jsdelivr.net/npm/mermaid@10.9.1/dist/mermaid.min.js"></script>
|
|
7
|
+
<script>mermaid.initialize({ startOnLoad: true });</script>
|
|
8
|
+
<% end %>
|
|
9
|
+
|
|
5
10
|
<% state_machines.each do |name, machine| %>
|
|
6
11
|
<h3><%= h(machine[:name]) %></h3>
|
|
7
12
|
<p><%= h(machine[:description]) %></p>
|
|
8
13
|
|
|
14
|
+
<% if machine[:events]&.any? %>
|
|
15
|
+
<h4>Events</h4>
|
|
16
|
+
<dl class="state_machine_events">
|
|
17
|
+
<% machine[:events].each do |event| %>
|
|
18
|
+
<dt><tt><%= h(event[:name]) %></tt></dt>
|
|
19
|
+
<dd>
|
|
20
|
+
<% if event[:error] %>
|
|
21
|
+
<p>Its transitions cannot be described: <%= h(event[:error]) %></p>
|
|
22
|
+
<% elsif event[:transitions].empty? %>
|
|
23
|
+
<p>No transitions: it never fires.</p>
|
|
24
|
+
<% else %>
|
|
25
|
+
<p>Transitions (from each state the first that matches is taken):</p>
|
|
26
|
+
<ul>
|
|
27
|
+
<% event[:transitions].each do |transition| %>
|
|
28
|
+
<li><tt><%= h(transition) %></tt></li>
|
|
29
|
+
<% end %>
|
|
30
|
+
</ul>
|
|
31
|
+
<% end %>
|
|
32
|
+
<% if event[:failure].any? %>
|
|
33
|
+
<p>On failure: <tt><%= h(event[:failure].join(', ')) %></tt></p>
|
|
34
|
+
<% end %>
|
|
35
|
+
</dd>
|
|
36
|
+
<% end %>
|
|
37
|
+
</dl>
|
|
38
|
+
<% end %>
|
|
39
|
+
|
|
9
40
|
<% if machine[:image] %>
|
|
10
41
|
<img alt="State machine diagram for <%= h(machine[:name]) %>" src="<%= url_for(state_machine_image_path(machine)) %>"/>
|
|
42
|
+
<% elsif machine[:mermaid] %>
|
|
43
|
+
<pre class="mermaid"><%= h(machine[:mermaid]) %></pre>
|
|
11
44
|
<% end %>
|
|
12
45
|
<% end %>
|
data/lib/state_machines/yard.rb
CHANGED
|
@@ -1,10 +1,21 @@
|
|
|
1
|
-
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'yard'
|
|
4
|
+
require 'state_machines'
|
|
5
|
+
require_relative 'yard/version'
|
|
2
6
|
module StateMachines
|
|
3
7
|
# YARD plugin for automated documentation
|
|
4
8
|
module Yard
|
|
5
9
|
end
|
|
6
10
|
end
|
|
7
11
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
12
|
+
require_relative 'yard/description'
|
|
13
|
+
require_relative 'yard/handlers'
|
|
14
|
+
require_relative 'yard/handlers/base'
|
|
15
|
+
require_relative 'yard/handlers/requirements'
|
|
16
|
+
require_relative 'yard/handlers/callback'
|
|
17
|
+
require_relative 'yard/handlers/event'
|
|
18
|
+
require_relative 'yard/handlers/machine'
|
|
19
|
+
require_relative 'yard/handlers/state'
|
|
20
|
+
require_relative 'yard/handlers/transition'
|
|
21
|
+
require_relative 'yard/templates'
|
data/state_machines-yard.gemspec
CHANGED
|
@@ -1,25 +1,33 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
require 'state_machines/yard/version'
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require_relative 'lib/state_machines/yard/version'
|
|
5
4
|
|
|
6
5
|
Gem::Specification.new do |spec|
|
|
7
6
|
spec.name = 'state_machines-yard'
|
|
8
7
|
spec.version = StateMachines::Yard::VERSION
|
|
9
8
|
spec.authors = ['Abdelkader Boudih', 'Aaron Pfeifer']
|
|
10
9
|
spec.email = ['terminale@gmail.com']
|
|
11
|
-
spec.summary =
|
|
12
|
-
spec.description =
|
|
13
|
-
spec.homepage = 'https://github.com/
|
|
10
|
+
spec.summary = 'State machines YARD plugin'
|
|
11
|
+
spec.description = 'State machines YARD plugin for automated documentation'
|
|
12
|
+
spec.homepage = 'https://github.com/state-machines/state_machines-yard'
|
|
14
13
|
spec.license = 'MIT'
|
|
15
14
|
|
|
16
|
-
spec.required_ruby_version
|
|
15
|
+
spec.required_ruby_version = '>= 4.0'
|
|
17
16
|
|
|
18
17
|
spec.files = `git ls-files -z`.split("\x0")
|
|
19
18
|
spec.require_paths = ['lib']
|
|
20
19
|
|
|
20
|
+
spec.add_dependency 'rdoc'
|
|
21
|
+
spec.add_dependency 'state_machines', '>= 0.303.0'
|
|
22
|
+
spec.add_dependency 'state_machines-diagram', '>= 0.3.0'
|
|
21
23
|
spec.add_dependency 'yard'
|
|
22
|
-
spec.
|
|
23
|
-
spec.add_development_dependency '
|
|
24
|
-
spec.add_development_dependency '
|
|
24
|
+
spec.add_development_dependency 'bundler', '>= 4.0'
|
|
25
|
+
spec.add_development_dependency 'minitest', '~> 6.0'
|
|
26
|
+
spec.add_development_dependency 'nokogiri'
|
|
27
|
+
spec.add_development_dependency 'rake', '~> 13.0'
|
|
28
|
+
spec.add_development_dependency 'rubocop', '~> 1.59'
|
|
29
|
+
spec.add_development_dependency 'rubocop-minitest', '~> 0.34'
|
|
30
|
+
spec.add_development_dependency 'rubocop-performance', '~> 1.20'
|
|
31
|
+
spec.add_development_dependency 'rubocop-rake', '~> 0.6'
|
|
32
|
+
spec.metadata['rubygems_mfa_required'] = 'true'
|
|
25
33
|
end
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'test_helper'
|
|
4
|
+
|
|
5
|
+
# The generated documentation lists each event's transitions, guards and
|
|
6
|
+
# callbacks as text whichever renderer draws the diagram, or none
|
|
7
|
+
class DescriptionTest < Minitest::Test
|
|
8
|
+
include TestHelpers
|
|
9
|
+
|
|
10
|
+
CODE = <<~RUBY
|
|
11
|
+
class Vehicle
|
|
12
|
+
state_machine :status, initial: :parked do
|
|
13
|
+
before_transition from: :parked, do: :check_mirrors
|
|
14
|
+
after_transition to: :idling, do: :log_start, if: :logging?
|
|
15
|
+
after_failure on: :ignite, do: :alert
|
|
16
|
+
|
|
17
|
+
event :ignite do
|
|
18
|
+
transition parked: :idling, if: :engine_ok?, if_any_state: { gate: :open, alarm: :off }
|
|
19
|
+
transition parked: :stalled
|
|
20
|
+
transition parked: :never
|
|
21
|
+
end
|
|
22
|
+
|
|
23
|
+
event :noop
|
|
24
|
+
end
|
|
25
|
+
end
|
|
26
|
+
RUBY
|
|
27
|
+
|
|
28
|
+
IGNITE = [
|
|
29
|
+
'parked -> idling [if engine_ok? && if_any_state (gate=open, alarm=off)] / before check_mirrors, ' \
|
|
30
|
+
'after log_start (if logging?)',
|
|
31
|
+
'parked -> stalled / before check_mirrors'
|
|
32
|
+
].freeze
|
|
33
|
+
|
|
34
|
+
DIAGRAMS = { 'none' => [], 'graphviz' => ['img'], 'mermaid' => ['pre.mermaid'] }.freeze
|
|
35
|
+
|
|
36
|
+
def setup
|
|
37
|
+
setup_yard
|
|
38
|
+
@previous_renderer = ENV.fetch('STATE_MACHINES_RENDERER', nil)
|
|
39
|
+
end
|
|
40
|
+
|
|
41
|
+
def teardown
|
|
42
|
+
ENV['STATE_MACHINES_RENDERER'] = @previous_renderer
|
|
43
|
+
cleanup_yard
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
def document(renderer)
|
|
47
|
+
ENV['STATE_MACHINES_RENDERER'] = renderer
|
|
48
|
+
YARD::Registry.clear
|
|
49
|
+
parse_code(CODE)
|
|
50
|
+
YARD::CLI::Yardoc.run('--no-save', '--no-progress', '--quiet', '-o', @yard_dir)
|
|
51
|
+
Nokogiri::HTML(File.read(File.join(@yard_dir, 'Vehicle.html')))
|
|
52
|
+
end
|
|
53
|
+
|
|
54
|
+
def test_each_renderer_mode_documents_the_events_as_text
|
|
55
|
+
DIAGRAMS.each do |renderer, diagram|
|
|
56
|
+
html = document(renderer)
|
|
57
|
+
events = html.css('dl.state_machine_events')
|
|
58
|
+
|
|
59
|
+
assert_equal(%w[ignite noop], events.css('dt').map { it.text.strip }, renderer)
|
|
60
|
+
assert_equal(IGNITE, events.css('dd').first.css('li').map { it.text.strip }, renderer)
|
|
61
|
+
assert_includes(events.css('dd').first.text, 'On failure: alert', renderer)
|
|
62
|
+
assert_includes(events.css('dd').last.text, 'No transitions: it never fires.', renderer)
|
|
63
|
+
assert_equal(diagram.size, diagram.sum { html.css(it).size }, renderer)
|
|
64
|
+
end
|
|
65
|
+
end
|
|
66
|
+
|
|
67
|
+
def test_callbacks_read_in_the_order_the_core_runs_them
|
|
68
|
+
machine = parse_machines(<<~RUBY)['Lamp'][:state]
|
|
69
|
+
class Lamp
|
|
70
|
+
state_machine initial: :off do
|
|
71
|
+
around_transition on: :switch, do: :hold
|
|
72
|
+
before_transition from: :off, do: :check
|
|
73
|
+
after_transition do: :log
|
|
74
|
+
around_transition on: :switch, do: :time
|
|
75
|
+
event(:switch) { transition off: :on }
|
|
76
|
+
end
|
|
77
|
+
end
|
|
78
|
+
RUBY
|
|
79
|
+
|
|
80
|
+
assert_equal(['off -> on / around hold, before check, around time, after log'],
|
|
81
|
+
StateMachines::Yard::Description.events(machine).first[:transitions])
|
|
82
|
+
end
|
|
83
|
+
|
|
84
|
+
def test_each_renderer_mode_documents_the_event_methods
|
|
85
|
+
DIAGRAMS.each_key do |renderer|
|
|
86
|
+
document(renderer)
|
|
87
|
+
ignite = YARD::Registry.at('Vehicle#ignite').docstring
|
|
88
|
+
ignite_bang = YARD::Registry.at('Vehicle#ignite!').docstring
|
|
89
|
+
|
|
90
|
+
[ignite, ignite_bang].each do |docstring|
|
|
91
|
+
IGNITE.each { assert_includes(docstring, "* #{it}", renderer) }
|
|
92
|
+
|
|
93
|
+
assert_includes(docstring, 'On failure: alert', renderer)
|
|
94
|
+
end
|
|
95
|
+
assert_includes(YARD::Registry.at('Vehicle#noop').docstring, 'No transitions: it never fires.', renderer)
|
|
96
|
+
assert_equal(['@param', '@return'], YARD::Registry.at('Vehicle#ignite').tags.map { "@#{it.tag_name}" })
|
|
97
|
+
end
|
|
98
|
+
end
|
|
99
|
+
end
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'test_helper'
|
|
4
|
+
|
|
5
|
+
class BaseHandlerTest < Minitest::Test
|
|
6
|
+
include TestHelpers
|
|
7
|
+
|
|
8
|
+
def setup
|
|
9
|
+
setup_yard
|
|
10
|
+
end
|
|
11
|
+
|
|
12
|
+
def teardown
|
|
13
|
+
cleanup_yard
|
|
14
|
+
end
|
|
15
|
+
|
|
16
|
+
def test_symbol_state_name
|
|
17
|
+
code = <<-RUBY
|
|
18
|
+
class TestClass
|
|
19
|
+
state_machine :status do
|
|
20
|
+
# Test using a symbol
|
|
21
|
+
state :parked
|
|
22
|
+
end
|
|
23
|
+
end
|
|
24
|
+
RUBY
|
|
25
|
+
|
|
26
|
+
parse_code(code)
|
|
27
|
+
|
|
28
|
+
# The name was read from the symbol literal
|
|
29
|
+
test_class = YARD::Registry.at('TestClass')
|
|
30
|
+
|
|
31
|
+
refute_nil test_class, 'TestClass should be registered'
|
|
32
|
+
|
|
33
|
+
parked_method = YARD::Registry.at('TestClass#parked?')
|
|
34
|
+
|
|
35
|
+
refute_nil parked_method, 'parked? method should be registered'
|
|
36
|
+
end
|
|
37
|
+
|
|
38
|
+
def test_string_state_name
|
|
39
|
+
code = <<-RUBY
|
|
40
|
+
class TestClass
|
|
41
|
+
state_machine :status do
|
|
42
|
+
# Test using a string
|
|
43
|
+
state "moving"
|
|
44
|
+
end
|
|
45
|
+
end
|
|
46
|
+
RUBY
|
|
47
|
+
|
|
48
|
+
parse_code(code)
|
|
49
|
+
|
|
50
|
+
# Test that string nodes were correctly processed
|
|
51
|
+
test_class = YARD::Registry.at('TestClass')
|
|
52
|
+
|
|
53
|
+
refute_nil test_class, 'TestClass should be registered'
|
|
54
|
+
|
|
55
|
+
moving_method = YARD::Registry.at('TestClass#moving?')
|
|
56
|
+
|
|
57
|
+
refute_nil moving_method, 'moving? method should be registered'
|
|
58
|
+
end
|
|
59
|
+
|
|
60
|
+
def test_several_state_names
|
|
61
|
+
code = <<-RUBY
|
|
62
|
+
class TestClass
|
|
63
|
+
state_machine :status do
|
|
64
|
+
# Test using an array
|
|
65
|
+
state :parked, :idling, :moving
|
|
66
|
+
end
|
|
67
|
+
end
|
|
68
|
+
RUBY
|
|
69
|
+
|
|
70
|
+
parse_code(code)
|
|
71
|
+
|
|
72
|
+
# Test that array nodes were correctly processed
|
|
73
|
+
test_class = YARD::Registry.at('TestClass')
|
|
74
|
+
|
|
75
|
+
refute_nil test_class, 'TestClass should be registered'
|
|
76
|
+
|
|
77
|
+
%w[parked idling moving].each do |state|
|
|
78
|
+
method = YARD::Registry.at("TestClass##{state}?")
|
|
79
|
+
|
|
80
|
+
refute_nil method, "#{state}? method should be registered"
|
|
81
|
+
end
|
|
82
|
+
end
|
|
83
|
+
end
|