state_machines-yard 0.3.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/.release-please-manifest.json +1 -1
- data/CHANGELOG.md +18 -0
- data/README.md +6 -3
- data/lib/state_machines/yard/description.rb +7 -4
- data/lib/state_machines/yard/handlers/actions.rb +113 -0
- data/lib/state_machines/yard/handlers/base.rb +28 -2
- data/lib/state_machines/yard/handlers/callback.rb +2 -42
- data/lib/state_machines/yard/handlers/transition.rb +40 -3
- data/lib/state_machines/yard/version.rb +1 -1
- data/lib/state_machines/yard.rb +1 -0
- data/state_machines-yard.gemspec +2 -2
- data/test/description_test.rb +39 -0
- data/test/handlers/base_test.rb +18 -0
- data/test/handlers/callback_test.rb +31 -0
- data/test/handlers/transition_test.rb +101 -0
- metadata +6 -5
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 90c9f031f3007e509582714835aa6c1b3607b50d44871ba5b73ccb85aad301b7
|
|
4
|
+
data.tar.gz: 2b7a97545ca16cac0e2f47b425024aa0d1a318acf091c600fd59897d9d75fa14
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 65193fd5562621438bf8235416eef4e2f23abfee6bb39d1f5c44132960dac60d2b4e0ba9285cb53042d8108423967fcf07106c33feafdadebf3d088a7847d736
|
|
7
|
+
data.tar.gz: bc1fe94bd090ff2f1425c79002a38bd64da4af0301cc607e8f76a6f6839436b68ae710c68052d6e3e45bed58742dbf23fe22f030514da606011ada52defe5075
|
data/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,23 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [0.4.0](https://github.com/state-machines/state_machines-yard/compare/v0.3.0...v0.4.0) (2026-11-17)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### Features
|
|
7
|
+
|
|
8
|
+
* list a transition's own callbacks where the core runs them ([f63e27b](https://github.com/state-machines/state_machines-yard/commit/f63e27b6fcae11bac31356971addb65453cc147a))
|
|
9
|
+
* require state_machines-diagram 0.4.0 for transition callbacks ([0d72dc4](https://github.com/state-machines/state_machines-yard/commit/0d72dc40ea5a7d46a02bc428e4360ca1f66877f0))
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
### Bug Fixes
|
|
13
|
+
|
|
14
|
+
* document no callback method for do: nil or &nil ([b1d4e32](https://github.com/state-machines/state_machines-yard/commit/b1d4e3228145172268eaeb0083e53ec9909053f0))
|
|
15
|
+
* document transitions declared in a state's block ([71951c6](https://github.com/state-machines/state_machines-yard/commit/71951c67654d6720818e05b00df55a78812fd582))
|
|
16
|
+
* leave out a callback whose block argument has no to_proc ([e1b5d12](https://github.com/state-machines/state_machines-yard/commit/e1b5d12c05c78546ab8f0892db0cb700f71128f0))
|
|
17
|
+
* read a call whole when YARD's parser cuts its last argument ([a8ee0ed](https://github.com/state-machines/state_machines-yard/commit/a8ee0edd69878e6406bdecb02da322b023f243ae))
|
|
18
|
+
* read a callback method through parentheses and refuse every non-method ([0d5f024](https://github.com/state-machines/state_machines-yard/commit/0d5f024f11c0db7cd7db24264b9453d5448213a6))
|
|
19
|
+
* read a transition's before:/around:/after: as the methods they are ([482a37f](https://github.com/state-machines/state_machines-yard/commit/482a37fe78677afbede4189c3736211fb2a1f7ab))
|
|
20
|
+
|
|
3
21
|
## [0.3.0](https://github.com/state-machines/state_machines-yard/compare/v0.2.0...v0.3.0) (2026-11-17)
|
|
4
22
|
|
|
5
23
|
|
data/README.md
CHANGED
|
@@ -21,8 +21,9 @@ Or install it yourself as:
|
|
|
21
21
|
Whatever the renderer, each class's documentation lists its machines' events, and
|
|
22
22
|
each event's method (`ignite`, `ignite!`) describes the transitions it performs: from
|
|
23
23
|
each state the first branch that matches, its guards and the callbacks that run on it in
|
|
24
|
-
the order the core runs them (an around where it enters
|
|
25
|
-
|
|
24
|
+
the order the core runs them (an around where it enters; a transition's own
|
|
25
|
+
`before:`/`around:`/`after:` closest to the state change, after the machine's befores and
|
|
26
|
+
before its afters), and the `after_failure` callbacks:
|
|
26
27
|
|
|
27
28
|
* parked -> idling [if engine_ok? && if_any_state (gate=open, alarm=off)] / before check_mirrors, after log_start (if logging?)
|
|
28
29
|
* parked -> stalled / before check_mirrors
|
|
@@ -53,7 +54,9 @@ written as code documents no state as initial.
|
|
|
53
54
|
Transition callbacks (`before_transition`, `after_transition`, `around_transition`,
|
|
54
55
|
`after_failure`) are read the same way: their methods (positional, `do:`, a block),
|
|
55
56
|
the transitions they run on (`from`/`to`/`on`, their `except_` forms, `a => b`
|
|
56
|
-
pairs) and their own conditions.
|
|
57
|
+
pairs) and their own conditions. A transition's own callbacks
|
|
58
|
+
(`transition parked: :idling, before: :prime, after: -> { log }`) are read as methods the
|
|
59
|
+
same way, in an event or a state's block. Diagrams show them as the renderers label them:
|
|
57
60
|
a Symbol by name, String code as written, a block or lambda as `lambda@file:line`,
|
|
58
61
|
a conditional callback with its conditions. A diagram a renderer fails to draw is
|
|
59
62
|
left out with a warning; the rest of the class's documentation stands.
|
|
@@ -30,7 +30,7 @@ module StateMachines
|
|
|
30
30
|
# "parked -> idling [if a && if_state gate=open] / before check, after log"
|
|
31
31
|
def transition(machine, event, from, to, branch)
|
|
32
32
|
guards = Labels.condition_phrases(Introspection.guard_conditions(branch))
|
|
33
|
-
callbacks = callback_steps(machine, from, to, event.name)
|
|
33
|
+
callbacks = callback_steps(machine, from, to, event.name, branch)
|
|
34
34
|
["#{Labels.state_text(from)} -> #{Labels.state_text(to)}",
|
|
35
35
|
("[#{guards.join(' && ')}]" if guards.any?),
|
|
36
36
|
("/ #{callbacks.join(', ')}" if callbacks.any?)].compact.join(' ')
|
|
@@ -38,9 +38,12 @@ module StateMachines
|
|
|
38
38
|
|
|
39
39
|
# The callbacks in the order the core runs them, each with its kind: an
|
|
40
40
|
# around where it enters (as Labels.action_list lists it), the afters
|
|
41
|
-
# after the state change: "around time, before check, after log"
|
|
42
|
-
|
|
43
|
-
|
|
41
|
+
# after the state change: "around time, before check, after log". The
|
|
42
|
+
# transition's own (transition ..., before:/around:/after:) run
|
|
43
|
+
# closest to the change: its befores and arounds after the machine's,
|
|
44
|
+
# its afters before them.
|
|
45
|
+
def callback_steps(machine, from, to, event_name, branch)
|
|
46
|
+
Introspection.callback_sequence(machine, from, to, event_name, branch: branch)
|
|
44
47
|
.reject { it[:phase] == :exit }
|
|
45
48
|
.map { "#{it[:kind]} #{Labels.callback_text(it)}" }
|
|
46
49
|
end
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module StateMachines
|
|
4
|
+
module Yard
|
|
5
|
+
module Handlers
|
|
6
|
+
# Reads the methods a callback runs as the core reads them, for
|
|
7
|
+
# handlers built on Base: a transition callback's (do:, positional, a
|
|
8
|
+
# block) and a transition's own (before:, around:, after:)
|
|
9
|
+
module Actions
|
|
10
|
+
# Literals without to_proc: & raises TypeError on them, so the
|
|
11
|
+
# declaration never runs. A Symbol and a Hash have one.
|
|
12
|
+
NO_TO_PROC = [
|
|
13
|
+
Prism::TrueNode, Prism::FalseNode, Prism::IntegerNode, Prism::FloatNode, Prism::RationalNode,
|
|
14
|
+
Prism::ImaginaryNode, Prism::StringNode, Prism::InterpolatedStringNode, Prism::XStringNode,
|
|
15
|
+
Prism::InterpolatedXStringNode, Prism::SourceFileNode, Prism::SourceLineNode, Prism::SourceEncodingNode,
|
|
16
|
+
Prism::ArrayNode, Prism::RangeNode, Prism::RegularExpressionNode, Prism::InterpolatedRegularExpressionNode
|
|
17
|
+
].freeze
|
|
18
|
+
|
|
19
|
+
private
|
|
20
|
+
|
|
21
|
+
# A do: option's methods: one, or an Array of them. The core reads
|
|
22
|
+
# it with Array(), so nil (do: nil) is no method.
|
|
23
|
+
def action_list(node)
|
|
24
|
+
return [] if nil_literal?(node)
|
|
25
|
+
|
|
26
|
+
node = unwrap(node)
|
|
27
|
+
node.is_a?(Prism::ArrayNode) ? node.elements.map { action(it) } : [action(node)]
|
|
28
|
+
end
|
|
29
|
+
|
|
30
|
+
# A method the callback runs, as the core reads it: a Symbol names a
|
|
31
|
+
# method, a String is code. A lambda or proc is shown as diagrams show
|
|
32
|
+
# a Proc, by where it is defined; any other code by its source.
|
|
33
|
+
def action(node)
|
|
34
|
+
node = unwrap(node)
|
|
35
|
+
case node
|
|
36
|
+
when Prism::SymbolNode, Prism::StringNode then literal(node)
|
|
37
|
+
else proc_literal?(node) ? lambda_label(node.location.start_line) : node.slice
|
|
38
|
+
end
|
|
39
|
+
end
|
|
40
|
+
|
|
41
|
+
# The expression a group gives: (x), ((x)) and begin x end are x. An
|
|
42
|
+
# empty group, or one of several expressions or with rescue / else /
|
|
43
|
+
# ensure, stays itself (see #nil_literal?).
|
|
44
|
+
def unwrap(node)
|
|
45
|
+
single = single_statement(group_body(node)) if group?(node)
|
|
46
|
+
single ? unwrap(single) : node
|
|
47
|
+
end
|
|
48
|
+
|
|
49
|
+
# nil, written as such or as an empty group: () or begin end
|
|
50
|
+
def nil_literal?(node)
|
|
51
|
+
node = unwrap(node)
|
|
52
|
+
node.is_a?(Prism::NilNode) || (group?(node) && group_body(node).nil?)
|
|
53
|
+
end
|
|
54
|
+
|
|
55
|
+
def group?(node)
|
|
56
|
+
node.is_a?(Prism::ParenthesesNode) ||
|
|
57
|
+
(node.is_a?(Prism::BeginNode) && !node.rescue_clause && !node.else_clause && !node.ensure_clause)
|
|
58
|
+
end
|
|
59
|
+
|
|
60
|
+
def group_body(node) = node.is_a?(Prism::BeginNode) ? node.statements : node.body
|
|
61
|
+
|
|
62
|
+
def single_statement(body)
|
|
63
|
+
return body unless body.is_a?(Prism::StatementsNode)
|
|
64
|
+
|
|
65
|
+
body.body.first if body.body.one?
|
|
66
|
+
end
|
|
67
|
+
|
|
68
|
+
# ->, lambda {}, proc {} or Proc.new {}
|
|
69
|
+
def proc_literal?(node)
|
|
70
|
+
return true if node.is_a?(Prism::LambdaNode)
|
|
71
|
+
return false unless node.is_a?(Prism::CallNode) && node.block
|
|
72
|
+
|
|
73
|
+
node.receiver.nil? ? %i[lambda proc].include?(node.name) : proc_new?(node)
|
|
74
|
+
end
|
|
75
|
+
|
|
76
|
+
def proc_new?(node)
|
|
77
|
+
node.name == :new && node.receiver.slice == 'Proc'
|
|
78
|
+
end
|
|
79
|
+
|
|
80
|
+
# The callback's own block, or a block argument: &:name as diagrams
|
|
81
|
+
# show a Symbol's proc, a Hash's proc as diagrams show a Proc without
|
|
82
|
+
# a source (lambda), anything else as an action. &nil passes no
|
|
83
|
+
# block, so it is no method; a literal without to_proc raises
|
|
84
|
+
# TypeError, so the declaration is refused as it never registers.
|
|
85
|
+
def block_actions(node)
|
|
86
|
+
return [lambda_label(node.location.start_line)] if node.is_a?(Prism::BlockNode)
|
|
87
|
+
|
|
88
|
+
expression = unwrap(node.expression)
|
|
89
|
+
return [] if nil_literal?(expression)
|
|
90
|
+
if NO_TO_PROC.any? { expression.is_a?(it) }
|
|
91
|
+
raise ArgumentError, "`#{node.slice}` is no block: Ruby raises TypeError, so the core never registers it"
|
|
92
|
+
end
|
|
93
|
+
|
|
94
|
+
[block_label(expression)]
|
|
95
|
+
end
|
|
96
|
+
|
|
97
|
+
def block_label(expression)
|
|
98
|
+
case expression
|
|
99
|
+
when Prism::SymbolNode then "&#{expression.slice}"
|
|
100
|
+
when Prism::HashNode then 'lambda'
|
|
101
|
+
else action(expression)
|
|
102
|
+
end
|
|
103
|
+
end
|
|
104
|
+
|
|
105
|
+
# "lambda@file:line", the label diagrams give a Proc; +line+ counts
|
|
106
|
+
# from the start of the statement
|
|
107
|
+
def lambda_label(line)
|
|
108
|
+
"lambda@#{File.basename(parser.file.to_s)}:#{statement.line + line - 1}"
|
|
109
|
+
end
|
|
110
|
+
end
|
|
111
|
+
end
|
|
112
|
+
end
|
|
113
|
+
end
|
|
@@ -33,13 +33,39 @@ module StateMachines
|
|
|
33
33
|
# The handled call as Prism reads it
|
|
34
34
|
def call_node
|
|
35
35
|
@call_node ||= begin
|
|
36
|
-
|
|
37
|
-
|
|
36
|
+
source = call_source
|
|
37
|
+
node = Prism.parse(source).value.statements.body.first
|
|
38
|
+
raise Unreadable, "`#{source}` is not a plain call" unless node.is_a?(Prism::CallNode)
|
|
38
39
|
|
|
39
40
|
node
|
|
40
41
|
end
|
|
41
42
|
end
|
|
42
43
|
|
|
44
|
+
# The handled call's source, as Prism reads it in the file. YARD's
|
|
45
|
+
# parser ends a statement before a trailing rational or imaginary
|
|
46
|
+
# literal (`after: 1r` reads `after:`, which Prism reads as a call to
|
|
47
|
+
# `after`) and past a trailing negative number (`-1 }`), so the call is
|
|
48
|
+
# the one Prism finds where the statement starts.
|
|
49
|
+
def call_source
|
|
50
|
+
FileSource.call_at(statement.full_source, statement.source_range.begin)&.slice || statement.source
|
|
51
|
+
end
|
|
52
|
+
|
|
53
|
+
# The calls of the file being documented, read once per file
|
|
54
|
+
module FileSource
|
|
55
|
+
@calls = nil
|
|
56
|
+
|
|
57
|
+
# The innermost call starting at character +offset+ of +source+
|
|
58
|
+
def self.call_at(source, offset)
|
|
59
|
+
@calls = [source, calls_by_offset(source)] unless @calls&.first.equal?(source)
|
|
60
|
+
@calls.last[offset]
|
|
61
|
+
end
|
|
62
|
+
|
|
63
|
+
def self.calls_by_offset(source)
|
|
64
|
+
calls = Prism.parse(source).value.breadth_first_search_all { it.is_a?(Prism::CallNode) }
|
|
65
|
+
calls.group_by { it.location.start_character_offset }.transform_values { it.min_by { it.location.length } }
|
|
66
|
+
end
|
|
67
|
+
end
|
|
68
|
+
|
|
43
69
|
# The call's positional arguments, as nodes
|
|
44
70
|
def positional_arguments
|
|
45
71
|
arguments = call_node.arguments&.arguments || []
|
|
@@ -11,6 +11,7 @@ module StateMachines
|
|
|
11
11
|
# reads a transition's.
|
|
12
12
|
class Callback < Base
|
|
13
13
|
include Requirements
|
|
14
|
+
include Actions
|
|
14
15
|
|
|
15
16
|
# The DSL method of each callback kind
|
|
16
17
|
KINDS = %i[before_transition after_transition around_transition after_failure].freeze
|
|
@@ -46,50 +47,9 @@ module StateMachines
|
|
|
46
47
|
read[name] = option_value(name, value)
|
|
47
48
|
end
|
|
48
49
|
end
|
|
49
|
-
methods
|
|
50
|
+
methods.concat(block_actions(call_node.block)) if call_node.block
|
|
50
51
|
options.merge(do: methods)
|
|
51
52
|
end
|
|
52
|
-
|
|
53
|
-
def action_list(node)
|
|
54
|
-
node.is_a?(Prism::ArrayNode) ? node.elements.map { action(it) } : [action(node)]
|
|
55
|
-
end
|
|
56
|
-
|
|
57
|
-
# A method the callback runs, as the core reads it: a Symbol names a
|
|
58
|
-
# method, a String is code. A lambda or proc is shown as diagrams show
|
|
59
|
-
# a Proc, by where it is defined; any other code by its source.
|
|
60
|
-
def action(node)
|
|
61
|
-
case node
|
|
62
|
-
when Prism::SymbolNode, Prism::StringNode then literal(node)
|
|
63
|
-
else proc_literal?(node) ? lambda_label(node.location.start_line) : node.slice
|
|
64
|
-
end
|
|
65
|
-
end
|
|
66
|
-
|
|
67
|
-
# ->, lambda {}, proc {} or Proc.new {}
|
|
68
|
-
def proc_literal?(node)
|
|
69
|
-
return true if node.is_a?(Prism::LambdaNode)
|
|
70
|
-
return false unless node.is_a?(Prism::CallNode) && node.block
|
|
71
|
-
|
|
72
|
-
node.receiver.nil? ? %i[lambda proc].include?(node.name) : proc_new?(node)
|
|
73
|
-
end
|
|
74
|
-
|
|
75
|
-
def proc_new?(node)
|
|
76
|
-
node.name == :new && node.receiver.slice == 'Proc'
|
|
77
|
-
end
|
|
78
|
-
|
|
79
|
-
# The callback's own block, or a block argument: &:name as diagrams
|
|
80
|
-
# show a Symbol's proc, anything else as an action
|
|
81
|
-
def block_action(node)
|
|
82
|
-
return lambda_label(node.location.start_line) if node.is_a?(Prism::BlockNode)
|
|
83
|
-
|
|
84
|
-
expression = node.expression
|
|
85
|
-
expression.is_a?(Prism::SymbolNode) ? "&#{expression.slice}" : action(expression)
|
|
86
|
-
end
|
|
87
|
-
|
|
88
|
-
# "lambda@file:line", the label diagrams give a Proc; +line+ counts
|
|
89
|
-
# from the start of the statement
|
|
90
|
-
def lambda_label(line)
|
|
91
|
-
"lambda@#{File.basename(parser.file.to_s)}:#{statement.line + line - 1}"
|
|
92
|
-
end
|
|
93
53
|
end
|
|
94
54
|
end
|
|
95
55
|
end
|
|
@@ -6,7 +6,10 @@ module StateMachines
|
|
|
6
6
|
# Handles and processes #transition. The documented machine gets the
|
|
7
7
|
# transition with the guards the core runs: if:/unless: conditions
|
|
8
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
|
|
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.
|
|
10
13
|
class Transition < Base
|
|
11
14
|
handles method_call(:transition)
|
|
12
15
|
|
|
@@ -14,9 +17,23 @@ module StateMachines
|
|
|
14
17
|
@handles_method = :transition
|
|
15
18
|
|
|
16
19
|
include Requirements
|
|
20
|
+
include Actions
|
|
21
|
+
|
|
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
|
|
17
34
|
|
|
18
35
|
def process
|
|
19
|
-
return unless
|
|
36
|
+
return unless OWNERS.include?(owner.class)
|
|
20
37
|
|
|
21
38
|
owner.transition(requirements)
|
|
22
39
|
rescue Unreadable, ArgumentError => e
|
|
@@ -33,9 +50,29 @@ module StateMachines
|
|
|
33
50
|
|
|
34
51
|
pairs.to_h do |key, value|
|
|
35
52
|
name = requirement(key)
|
|
36
|
-
[name, option_value(name, value)]
|
|
53
|
+
[name, CALLBACKS.include?(name) ? own_callbacks(value) : option_value(name, value)]
|
|
37
54
|
end
|
|
38
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
|
|
39
76
|
end
|
|
40
77
|
end
|
|
41
78
|
end
|
data/lib/state_machines/yard.rb
CHANGED
|
@@ -13,6 +13,7 @@ require_relative 'yard/description'
|
|
|
13
13
|
require_relative 'yard/handlers'
|
|
14
14
|
require_relative 'yard/handlers/base'
|
|
15
15
|
require_relative 'yard/handlers/requirements'
|
|
16
|
+
require_relative 'yard/handlers/actions'
|
|
16
17
|
require_relative 'yard/handlers/callback'
|
|
17
18
|
require_relative 'yard/handlers/event'
|
|
18
19
|
require_relative 'yard/handlers/machine'
|
data/state_machines-yard.gemspec
CHANGED
|
@@ -18,8 +18,8 @@ Gem::Specification.new do |spec|
|
|
|
18
18
|
spec.require_paths = ['lib']
|
|
19
19
|
|
|
20
20
|
spec.add_dependency 'rdoc'
|
|
21
|
-
spec.add_dependency 'state_machines', '>= 0.
|
|
22
|
-
spec.add_dependency 'state_machines-diagram', '>= 0.
|
|
21
|
+
spec.add_dependency 'state_machines', '>= 0.304.0'
|
|
22
|
+
spec.add_dependency 'state_machines-diagram', '>= 0.4.0'
|
|
23
23
|
spec.add_dependency 'yard'
|
|
24
24
|
spec.add_development_dependency 'bundler', '>= 4.0'
|
|
25
25
|
spec.add_development_dependency 'minitest', '~> 6.0'
|
data/test/description_test.rb
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
3
|
require 'test_helper'
|
|
4
|
+
require 'state_machines/yard/renderer'
|
|
4
5
|
|
|
5
6
|
# The generated documentation lists each event's transitions, guards and
|
|
6
7
|
# callbacks as text whichever renderer draws the diagram, or none
|
|
@@ -81,6 +82,44 @@ class DescriptionTest < Minitest::Test
|
|
|
81
82
|
StateMachines::Yard::Description.events(machine).first[:transitions])
|
|
82
83
|
end
|
|
83
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
|
+
|
|
84
123
|
def test_each_renderer_mode_documents_the_event_methods
|
|
85
124
|
DIAGRAMS.each_key do |renderer|
|
|
86
125
|
document(renderer)
|
data/test/handlers/base_test.rb
CHANGED
|
@@ -80,4 +80,22 @@ class BaseHandlerTest < Minitest::Test
|
|
|
80
80
|
refute_nil method, "#{state}? method should be registered"
|
|
81
81
|
end
|
|
82
82
|
end
|
|
83
|
+
|
|
84
|
+
# YARD's parser ends a statement before a trailing rational or imaginary
|
|
85
|
+
# literal and past a trailing negative number; each call is read whole
|
|
86
|
+
def test_a_call_ending_in_any_number_is_read_whole
|
|
87
|
+
machine = parse_machines(<<~RUBY)['Vehicle'][:status]
|
|
88
|
+
class Vehicle # é
|
|
89
|
+
state_machine :status, initial: :parked do
|
|
90
|
+
state :parked, value: 1r
|
|
91
|
+
state :idling, value: 2i
|
|
92
|
+
state :stalled, value: -1
|
|
93
|
+
event(:ignite) { transition parked: :idling, if: 3r }
|
|
94
|
+
end
|
|
95
|
+
end
|
|
96
|
+
RUBY
|
|
97
|
+
|
|
98
|
+
assert_equal(%w[1r 2i -1], machine.states.map { it.value(false).inspect })
|
|
99
|
+
assert_equal(:'3r', machine.events[:ignite].branches.first.if_condition)
|
|
100
|
+
end
|
|
83
101
|
end
|
|
@@ -94,10 +94,41 @@ class CallbackHandlerTest < Minitest::Test
|
|
|
94
94
|
'lambda@(stdin):3'], callback[:methods])
|
|
95
95
|
end
|
|
96
96
|
|
|
97
|
+
def test_a_method_in_parentheses_is_that_method
|
|
98
|
+
callback = callbacks('before_transition on: :park, do: [(:lock), ((-> { beep })), begin :wait end]').first
|
|
99
|
+
|
|
100
|
+
assert_equal([:lock, 'lambda@(stdin):3', :wait], callback[:methods])
|
|
101
|
+
end
|
|
102
|
+
|
|
97
103
|
def test_a_block_argument_is_a_method
|
|
98
104
|
assert_equal([:lock, '&:beep'], callbacks('before_transition on: :park, do: :lock, &:beep').first[:methods])
|
|
99
105
|
end
|
|
100
106
|
|
|
107
|
+
# The core reads do: with Array(), so do: nil adds no method, and &nil
|
|
108
|
+
# passes no block; a callback left with no method is refused
|
|
109
|
+
def test_nil_adds_no_method
|
|
110
|
+
found = callbacks(<<~RUBY)
|
|
111
|
+
before_transition on: :park, do: :check, &nil
|
|
112
|
+
before_transition :lock, on: :park, do: (nil), &(nil)
|
|
113
|
+
after_transition on: :park, &nil
|
|
114
|
+
after_transition on: :park, do: nil
|
|
115
|
+
after_transition on: :park, do: ()
|
|
116
|
+
RUBY
|
|
117
|
+
|
|
118
|
+
assert_equal([[:check], [:lock]], found.map { it[:methods] })
|
|
119
|
+
end
|
|
120
|
+
|
|
121
|
+
# & calls to_proc: a literal without one raises TypeError, so the core
|
|
122
|
+
# never registers the declaration; a Symbol's and a Hash's are Procs
|
|
123
|
+
def test_a_block_argument_without_to_proc_leaves_the_declaration_out
|
|
124
|
+
values = ['false', 'true', '1', '1.5', '1r', '2i', '"bad"', "\"a\#{b}\"", '`ls`', '__FILE__', '__LINE__',
|
|
125
|
+
'__ENCODING__', '[]', '%i[a]', '1..2', '/x/', '(false)', 'begin 1 end', '((true))']
|
|
126
|
+
body = values.map { "before_transition on: :park, do: :check, &#{it}" }
|
|
127
|
+
body.push('before_transition on: :park, do: :kept, &:beep', 'before_transition on: :park, do: :kept, &({ a: 1 })')
|
|
128
|
+
|
|
129
|
+
assert_equal([[:kept, '&:beep'], [:kept, 'lambda']], callbacks(body.join("\n")).map { it[:methods] })
|
|
130
|
+
end
|
|
131
|
+
|
|
101
132
|
def test_options_on_how_a_callback_runs_are_not_requirements
|
|
102
133
|
callback = callbacks('before_transition on: :park, do: :lock, bind_to_object: true, terminator: nil').first
|
|
103
134
|
|
|
@@ -139,4 +139,105 @@ class TransitionHandlerTest < Minitest::Test
|
|
|
139
139
|
|
|
140
140
|
refute_nil maintain_method, 'maintain method should be registered'
|
|
141
141
|
end
|
|
142
|
+
|
|
143
|
+
# Every literal the core refuses as a transition's callback, bare, in an
|
|
144
|
+
# Array or inside parentheses or begin/end, leaves the transition out
|
|
145
|
+
def test_literals_that_are_no_method_leave_the_transition_out_however_written
|
|
146
|
+
values = ['(nil)', '(1)', '(false)', '(true)', '(1.5)', '({ log: true })', '/x/', "/x\#{y}/", '1r', '2i',
|
|
147
|
+
'-1', '1..2', '__LINE__', '__ENCODING__', '()', 'begin end', 'begin; nil; end', '((nil))',
|
|
148
|
+
'[[:a]]', '[(nil), :x]']
|
|
149
|
+
body = values.map.with_index { |value, index| "event(:e#{index}) { transition parked: :idling, after: #{value} }" }
|
|
150
|
+
body << 'event(:kept) { transition parked: :idling, after: :kept }'
|
|
151
|
+
|
|
152
|
+
assert_equal([[[:after, [:kept]]]], own_callbacks(body.join("\n")))
|
|
153
|
+
end
|
|
154
|
+
|
|
155
|
+
def test_a_group_of_one_expression_is_that_expression
|
|
156
|
+
found = own_callbacks(<<~RUBY)
|
|
157
|
+
event :ignite do
|
|
158
|
+
transition parked: :idling, after: ((:log))
|
|
159
|
+
transition parked: :stalled, before: (-> { tow })
|
|
160
|
+
transition parked: :broken, around: (%i[a b]), after: [(:c), begin :d end]
|
|
161
|
+
transition idling: :parked, after: (:a; :b)
|
|
162
|
+
end
|
|
163
|
+
RUBY
|
|
164
|
+
|
|
165
|
+
assert_equal([[[:after, [:log]]], [[:before, ['lambda@(stdin):6']]],
|
|
166
|
+
[[:around, %i[a b]], [:after, %i[c d]]], [[:after, ['(:a; :b)']]]], found)
|
|
167
|
+
end
|
|
168
|
+
|
|
169
|
+
def test_a_transition_in_a_state_block_is_documented
|
|
170
|
+
code = <<~RUBY
|
|
171
|
+
class Vehicle
|
|
172
|
+
state_machine :status, initial: :parked do
|
|
173
|
+
state :idling do
|
|
174
|
+
transition to: :parked, on: :park, if: :stopped?
|
|
175
|
+
end
|
|
176
|
+
end
|
|
177
|
+
end
|
|
178
|
+
RUBY
|
|
179
|
+
|
|
180
|
+
branch = parse_machines(code)['Vehicle'][:status].events[:park].branches.first
|
|
181
|
+
requirement = branch.state_requirements.first
|
|
182
|
+
|
|
183
|
+
assert_equal([[:idling], [:parked], :stopped?],
|
|
184
|
+
[requirement[:from].values, requirement[:to].values, branch.if_condition])
|
|
185
|
+
end
|
|
186
|
+
|
|
187
|
+
# A transition's own callbacks, by branch, as [type, methods]
|
|
188
|
+
def own_callbacks(body)
|
|
189
|
+
code = <<~RUBY
|
|
190
|
+
class Vehicle
|
|
191
|
+
state_machine :status, initial: :parked do
|
|
192
|
+
state :stalled, :broken
|
|
193
|
+
#{body.gsub(/^/, ' ')}
|
|
194
|
+
end
|
|
195
|
+
end
|
|
196
|
+
RUBY
|
|
197
|
+
machine = parse_machines(code)['Vehicle'][:status]
|
|
198
|
+
machine.events.flat_map(&:branches).map { |branch| branch.callbacks.map { [it.type, it.callables] } }
|
|
199
|
+
end
|
|
200
|
+
|
|
201
|
+
def test_a_transitions_own_callbacks_are_its_methods
|
|
202
|
+
found = own_callbacks(<<~RUBY)
|
|
203
|
+
event :ignite do
|
|
204
|
+
transition parked: :idling, before: :prime, around: [:crank, 'time_it'], after: %i[log_start warm_up]
|
|
205
|
+
end
|
|
206
|
+
state :idling do
|
|
207
|
+
transition to: :parked, on: :park, after: :set_brake
|
|
208
|
+
end
|
|
209
|
+
RUBY
|
|
210
|
+
|
|
211
|
+
assert_equal([[[:before, [:prime]], [:around, [:crank, 'time_it']], [:after, %i[log_start warm_up]]],
|
|
212
|
+
[[:after, [:set_brake]]]], found)
|
|
213
|
+
end
|
|
214
|
+
|
|
215
|
+
def test_own_callbacks_written_as_code_are_methods_not_states
|
|
216
|
+
found = own_callbacks(<<~RUBY)
|
|
217
|
+
event :ignite do
|
|
218
|
+
transition parked: :idling, after: -> { tow }
|
|
219
|
+
transition parked: :stalled, before: [:prime, lambda { crank }], around: notifier
|
|
220
|
+
transition parked: :broken, after: method(:report)
|
|
221
|
+
end
|
|
222
|
+
RUBY
|
|
223
|
+
|
|
224
|
+
assert_equal([[[:after, ['lambda@(stdin):5']]],
|
|
225
|
+
[[:before, [:prime, 'lambda@(stdin):6']], [:around, ['notifier']]],
|
|
226
|
+
[[:after, ['method(:report)']]]], found)
|
|
227
|
+
end
|
|
228
|
+
|
|
229
|
+
def test_own_callbacks_the_core_refuses_leave_the_transition_out
|
|
230
|
+
found = own_callbacks(<<~RUBY)
|
|
231
|
+
event :ignite do
|
|
232
|
+
transition parked: :idling, after: nil
|
|
233
|
+
transition parked: :idling, before: [:prime, 1]
|
|
234
|
+
transition parked: :idling, around: []
|
|
235
|
+
transition parked: :idling, after: { log: true }
|
|
236
|
+
transition parked: :idling, do: :log
|
|
237
|
+
transition parked: :stalled, after: :kept
|
|
238
|
+
end
|
|
239
|
+
RUBY
|
|
240
|
+
|
|
241
|
+
assert_equal([[[:after, [:kept]]]], found)
|
|
242
|
+
end
|
|
142
243
|
end
|
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: state_machines-yard
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.
|
|
4
|
+
version: 0.4.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Abdelkader Boudih
|
|
@@ -30,28 +30,28 @@ dependencies:
|
|
|
30
30
|
requirements:
|
|
31
31
|
- - ">="
|
|
32
32
|
- !ruby/object:Gem::Version
|
|
33
|
-
version: 0.
|
|
33
|
+
version: 0.304.0
|
|
34
34
|
type: :runtime
|
|
35
35
|
prerelease: false
|
|
36
36
|
version_requirements: !ruby/object:Gem::Requirement
|
|
37
37
|
requirements:
|
|
38
38
|
- - ">="
|
|
39
39
|
- !ruby/object:Gem::Version
|
|
40
|
-
version: 0.
|
|
40
|
+
version: 0.304.0
|
|
41
41
|
- !ruby/object:Gem::Dependency
|
|
42
42
|
name: state_machines-diagram
|
|
43
43
|
requirement: !ruby/object:Gem::Requirement
|
|
44
44
|
requirements:
|
|
45
45
|
- - ">="
|
|
46
46
|
- !ruby/object:Gem::Version
|
|
47
|
-
version: 0.
|
|
47
|
+
version: 0.4.0
|
|
48
48
|
type: :runtime
|
|
49
49
|
prerelease: false
|
|
50
50
|
version_requirements: !ruby/object:Gem::Requirement
|
|
51
51
|
requirements:
|
|
52
52
|
- - ">="
|
|
53
53
|
- !ruby/object:Gem::Version
|
|
54
|
-
version: 0.
|
|
54
|
+
version: 0.4.0
|
|
55
55
|
- !ruby/object:Gem::Dependency
|
|
56
56
|
name: yard
|
|
57
57
|
requirement: !ruby/object:Gem::Requirement
|
|
@@ -198,6 +198,7 @@ files:
|
|
|
198
198
|
- lib/state_machines/yard.rb
|
|
199
199
|
- lib/state_machines/yard/description.rb
|
|
200
200
|
- lib/state_machines/yard/handlers.rb
|
|
201
|
+
- lib/state_machines/yard/handlers/actions.rb
|
|
201
202
|
- lib/state_machines/yard/handlers/base.rb
|
|
202
203
|
- lib/state_machines/yard/handlers/callback.rb
|
|
203
204
|
- lib/state_machines/yard/handlers/event.rb
|