state_machines-yard 0.1.0 → 0.4.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 +4 -4
- data/.github/workflows/ci.yml +12 -4
- data/.github/workflows/release.yml +8 -6
- data/.release-please-manifest.json +3 -0
- data/.rubocop.yml +38 -0
- data/CHANGELOG.md +54 -0
- data/Gemfile +12 -1
- data/README.md +45 -0
- data/Rakefile +21 -3
- data/lib/state_machines/yard/description.rb +77 -0
- data/lib/state_machines/yard/handlers/actions.rb +113 -0
- data/lib/state_machines/yard/handlers/base.rb +145 -20
- data/lib/state_machines/yard/handlers/callback.rb +56 -0
- data/lib/state_machines/yard/handlers/event.rb +16 -12
- data/lib/state_machines/yard/handlers/machine.rb +258 -253
- data/lib/state_machines/yard/handlers/requirements.rb +92 -0
- data/lib/state_machines/yard/handlers/state.rb +16 -12
- data/lib/state_machines/yard/handlers/transition.rb +59 -30
- data/lib/state_machines/yard/handlers.rb +3 -1
- 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 +7 -0
- data/release-please-config.json +11 -0
- data/state_machines-yard.gemspec +16 -8
- data/test/description_test.rb +138 -0
- data/test/handlers/base_test.rb +43 -18
- data/test/handlers/callback_test.rb +168 -0
- data/test/handlers/event_test.rb +32 -19
- data/test/handlers/guards_test.rb +180 -0
- data/test/handlers/machine_test.rb +100 -16
- data/test/handlers/review_test.rb +192 -0
- data/test/handlers/state_test.rb +20 -13
- data/test/handlers/transition_test.rb +154 -19
- data/test/integration_test.rb +47 -36
- data/test/templates_test.rb +39 -16
- data/test/test_helper.rb +24 -10
- metadata +103 -20
|
@@ -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,28 +1,32 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
1
3
|
module StateMachines
|
|
2
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
|
+
|
|
8
10
|
# Store the handled method name for testing
|
|
9
11
|
@handles_method = :state
|
|
10
12
|
|
|
11
13
|
def process
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
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])
|
|
16
20
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
if statement.block
|
|
21
|
-
handler.parse_block(statement.block.last, owner: self)
|
|
22
|
-
end
|
|
23
|
-
end
|
|
21
|
+
names.each do |name|
|
|
22
|
+
owner.state(name, **options) do
|
|
23
|
+
handler.parse_block(block.last, owner: self) if block
|
|
24
24
|
end
|
|
25
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)
|
|
26
30
|
end
|
|
27
31
|
end
|
|
28
32
|
end
|
|
@@ -1,49 +1,78 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
1
3
|
module StateMachines
|
|
2
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,
|
|
10
|
+
# and its own before:/around:/after: callbacks, each method read as a
|
|
11
|
+
# transition callback's (Actions): a lambda or other code is a method
|
|
12
|
+
# the transition runs, not a state.
|
|
5
13
|
class Transition < Base
|
|
6
14
|
handles method_call(:transition)
|
|
7
|
-
|
|
15
|
+
|
|
8
16
|
# Store the handled method name for testing
|
|
9
17
|
@handles_method = :transition
|
|
10
18
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
options = {}
|
|
19
|
+
include Requirements
|
|
20
|
+
include Actions
|
|
14
21
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
22
|
+
# What a transition is declared on: a machine, an event, or a state's
|
|
23
|
+
# block (state :parked do ... end), whose owner is its StateContext
|
|
24
|
+
OWNERS = [StateMachines::Machine, StateMachines::Event, StateMachines::StateContext].freeze
|
|
25
|
+
# The options that hold the transition's own callbacks
|
|
26
|
+
CALLBACKS = %i[before around after].freeze
|
|
27
|
+
# Literals whose value is never a method name (Symbol, String), Proc
|
|
28
|
+
# or Method, which is all the core takes as a transition's callback
|
|
29
|
+
NOT_METHODS = [
|
|
30
|
+
*KEYWORDS.keys, *NUMBERS, Prism::RationalNode, Prism::ImaginaryNode, Prism::RegularExpressionNode,
|
|
31
|
+
Prism::InterpolatedRegularExpressionNode, Prism::HashNode, Prism::RangeNode, Prism::SourceLineNode,
|
|
32
|
+
Prism::SourceEncodingNode
|
|
33
|
+
].freeze
|
|
20
34
|
|
|
21
|
-
|
|
22
|
-
|
|
35
|
+
def process
|
|
36
|
+
return unless OWNERS.include?(owner.class)
|
|
23
37
|
|
|
24
|
-
|
|
25
|
-
|
|
38
|
+
owner.transition(requirements)
|
|
39
|
+
rescue Unreadable, ArgumentError => e
|
|
40
|
+
# A transition that cannot be read, or that the core refuses, would
|
|
41
|
+
# be documented with other requirements or guards than it has
|
|
42
|
+
skip('transition', e)
|
|
26
43
|
end
|
|
27
44
|
|
|
28
45
|
private
|
|
29
|
-
|
|
30
|
-
def
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
case ast.source
|
|
38
|
-
when 'nil'
|
|
39
|
-
nil
|
|
40
|
-
when 'same'
|
|
41
|
-
LoopbackMatcher.instance
|
|
42
|
-
else
|
|
43
|
-
AllMatcher.instance
|
|
44
|
-
end
|
|
46
|
+
|
|
47
|
+
def requirements
|
|
48
|
+
pairs = option_pairs
|
|
49
|
+
unreadable(call_node) if pairs.empty?
|
|
50
|
+
|
|
51
|
+
pairs.to_h do |key, value|
|
|
52
|
+
name = requirement(key)
|
|
53
|
+
[name, CALLBACKS.include?(name) ? own_callbacks(value) : option_value(name, value)]
|
|
45
54
|
end
|
|
46
55
|
end
|
|
56
|
+
|
|
57
|
+
# The methods of a before:/around:/after: option: one, or an Array of
|
|
58
|
+
# them, each read through any parentheses around it. A literal that
|
|
59
|
+
# is no method (nil, true, a number, a Regexp, a Hash, a Range, an
|
|
60
|
+
# Array inside the list) is kept as code the core refuses, as it
|
|
61
|
+
# refuses that literal when the class loads.
|
|
62
|
+
def own_callbacks(node)
|
|
63
|
+
node = unwrap(node)
|
|
64
|
+
return node.elements.map { own_callback(it) } if node.is_a?(Prism::ArrayNode)
|
|
65
|
+
|
|
66
|
+
own_callback(node)
|
|
67
|
+
end
|
|
68
|
+
|
|
69
|
+
def own_callback(node)
|
|
70
|
+
node = unwrap(node)
|
|
71
|
+
return Code.new(node.slice) if node.is_a?(Prism::ArrayNode) || nil_literal?(node) ||
|
|
72
|
+
NOT_METHODS.any? { node.is_a?(it) }
|
|
73
|
+
|
|
74
|
+
action(node)
|
|
75
|
+
end
|
|
47
76
|
end
|
|
48
77
|
end
|
|
49
78
|
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,4 +1,7 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
1
3
|
require 'yard'
|
|
4
|
+
require 'state_machines'
|
|
2
5
|
require_relative 'yard/version'
|
|
3
6
|
module StateMachines
|
|
4
7
|
# YARD plugin for automated documentation
|
|
@@ -6,8 +9,12 @@ module StateMachines
|
|
|
6
9
|
end
|
|
7
10
|
end
|
|
8
11
|
|
|
12
|
+
require_relative 'yard/description'
|
|
9
13
|
require_relative 'yard/handlers'
|
|
10
14
|
require_relative 'yard/handlers/base'
|
|
15
|
+
require_relative 'yard/handlers/requirements'
|
|
16
|
+
require_relative 'yard/handlers/actions'
|
|
17
|
+
require_relative 'yard/handlers/callback'
|
|
11
18
|
require_relative 'yard/handlers/event'
|
|
12
19
|
require_relative 'yard/handlers/machine'
|
|
13
20
|
require_relative 'yard/handlers/state'
|
data/state_machines-yard.gemspec
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
1
3
|
require_relative 'lib/state_machines/yard/version'
|
|
2
4
|
|
|
3
5
|
Gem::Specification.new do |spec|
|
|
@@ -5,21 +7,27 @@ Gem::Specification.new do |spec|
|
|
|
5
7
|
spec.version = StateMachines::Yard::VERSION
|
|
6
8
|
spec.authors = ['Abdelkader Boudih', 'Aaron Pfeifer']
|
|
7
9
|
spec.email = ['terminale@gmail.com']
|
|
8
|
-
spec.summary =
|
|
9
|
-
spec.description =
|
|
10
|
+
spec.summary = 'State machines YARD plugin'
|
|
11
|
+
spec.description = 'State machines YARD plugin for automated documentation'
|
|
10
12
|
spec.homepage = 'https://github.com/state-machines/state_machines-yard'
|
|
11
13
|
spec.license = 'MIT'
|
|
12
14
|
|
|
13
|
-
spec.required_ruby_version
|
|
15
|
+
spec.required_ruby_version = '>= 4.0'
|
|
14
16
|
|
|
15
17
|
spec.files = `git ls-files -z`.split("\x0")
|
|
16
18
|
spec.require_paths = ['lib']
|
|
17
19
|
|
|
18
|
-
spec.add_dependency 'yard'
|
|
19
|
-
spec.add_dependency 'state_machines-graphviz'
|
|
20
20
|
spec.add_dependency 'rdoc'
|
|
21
|
-
spec.
|
|
22
|
-
spec.
|
|
23
|
-
spec.
|
|
21
|
+
spec.add_dependency 'state_machines', '>= 0.304.0'
|
|
22
|
+
spec.add_dependency 'state_machines-diagram', '>= 0.4.0'
|
|
23
|
+
spec.add_dependency 'yard'
|
|
24
|
+
spec.add_development_dependency 'bundler', '>= 4.0'
|
|
25
|
+
spec.add_development_dependency 'minitest', '~> 6.0'
|
|
24
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,138 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'test_helper'
|
|
4
|
+
require 'state_machines/yard/renderer'
|
|
5
|
+
|
|
6
|
+
# The generated documentation lists each event's transitions, guards and
|
|
7
|
+
# callbacks as text whichever renderer draws the diagram, or none
|
|
8
|
+
class DescriptionTest < Minitest::Test
|
|
9
|
+
include TestHelpers
|
|
10
|
+
|
|
11
|
+
CODE = <<~RUBY
|
|
12
|
+
class Vehicle
|
|
13
|
+
state_machine :status, initial: :parked do
|
|
14
|
+
before_transition from: :parked, do: :check_mirrors
|
|
15
|
+
after_transition to: :idling, do: :log_start, if: :logging?
|
|
16
|
+
after_failure on: :ignite, do: :alert
|
|
17
|
+
|
|
18
|
+
event :ignite do
|
|
19
|
+
transition parked: :idling, if: :engine_ok?, if_any_state: { gate: :open, alarm: :off }
|
|
20
|
+
transition parked: :stalled
|
|
21
|
+
transition parked: :never
|
|
22
|
+
end
|
|
23
|
+
|
|
24
|
+
event :noop
|
|
25
|
+
end
|
|
26
|
+
end
|
|
27
|
+
RUBY
|
|
28
|
+
|
|
29
|
+
IGNITE = [
|
|
30
|
+
'parked -> idling [if engine_ok? && if_any_state (gate=open, alarm=off)] / before check_mirrors, ' \
|
|
31
|
+
'after log_start (if logging?)',
|
|
32
|
+
'parked -> stalled / before check_mirrors'
|
|
33
|
+
].freeze
|
|
34
|
+
|
|
35
|
+
DIAGRAMS = { 'none' => [], 'graphviz' => ['img'], 'mermaid' => ['pre.mermaid'] }.freeze
|
|
36
|
+
|
|
37
|
+
def setup
|
|
38
|
+
setup_yard
|
|
39
|
+
@previous_renderer = ENV.fetch('STATE_MACHINES_RENDERER', nil)
|
|
40
|
+
end
|
|
41
|
+
|
|
42
|
+
def teardown
|
|
43
|
+
ENV['STATE_MACHINES_RENDERER'] = @previous_renderer
|
|
44
|
+
cleanup_yard
|
|
45
|
+
end
|
|
46
|
+
|
|
47
|
+
def document(renderer)
|
|
48
|
+
ENV['STATE_MACHINES_RENDERER'] = renderer
|
|
49
|
+
YARD::Registry.clear
|
|
50
|
+
parse_code(CODE)
|
|
51
|
+
YARD::CLI::Yardoc.run('--no-save', '--no-progress', '--quiet', '-o', @yard_dir)
|
|
52
|
+
Nokogiri::HTML(File.read(File.join(@yard_dir, 'Vehicle.html')))
|
|
53
|
+
end
|
|
54
|
+
|
|
55
|
+
def test_each_renderer_mode_documents_the_events_as_text
|
|
56
|
+
DIAGRAMS.each do |renderer, diagram|
|
|
57
|
+
html = document(renderer)
|
|
58
|
+
events = html.css('dl.state_machine_events')
|
|
59
|
+
|
|
60
|
+
assert_equal(%w[ignite noop], events.css('dt').map { it.text.strip }, renderer)
|
|
61
|
+
assert_equal(IGNITE, events.css('dd').first.css('li').map { it.text.strip }, renderer)
|
|
62
|
+
assert_includes(events.css('dd').first.text, 'On failure: alert', renderer)
|
|
63
|
+
assert_includes(events.css('dd').last.text, 'No transitions: it never fires.', renderer)
|
|
64
|
+
assert_equal(diagram.size, diagram.sum { html.css(it).size }, renderer)
|
|
65
|
+
end
|
|
66
|
+
end
|
|
67
|
+
|
|
68
|
+
def test_callbacks_read_in_the_order_the_core_runs_them
|
|
69
|
+
machine = parse_machines(<<~RUBY)['Lamp'][:state]
|
|
70
|
+
class Lamp
|
|
71
|
+
state_machine initial: :off do
|
|
72
|
+
around_transition on: :switch, do: :hold
|
|
73
|
+
before_transition from: :off, do: :check
|
|
74
|
+
after_transition do: :log
|
|
75
|
+
around_transition on: :switch, do: :time
|
|
76
|
+
event(:switch) { transition off: :on }
|
|
77
|
+
end
|
|
78
|
+
end
|
|
79
|
+
RUBY
|
|
80
|
+
|
|
81
|
+
assert_equal(['off -> on / around hold, before check, around time, after log'],
|
|
82
|
+
StateMachines::Yard::Description.events(machine).first[:transitions])
|
|
83
|
+
end
|
|
84
|
+
|
|
85
|
+
LAMP = <<~RUBY
|
|
86
|
+
class Lamp
|
|
87
|
+
state_machine initial: :off do
|
|
88
|
+
before_transition do: :check
|
|
89
|
+
around_transition do: :hold
|
|
90
|
+
before_transition on: :switch, do: :warm, if: :cold?
|
|
91
|
+
after_transition do: :log
|
|
92
|
+
state :dim
|
|
93
|
+
event :switch do
|
|
94
|
+
transition off: :lit, if: :bulb?, before: :prime, around: :fade, after: [:glow, -> { hum }]
|
|
95
|
+
transition off: :dim, after: :flicker
|
|
96
|
+
transition lit: same, around: :pulse
|
|
97
|
+
end
|
|
98
|
+
state :lit do
|
|
99
|
+
transition to: :off, on: :cut, around: :fade, before: :cool
|
|
100
|
+
end
|
|
101
|
+
end
|
|
102
|
+
end
|
|
103
|
+
RUBY
|
|
104
|
+
|
|
105
|
+
def test_a_transitions_own_callbacks_read_where_the_core_runs_them
|
|
106
|
+
switch, cut = StateMachines::Yard::Description.events(parse_machines(LAMP)['Lamp'][:state])
|
|
107
|
+
|
|
108
|
+
assert_equal(['off -> lit [if bulb?] / before check, around hold, before warm (if cold?), before prime, ' \
|
|
109
|
+
'around fade, after glow, after lambda@(stdin):9, after log',
|
|
110
|
+
'off -> dim / before check, around hold, before warm (if cold?), after flicker, after log',
|
|
111
|
+
'lit -> lit / before check, around hold, before warm (if cold?), around pulse, after log'],
|
|
112
|
+
switch[:transitions])
|
|
113
|
+
# a state context transition, its around: written before its before:
|
|
114
|
+
assert_equal(['lit -> off / before check, around hold, around fade, before cool, after log'], cut[:transitions])
|
|
115
|
+
end
|
|
116
|
+
|
|
117
|
+
def test_the_mermaid_diagram_shows_a_transitions_own_callbacks
|
|
118
|
+
mermaid = StateMachines::Yard::Renderer.render_mermaid(parse_machines(LAMP)['Lamp'][:state])[:mermaid]
|
|
119
|
+
|
|
120
|
+
assert_includes(mermaid, 'lit --> off : cut / before check, around hold, around fade, before cool, after log')
|
|
121
|
+
end
|
|
122
|
+
|
|
123
|
+
def test_each_renderer_mode_documents_the_event_methods
|
|
124
|
+
DIAGRAMS.each_key do |renderer|
|
|
125
|
+
document(renderer)
|
|
126
|
+
ignite = YARD::Registry.at('Vehicle#ignite').docstring
|
|
127
|
+
ignite_bang = YARD::Registry.at('Vehicle#ignite!').docstring
|
|
128
|
+
|
|
129
|
+
[ignite, ignite_bang].each do |docstring|
|
|
130
|
+
IGNITE.each { assert_includes(docstring, "* #{it}", renderer) }
|
|
131
|
+
|
|
132
|
+
assert_includes(docstring, 'On failure: alert', renderer)
|
|
133
|
+
end
|
|
134
|
+
assert_includes(YARD::Registry.at('Vehicle#noop').docstring, 'No transitions: it never fires.', renderer)
|
|
135
|
+
assert_equal(['@param', '@return'], YARD::Registry.at('Vehicle#ignite').tags.map { "@#{it.tag_name}" })
|
|
136
|
+
end
|
|
137
|
+
end
|
|
138
|
+
end
|