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
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/.github/workflows/ci.yml
CHANGED
|
@@ -10,15 +10,23 @@ jobs:
|
|
|
10
10
|
build:
|
|
11
11
|
|
|
12
12
|
runs-on: ubuntu-latest
|
|
13
|
+
strategy:
|
|
14
|
+
fail-fast: false
|
|
15
|
+
matrix:
|
|
16
|
+
ruby-version: ['4.0']
|
|
17
|
+
renderer: ['none', 'graphviz', 'mermaid']
|
|
13
18
|
|
|
14
19
|
steps:
|
|
15
|
-
- uses: actions/checkout@
|
|
20
|
+
- uses: actions/checkout@v7
|
|
16
21
|
- name: Set up Ruby
|
|
17
22
|
uses: ruby/setup-ruby@v1
|
|
18
23
|
with:
|
|
19
|
-
ruby-version:
|
|
24
|
+
ruby-version: ${{ matrix.ruby-version }}
|
|
20
25
|
bundler-cache: true
|
|
21
|
-
|
|
26
|
+
# Every job draws a GraphViz diagram in the renderer tests
|
|
27
|
+
- name: Install graphviz
|
|
22
28
|
run: sudo apt-get update && sudo apt-get install -y graphviz
|
|
23
29
|
- name: Run tests
|
|
24
|
-
|
|
30
|
+
env:
|
|
31
|
+
STATE_MACHINES_RENDERER: ${{ matrix.renderer }}
|
|
32
|
+
run: bundle exec rake
|
|
@@ -1,16 +1,18 @@
|
|
|
1
|
-
name:
|
|
1
|
+
name: release-please
|
|
2
2
|
|
|
3
3
|
on:
|
|
4
4
|
push:
|
|
5
5
|
branches:
|
|
6
6
|
- master
|
|
7
|
+
workflow_dispatch:
|
|
8
|
+
|
|
9
|
+
permissions:
|
|
10
|
+
contents: write
|
|
11
|
+
pull-requests: write
|
|
12
|
+
issues: write
|
|
7
13
|
|
|
8
14
|
jobs:
|
|
9
15
|
release-please:
|
|
10
16
|
runs-on: ubuntu-latest
|
|
11
17
|
steps:
|
|
12
|
-
- uses:
|
|
13
|
-
- uses: googleapis/release-please-action@v3
|
|
14
|
-
with:
|
|
15
|
-
release-type: ruby
|
|
16
|
-
package-name: state_machines-yard
|
|
18
|
+
- uses: googleapis/release-please-action@v5
|
data/.rubocop.yml
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
plugins:
|
|
2
|
+
- rubocop-minitest
|
|
3
|
+
- rubocop-rake
|
|
4
|
+
- rubocop-performance
|
|
5
|
+
AllCops:
|
|
6
|
+
TargetRubyVersion: 4.0
|
|
7
|
+
NewCops: enable
|
|
8
|
+
Exclude:
|
|
9
|
+
- 'pkg/**/*'
|
|
10
|
+
- 'tmp/**/*'
|
|
11
|
+
- 'vendor/**/*'
|
|
12
|
+
|
|
13
|
+
Style/Documentation:
|
|
14
|
+
Enabled: false
|
|
15
|
+
|
|
16
|
+
Metrics/MethodLength:
|
|
17
|
+
Max: 20
|
|
18
|
+
Exclude:
|
|
19
|
+
- 'test/**/*' # Tests hold their fixture source
|
|
20
|
+
|
|
21
|
+
Metrics/AbcSize:
|
|
22
|
+
Max: 40
|
|
23
|
+
|
|
24
|
+
Minitest/MultipleAssertions:
|
|
25
|
+
Enabled: false
|
|
26
|
+
|
|
27
|
+
Gemspec/DevelopmentDependencies:
|
|
28
|
+
Enabled: false
|
|
29
|
+
|
|
30
|
+
Metrics/ClassLength:
|
|
31
|
+
Exclude:
|
|
32
|
+
- 'test/**/*' # Allow longer test classes
|
|
33
|
+
- 'lib/state_machines/yard/handlers/machine.rb' # The generated methods' documentation
|
|
34
|
+
|
|
35
|
+
# Test classes are long blocks by nature.
|
|
36
|
+
Metrics/BlockLength:
|
|
37
|
+
Exclude:
|
|
38
|
+
- 'test/**/*'
|
data/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,59 @@
|
|
|
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
|
+
|
|
21
|
+
## [0.3.0](https://github.com/state-machines/state_machines-yard/compare/v0.2.0...v0.3.0) (2026-11-17)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
### Features
|
|
25
|
+
|
|
26
|
+
* document each event's transitions, guards and callbacks as text ([d79a9a1](https://github.com/state-machines/state_machines-yard/commit/d79a9a117b380183301659221bcc8664c451c021))
|
|
27
|
+
* document the guards and options the DSL declares ([75c2603](https://github.com/state-machines/state_machines-yard/commit/75c26039e59d00b61cfa12bf7524acdabfab3481))
|
|
28
|
+
* document transition callbacks ([3bb2645](https://github.com/state-machines/state_machines-yard/commit/3bb264539d585a49fadeaab663ba18b62bb06a04))
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
### Bug Fixes
|
|
32
|
+
|
|
33
|
+
* a code condition is never evaluated as a String condition ([47d25d6](https://github.com/state-machines/state_machines-yard/commit/47d25d688bdf80a6a61409a2d7eb1af84aa2d828))
|
|
34
|
+
* a documented machine is owned by a class named as the documented one ([82e8e5c](https://github.com/state-machines/state_machines-yard/commit/82e8e5ca9a6695adaf33a0dbb34e1e49b0ec881a))
|
|
35
|
+
* a reopened machine never publishes its earlier diagram ([1edc9b8](https://github.com/state-machines/state_machines-yard/commit/1edc9b87980d1202c72671deeb7c4494761bc557))
|
|
36
|
+
* code-valued state options and numeric names are documented as written ([d7a2c4b](https://github.com/state-machines/state_machines-yard/commit/d7a2c4b976b3cf5fd46258e9602660402e1a25f2))
|
|
37
|
+
* key documented machines by their fully qualified namespace ([5bf46b0](https://github.com/state-machines/state_machines-yard/commit/5bf46b095a91e9293cbdec8ae269bf8e16096aba))
|
|
38
|
+
* read callbacks through Callback#callables; require state_machines 0.303.0 ([8bd5e0d](https://github.com/state-machines/state_machines-yard/commit/8bd5e0db24a92e056fd53bf915c2d41dbb12f158))
|
|
39
|
+
* release-please bumps the gem version ([1115494](https://github.com/state-machines/state_machines-yard/commit/1115494011bf37913c7d5ff123a70b6e4f657dc6))
|
|
40
|
+
* reopened and inherited machines are documented as the core builds them ([84ac0ee](https://github.com/state-machines/state_machines-yard/commit/84ac0ee8d60e21cea536121af353a0b84a05ab2a))
|
|
41
|
+
* run RuboCop in the default task ([f5827cf](https://github.com/state-machines/state_machines-yard/commit/f5827cfb471d8ff14848fc562c3b94780226bf06))
|
|
42
|
+
* the Events text lists callbacks in the order the core runs them ([e568c5f](https://github.com/state-machines/state_machines-yard/commit/e568c5f9a0c665eba8b86d72fdaff423bc0a0496))
|
|
43
|
+
|
|
44
|
+
## [0.2.0](https://github.com/state-machines/state_machines-yard/compare/v0.1.0...v0.2.0) (2026-10-18)
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
### Features
|
|
48
|
+
|
|
49
|
+
* configurable renderer for yard diagrams ([3268679](https://github.com/state-machines/state_machines-yard/commit/326867993c1982bfc9fe2ccf406d6f3669f4608e))
|
|
50
|
+
* run tests with padded_cell on CRuby ([#13](https://github.com/state-machines/state_machines-yard/issues/13)) ([1b9201c](https://github.com/state-machines/state_machines-yard/commit/1b9201c114a1f8d28988430069527f1f7d1236dd))
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
### Bug Fixes
|
|
54
|
+
|
|
55
|
+
* require state_machines-mermaid ([eea3f26](https://github.com/state-machines/state_machines-yard/commit/eea3f26d8a53689ad184cfc4fe201fa6406c9c05))
|
|
56
|
+
|
|
3
57
|
## 0.1.0 (2025-03-18)
|
|
4
58
|
|
|
5
59
|
|
data/Gemfile
CHANGED
|
@@ -1,4 +1,15 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
1
3
|
source 'https://rubygems.org'
|
|
2
4
|
gemspec
|
|
3
5
|
|
|
4
|
-
|
|
6
|
+
platforms :mri do
|
|
7
|
+
gem 'padded_cell', '~> 0.2'
|
|
8
|
+
end
|
|
9
|
+
|
|
10
|
+
gem 'ruby-graphviz'
|
|
11
|
+
|
|
12
|
+
group :test do
|
|
13
|
+
gem 'state_machines-graphviz', '>= 0.2.0'
|
|
14
|
+
gem 'state_machines-mermaid', '>= 0.3.0'
|
|
15
|
+
end
|
data/README.md
CHANGED
|
@@ -16,6 +16,51 @@ Or install it yourself as:
|
|
|
16
16
|
|
|
17
17
|
$ gem install state_machines-yard
|
|
18
18
|
|
|
19
|
+
## Events
|
|
20
|
+
|
|
21
|
+
Whatever the renderer, each class's documentation lists its machines' events, and
|
|
22
|
+
each event's method (`ignite`, `ignite!`) describes the transitions it performs: from
|
|
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; 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:
|
|
27
|
+
|
|
28
|
+
* parked -> idling [if engine_ok? && if_any_state (gate=open, alarm=off)] / before check_mirrors, after log_start (if logging?)
|
|
29
|
+
* parked -> stalled / before check_mirrors
|
|
30
|
+
|
|
31
|
+
On failure: alert
|
|
32
|
+
|
|
33
|
+
The text is read through [state_machines-diagram](https://github.com/state-machines/state_machines-diagram),
|
|
34
|
+
so it labels guards and callbacks exactly as the diagrams do.
|
|
35
|
+
|
|
36
|
+
## Diagrams
|
|
37
|
+
|
|
38
|
+
Diagrams are an optional extra. Set `STATE_MACHINES_RENDERER` to draw each documented machine:
|
|
39
|
+
|
|
40
|
+
* `graphviz` embeds a PNG drawn by [state_machines-graphviz](https://github.com/state-machines/state_machines-graphviz)
|
|
41
|
+
(needs the `dot` binary)
|
|
42
|
+
* `mermaid` embeds a Mermaid diagram drawn by [state_machines-mermaid](https://github.com/state-machines/state_machines-mermaid)
|
|
43
|
+
* `none` (the default) draws nothing
|
|
44
|
+
|
|
45
|
+
The plugin reads the state machine DSL without running it. Transitions carry the
|
|
46
|
+
guards the core runs: `if:`/`unless:` conditions (each one of an Array, a String
|
|
47
|
+
as the code it is, a lambda or other code by its source) and state guards
|
|
48
|
+
(`if_state`, `if_all_states`, `if_any_state`, `unless_state`, `unless_all_states`,
|
|
49
|
+
`unless_any_state`), each group with its requirements. A requirement or state guard
|
|
50
|
+
only known when the code runs (a constant, a method call) cannot be documented
|
|
51
|
+
faithfully, so that transition is left out with a warning; an initial state
|
|
52
|
+
written as code documents no state as initial.
|
|
53
|
+
|
|
54
|
+
Transition callbacks (`before_transition`, `after_transition`, `around_transition`,
|
|
55
|
+
`after_failure`) are read the same way: their methods (positional, `do:`, a block),
|
|
56
|
+
the transitions they run on (`from`/`to`/`on`, their `except_` forms, `a => b`
|
|
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:
|
|
60
|
+
a Symbol by name, String code as written, a block or lambda as `lambda@file:line`,
|
|
61
|
+
a conditional callback with its conditions. A diagram a renderer fails to draw is
|
|
62
|
+
left out with a warning; the rest of the class's documentation stands.
|
|
63
|
+
|
|
19
64
|
## Testing
|
|
20
65
|
|
|
21
66
|
A comprehensive test suite is included for the gem. To run all tests:
|
data/Rakefile
CHANGED
|
@@ -1,12 +1,30 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
1
3
|
require 'bundler/gem_tasks'
|
|
2
4
|
require 'rake/testtask'
|
|
5
|
+
require 'shellwords'
|
|
3
6
|
|
|
4
|
-
Rake::TestTask.new do |t|
|
|
7
|
+
Rake::TestTask.new(:minitest) do |t|
|
|
5
8
|
t.libs << 'test'
|
|
6
9
|
t.pattern = 'test/**/*_test.rb'
|
|
7
10
|
t.verbose = true
|
|
8
11
|
t.warning = false
|
|
9
12
|
end
|
|
10
13
|
|
|
11
|
-
|
|
12
|
-
|
|
14
|
+
# Both branches define :test, once per engine.
|
|
15
|
+
# rubocop:disable Rake/DuplicateTask
|
|
16
|
+
desc 'Run the test suite (padded_cell on CRuby, plain Minitest elsewhere)'
|
|
17
|
+
if RUBY_ENGINE == 'ruby'
|
|
18
|
+
task :test do
|
|
19
|
+
sh 'padded_cell', *Shellwords.split(ENV.fetch('TESTOPTS', ''))
|
|
20
|
+
end
|
|
21
|
+
else
|
|
22
|
+
task test: :minitest
|
|
23
|
+
end
|
|
24
|
+
# rubocop:enable Rake/DuplicateTask
|
|
25
|
+
|
|
26
|
+
require 'rubocop/rake_task'
|
|
27
|
+
|
|
28
|
+
RuboCop::RakeTask.new
|
|
29
|
+
|
|
30
|
+
task default: %i[test rubocop]
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'state_machines/diagram/introspection'
|
|
4
|
+
|
|
5
|
+
module StateMachines
|
|
6
|
+
module Yard
|
|
7
|
+
# A machine's events as text: the transitions each performs, as the core
|
|
8
|
+
# resolves them (from one source the first matching branch), with their
|
|
9
|
+
# guards and callbacks, labelled as the diagram renderers label them. The
|
|
10
|
+
# documentation carries this whatever renderer draws, or none.
|
|
11
|
+
module Description
|
|
12
|
+
Introspection = StateMachines::Diagram::Introspection
|
|
13
|
+
Labels = StateMachines::Diagram::Labels
|
|
14
|
+
|
|
15
|
+
module_function
|
|
16
|
+
|
|
17
|
+
# Each event as { name:, transitions: [line], failure: [callback] }, or
|
|
18
|
+
# { name:, error: } when the core refuses one of its conditions (a
|
|
19
|
+
# String it will not evaluate): it raises the same when it fires
|
|
20
|
+
def events(machine)
|
|
21
|
+
machine.events.map do |event|
|
|
22
|
+
{ name: event.name.to_s,
|
|
23
|
+
transitions: Introspection.event_transitions(machine, event).map { transition(machine, event, *it) },
|
|
24
|
+
failure: failure_callbacks(machine, event) }
|
|
25
|
+
rescue SecurityError, ArgumentError => e
|
|
26
|
+
{ name: event.name.to_s, error: e.message, transitions: [], failure: [] }
|
|
27
|
+
end
|
|
28
|
+
end
|
|
29
|
+
|
|
30
|
+
# "parked -> idling [if a && if_state gate=open] / before check, after log"
|
|
31
|
+
def transition(machine, event, from, to, branch)
|
|
32
|
+
guards = Labels.condition_phrases(Introspection.guard_conditions(branch))
|
|
33
|
+
callbacks = callback_steps(machine, from, to, event.name, branch)
|
|
34
|
+
["#{Labels.state_text(from)} -> #{Labels.state_text(to)}",
|
|
35
|
+
("[#{guards.join(' && ')}]" if guards.any?),
|
|
36
|
+
("/ #{callbacks.join(', ')}" if callbacks.any?)].compact.join(' ')
|
|
37
|
+
end
|
|
38
|
+
|
|
39
|
+
# The callbacks in the order the core runs them, each with its kind: an
|
|
40
|
+
# around where it enters (as Labels.action_list lists it), the afters
|
|
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)
|
|
47
|
+
.reject { it[:phase] == :exit }
|
|
48
|
+
.map { "#{it[:kind]} #{Labels.callback_text(it)}" }
|
|
49
|
+
end
|
|
50
|
+
|
|
51
|
+
# The after_failure callbacks that run when the event fails
|
|
52
|
+
def failure_callbacks(machine, event)
|
|
53
|
+
machine.callbacks[:failure].select { it.branch.matches?(nil, on: event.name, guard: false) }
|
|
54
|
+
.flat_map do |callback|
|
|
55
|
+
conditions = Introspection.guard_conditions(callback.branch)
|
|
56
|
+
callback.callables.map do |method|
|
|
57
|
+
Labels.callback_text(label: Labels.action_label(method), conditions: conditions)
|
|
58
|
+
end
|
|
59
|
+
end
|
|
60
|
+
end
|
|
61
|
+
|
|
62
|
+
# The event's description lines for its methods' docstrings
|
|
63
|
+
def docstring_lines(event)
|
|
64
|
+
lines = if event[:error]
|
|
65
|
+
['', "Its transitions cannot be described: #{event[:error]}"]
|
|
66
|
+
elsif event[:transitions].empty?
|
|
67
|
+
['', 'No transitions: it never fires.']
|
|
68
|
+
else
|
|
69
|
+
['', 'Transitions (from each state the first that matches is taken):', '',
|
|
70
|
+
*event[:transitions].map { "* #{it}" }]
|
|
71
|
+
end
|
|
72
|
+
lines += ['', "On failure: #{event[:failure].join(', ')}"] if event[:failure].any?
|
|
73
|
+
lines + ['']
|
|
74
|
+
end
|
|
75
|
+
end
|
|
76
|
+
end
|
|
77
|
+
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
|
|
@@ -1,35 +1,160 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'prism'
|
|
4
|
+
|
|
1
5
|
module StateMachines
|
|
2
6
|
module Yard
|
|
3
7
|
module Handlers
|
|
4
|
-
# Handles and processes nodes
|
|
8
|
+
# Handles and processes nodes. A handler reads its call's arguments
|
|
9
|
+
# from the source with Prism and takes only what is written as a
|
|
10
|
+
# literal: nothing in the documented code is run.
|
|
5
11
|
class Base < YARD::Handlers::Ruby::Base
|
|
12
|
+
# An argument that is not a literal, so its value is only known when
|
|
13
|
+
# the code runs
|
|
14
|
+
class Unreadable < StandardError; end
|
|
15
|
+
|
|
16
|
+
# Code the documented source holds where the core takes a value (a
|
|
17
|
+
# state's value: or human_name:), shown as it is written
|
|
18
|
+
Code = Data.define(:source) do
|
|
19
|
+
def to_s = source
|
|
20
|
+
def inspect = source
|
|
21
|
+
end
|
|
22
|
+
|
|
23
|
+
# The literals Ruby spells as keywords
|
|
24
|
+
KEYWORDS = { Prism::NilNode => nil, Prism::TrueNode => true, Prism::FalseNode => false }.freeze
|
|
25
|
+
NUMBERS = [Prism::IntegerNode, Prism::FloatNode].freeze
|
|
26
|
+
# The literals a name can be
|
|
27
|
+
NAMES = [Symbol, String, Integer, Float, TrueClass, FalseClass].freeze
|
|
28
|
+
# Text literals, and how each turns its text into its value
|
|
29
|
+
TEXTS = { Prism::SymbolNode => :to_sym, Prism::StringNode => :itself }.freeze
|
|
6
30
|
|
|
7
31
|
private
|
|
8
32
|
|
|
9
|
-
#
|
|
10
|
-
def
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
nil
|
|
33
|
+
# The handled call as Prism reads it
|
|
34
|
+
def call_node
|
|
35
|
+
@call_node ||= begin
|
|
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)
|
|
39
|
+
|
|
40
|
+
node
|
|
18
41
|
end
|
|
19
42
|
end
|
|
20
43
|
|
|
21
|
-
#
|
|
22
|
-
#
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
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
|
+
|
|
69
|
+
# The call's positional arguments, as nodes
|
|
70
|
+
def positional_arguments
|
|
71
|
+
arguments = call_node.arguments&.arguments || []
|
|
72
|
+
options_node?(arguments.last) ? arguments[0...-1] : arguments
|
|
73
|
+
end
|
|
74
|
+
|
|
75
|
+
# The call's trailing options Hash, as [key node, value node] pairs
|
|
76
|
+
def option_pairs
|
|
77
|
+
last = call_node.arguments&.arguments&.last
|
|
78
|
+
options_node?(last) ? pairs(last) : []
|
|
79
|
+
end
|
|
80
|
+
|
|
81
|
+
def options_node?(node)
|
|
82
|
+
node.is_a?(Prism::KeywordHashNode) || node.is_a?(Prism::HashNode)
|
|
83
|
+
end
|
|
84
|
+
|
|
85
|
+
def pairs(node)
|
|
86
|
+
node.elements.map do |element|
|
|
87
|
+
unreadable(element) unless element.is_a?(Prism::AssocNode)
|
|
88
|
+
|
|
89
|
+
[element.key, element.value]
|
|
31
90
|
end
|
|
32
91
|
end
|
|
92
|
+
|
|
93
|
+
# The value of a literal: a Symbol, String, nil, true, false, number,
|
|
94
|
+
# or an Array or Hash of those
|
|
95
|
+
def literal(node)
|
|
96
|
+
case node
|
|
97
|
+
when *TEXTS.keys then node.unescaped.public_send(TEXTS.fetch(node.class))
|
|
98
|
+
when *KEYWORDS.keys then KEYWORDS.fetch(node.class)
|
|
99
|
+
when *NUMBERS then node.value
|
|
100
|
+
when Prism::ArrayNode then node.elements.map { literal(it) }
|
|
101
|
+
when Prism::HashNode then pairs(node).to_h { |key, value| [literal(key), literal(value)] }
|
|
102
|
+
else unreadable(node)
|
|
103
|
+
end
|
|
104
|
+
end
|
|
105
|
+
|
|
106
|
+
# A state, event or machine name: any literal the core takes as one,
|
|
107
|
+
# a Symbol, String, number, true or false (or nil, the nil state,
|
|
108
|
+
# when +nil_allowed+)
|
|
109
|
+
def name_literal(node, nil_allowed: false)
|
|
110
|
+
value = literal(node)
|
|
111
|
+
return value if NAMES.any? { value.is_a?(it) } || (nil_allowed && value.nil?)
|
|
112
|
+
|
|
113
|
+
unreadable(node)
|
|
114
|
+
end
|
|
115
|
+
|
|
116
|
+
# The names one argument gives: a name, or an Array of them
|
|
117
|
+
def names_in(node, nil_allowed: false)
|
|
118
|
+
return [name_literal(node, nil_allowed: nil_allowed)] unless node.is_a?(Prism::ArrayNode)
|
|
119
|
+
|
|
120
|
+
node.elements.map { name_literal(it, nil_allowed: nil_allowed) }
|
|
121
|
+
end
|
|
122
|
+
|
|
123
|
+
# The literal options among +keys+; any other option is left out. An
|
|
124
|
+
# option written as code is a Code of its source when it is one of
|
|
125
|
+
# +code+, and otherwise left out; either way with a warning, since
|
|
126
|
+
# the documentation cannot show its value.
|
|
127
|
+
def literal_options(keys, code: [])
|
|
128
|
+
option_pairs.each_with_object({}) do |(key, value), options|
|
|
129
|
+
name = literal(key)
|
|
130
|
+
next unless keys.include?(name)
|
|
131
|
+
|
|
132
|
+
options[name] = option_literal(name, value, code)
|
|
133
|
+
rescue Unreadable
|
|
134
|
+
next
|
|
135
|
+
end
|
|
136
|
+
end
|
|
137
|
+
|
|
138
|
+
def option_literal(name, node, code)
|
|
139
|
+
literal(node)
|
|
140
|
+
rescue Unreadable
|
|
141
|
+
documented = code.include?(name) ? 'documented as its source' : 'left out'
|
|
142
|
+
log.warn "state_machines-yard: #{name}: is code (`#{node.slice}`), #{documented} " \
|
|
143
|
+
"(#{parser.file}:#{statement.line})"
|
|
144
|
+
raise unless code.include?(name)
|
|
145
|
+
|
|
146
|
+
Code.new(node.slice)
|
|
147
|
+
end
|
|
148
|
+
|
|
149
|
+
def unreadable(node)
|
|
150
|
+
raise Unreadable, "`#{node.slice}` is code, not a literal"
|
|
151
|
+
end
|
|
152
|
+
|
|
153
|
+
# Logs that +what+ is left out of the documentation, and why
|
|
154
|
+
def skip(what, error)
|
|
155
|
+
log.warn "state_machines-yard: #{what} is not documented: #{error.message} " \
|
|
156
|
+
"(#{parser.file}:#{statement.line})"
|
|
157
|
+
end
|
|
33
158
|
end
|
|
34
159
|
end
|
|
35
160
|
end
|