simply_fsm 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0fbbc600cd621a9dc61fe1e27e7f1713ffa51e52719e13975e32aae5963ae5b2
-  data.tar.gz: ad107702004bbb2e877b71a55404c53294dc8cdad83dfecbdacbe5cb5bcf7ab1
+  metadata.gz: 0ae5d7b10e3ba09f4838625a6de8dd2314b68246628efed8d950fe087f34f1d7
+  data.tar.gz: cb2f1af32ed62f1032e902391543e6347d0c367eabbe1795e0caf067099baece
 SHA512:
-  metadata.gz: c308a333334a16a02f1d885848c529ef4dc6066367c221cdb93c6ada4eb1fc909557e4376d340df13c34f81ddd03bca7e06f22cac0ca8f71a23c08e18818652a
-  data.tar.gz: b1775decefc14bc483fbe035d8d2b1f65957e07fc8bad9893b3a4c41b5deee0c01f54c67a63cdb32e5f111055bc65619476941981d333f21f520dd9ad8dc79f4
+  metadata.gz: 7f8e0821322ec9e24b9eb5626d59c30e8fa5863d174c53c1d77d041351a635f0a690a111057c3bbd8d58e2aa8418384996314fb39e1f43db3c31c825f229045b
+  data.tar.gz: f7fc248239ca69a84f54ac8a94e25e6bcfc7986e37c40c4bd2dbc5936d4e2a4168be5afbef66351c94f7aabc07debc27ab78ff8133426a6d140082a19f2f2138

data/.gitignore

@@ -10,3 +10,6 @@
 
 # rspec failure tracking
 .rspec_status
+
+# Mac temps
+.DS_Store

data/.yardopts

@@ -0,0 +1 @@
+--no-private

data/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 - None right now
 
+## [0.2.3] - 2022-04-09
+
+- Add `rake yard` to generate local documentation
+- Clean up API documentation
+- Privatise some internal methods
+
+## [0.2.2] - 2022-03-08
+
+- Call `fail` lambda without wrapping it in a lambda
+
 ## [0.2.1] - 2022-03-05
 
 - Fixed bug where named fail handlers were not called properly for multi-transition events.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    simply_fsm (0.2.0)
+    simply_fsm (0.2.3)
 
 GEM
   remote: https://rubygems.org/
@@ -46,6 +46,9 @@ GEM
     ruby-progressbar (1.11.0)
     stringio (3.0.1)
     unicode-display_width (2.1.0)
+    webrick (1.7.0)
+    yard (0.9.27)
+      webrick (~> 1.7.0)
 
 PLATFORMS
   ruby
@@ -56,6 +59,7 @@ DEPENDENCIES
   rspec (~> 3.0)
   rubocop (~> 1.21)
   simply_fsm!
+  yard
 
 BUNDLED WITH
    2.1.4

data/Rakefile

@@ -17,6 +17,13 @@ Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_files.include("lib/**/*.rb")
 end
 
+require "yard"
+
+YARD::Rake::YardocTask.new do |t|
+  t.files = ["lib/**/*.rb"]
+  t.stats_options = ["--list-undoc"]
+end
+
 RuboCop::RakeTask.new
 
 task default: %i[spec rubocop]

data/lib/simply_fsm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SimplyFSM
-  VERSION = "0.2.1"
+  VERSION = "0.2.3"
 end

data/lib/simply_fsm.rb

@@ -2,31 +2,27 @@
 
 require "simply_fsm/version"
 
-##
-# Defines the `SimplyFSM` module
+#
+# Include *SimplyFSM* in a class to be able to defined state machines.
+#
 module SimplyFSM
+  #
+  # Provides a +state_machine+ for the including class.
   def self.included(base)
     base.extend(ClassMethods)
   end
 
-  def state_match?(from, current)
-    return true if from == :any
-    return from.include?(current) if from.is_a?(Array)
-
-    from == current
-  end
-
-  def cannot_transition?(from, cond, current)
-    (from && !state_match?(from, current)) || (cond && !instance_exec(&cond))
-  end
-
-  ##
+  #
   # Defines the constructor for defining a state machine
   module ClassMethods
