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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 2b674c24b722f0643ed70d4c459d9d62200f4b821035280ed970e67509da382d
4
- data.tar.gz: e2157b72de56685420efcb67624dc25404fd162f6b685a3ba2e78f9896c924c4
3
+ metadata.gz: 90c9f031f3007e509582714835aa6c1b3607b50d44871ba5b73ccb85aad301b7
4
+ data.tar.gz: 2b7a97545ca16cac0e2f47b425024aa0d1a318acf091c600fd59897d9d75fa14
5
5
  SHA512:
6
- metadata.gz: f0fe6c896583ddd924e70ddc0b29f52b9dcb122909044ca978440edbc3e72ecce330c0896b08f4976835268824f8deb37a9ab1134c94cd2b06dd6db4558b8772
7
- data.tar.gz: 89461e5685c9892896d531e4b9f91dcc1a876da0604cd3a45ac291cfffe6106b8d238722026f385e7aff1437a0368aa3433f689a5b54c4eae52c57faf5dec9db
6
+ metadata.gz: 65193fd5562621438bf8235416eef4e2f23abfee6bb39d1f5c44132960dac60d2b4e0ba9285cb53042d8108423967fcf07106c33feafdadebf3d088a7847d736
7
+ data.tar.gz: bc1fe94bd090ff2f1425c79002a38bd64da4af0301cc607e8f76a6f6839436b68ae710c68052d6e3e45bed58742dbf23fe22f030514da606011ada52defe5075
@@ -1,3 +1,3 @@
1
1
  {
2
- ".": "0.3.0"
2
+ ".": "0.4.0"
3
3
  }
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
- and the `after_failure` callbacks:
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. Diagrams show them as the renderers label them:
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
- def callback_steps(machine, from, to, event_name)
43
- Introspection.callback_sequence(machine, from, to, event_name)
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
- node = Prism.parse(statement.source).value.statements.body.first
37
- raise Unreadable, "`#{statement.source}` is not a plain call" unless node.is_a?(Prism::CallNode)
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 << block_action(call_node.block) if call_node.block
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 [StateMachines::Machine, StateMachines::Event, StateMachines::State].include?(owner.class)
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
@@ -2,6 +2,6 @@
2
2
 
3
3
  module StateMachines
4
4
  module Yard
5
- VERSION = '0.3.0'
5
+ VERSION = '0.4.0'
6
6
  end
7
7
  end
@@ -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'
@@ -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.303.0'
22
- spec.add_dependency 'state_machines-diagram', '>= 0.3.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'
@@ -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)
@@ -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.3.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.303.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.303.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.3.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.3.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