-    ##
+    #
     # Declare a state machine called +name+ which can then be defined
-    # by a DSL defined by the methods of `StateMachine`, with the following +opts+:
-    # - an optional +fail+ lambda that is called when any event fails to transition)
+    # by a DSL defined by the methods of *StateMachine*.
+    #
+    # @param [String] name of the state machine.
+    # @param [Hash] opts to specify options such as:
+    #   - +fail+ lambda that is called with the event name when any event fails to transition
+    #
     def state_machine(name, opts = {}, &block)
       fsm = StateMachine.new(name, self, fail: opts[:fail])
       fsm.instance_eval(&block)
@@ -34,10 +30,19 @@ module SimplyFSM
   end
 
   ##
-  # The DSL for defining a state machine
+  # The DSL for defining a state machine. These methods are used within the declaration of a +state_machine+.
+  #
+  # @attr_reader [String] initial_state The initial state of the state machine
+  # @attr_reader [Array] states All the states of the state machine
+  # @attr_reader [Array] events All the events of the state machine
+  # @attr_reader [String] name
+  # @attr_reader [String] full_name The name of the owning class combined with the state machine's name
+  #
   class StateMachine
     attr_reader :initial_state, :states, :events, :name, :full_name
 
+    #
+    # @!visibility private
     def initialize(name, owner_class, fail: nil)
       @owner_class = owner_class
       @name = name.to_sym
@@ -50,8 +55,12 @@ module SimplyFSM
       setup_base_methods
     end
 
-    ##
+    #
     # Declare a supported +state_name+, and optionally specify one as the +initial+ state.
+    #
+    # @param [String] state_name
+    # @param [Boolean] initial to indicate if this is the initial state of the state machine
+    #
     def state(state_name, initial: false)
       return if state_name.nil? || @states.include?(state_name)
 
@@ -68,10 +77,11 @@ module SimplyFSM
     ##
     # Define an event by +event_name+
     #
-    # - which +transitions+ as a hash with a +from+ state or array of states and the +to+ state,
-    # - an optional +guard+ lambda which must return true for the transition to occur,
-    # - an optional +fail+ lambda that is called when the transition fails (overrides top-level fail handler), and
-    # - an optional do block that is called +after+ the transition succeeds
+    # @param [String] event_name
+    # @param [Hash,Array] transitions either one (Hash) or many (Array of Hashes) transitions +from+ one state +to+ another state.
+    # @param [Lambda] guard if specified must return +true+ before any transitions are attempted
+    # @param [Lambda] fail called with event name if specified when all the attempted transitions fail
+    # @yield when the transition attempt succeeds.
     def event(event_name, transitions:, guard: nil, fail: nil, &after)
       return unless event_exists?(event_name) && transitions
 
@@ -119,7 +129,7 @@ module SimplyFSM
       if fail.is_a?(String) || fail.is_a?(Symbol)
         ->(event_name) { send(fail, event_name) }
       else
-        ->(event_name) { instance_exec(event_name, &fail) }
+        fail
       end
     end
 
@@ -254,4 +264,17 @@ module SimplyFSM
       @owner_class.define_method(method_name, method_definition)
     end
   end
+
+  private
+
+  def state_match?(from, current)
+    return true if from == :any
+    return from.include?(current) if from.is_a?(Array)
+
+    from == current
+  end
+
+  def cannot_transition?(from, cond, current)
+    (from && !state_match?(from, current)) || (cond && !instance_exec(&cond))
+  end
 end

data/simply_fsm.gemspec

@@ -27,5 +27,6 @@ Gem::Specification.new do |spec|
 
   # development
   spec.add_development_dependency "rdoc"
+  spec.add_development_dependency "yard"
   spec.add_development_dependency "rspec", "~> 3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simply_fsm
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.3
 platform: ruby
 authors:
 - nogginly
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-03-05 00:00:00.000000000 Z
+date: 2022-04-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rdoc
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -49,6 +63,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
+- ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile