strict_machine 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cd8176055fcd833b0c5e292f89d251ef32067687
-  data.tar.gz: 8c5526e2c67353ce0bb71d52713584219a901d1c
+  metadata.gz: af5b761971dfb358c71f10ac26f27fe6e8bd5d2d
+  data.tar.gz: c09dd654724097dc1db5c1ca9d4106460a3c8303
 SHA512:
-  metadata.gz: e364a995db6ffbde2984893fdc5f2e0b7d2dccf67b85514904aba17a5e66b86db90d958eb1e8e475e85b63589f70ecdcd7cb7cba6f800fb930073c0e7b043257
-  data.tar.gz: 0c2f0375d4df894541648ca6ddd7e2ebc7a14ca90edf6ed867c91a63b8effe15d914aece8e9496d6f9c964b10541bd9fb3853e145d717655272516eabfcb29ff
+  metadata.gz: fb18988d67119ceab8121d57c61c12ab65dd7ba1b55a1ad009d24343488b33a1557185c3f4938cc66671a2425ec9cf3157ef11b7c014cb1093683e7bbd949aad
+  data.tar.gz: 28c3aa5e21a28d1247c4fee56e9b3d0864be384dd831251d9f685cb556bca515c69db7fa81826afa8560d6aa67d56d8f64d9f48bcee5958504a223262b6bc59a

data/README.md

@@ -20,17 +20,134 @@ Or install it yourself as:
 
 ## Usage
 
-Still working on this one...
+You can use this gem in two ways - either by embedding a state machine onto
+your class, or by mounting a separate class.
+
+### Embedded
+
+```ruby
+class A < StrictMachine::Base
+  strict_machine do
+    state :initial do
+      on hop: :middle
+    end
+    state :middle do
+      on hop: :final
+    end
+    state :final
+    on_transition do |from, to, trigger_event, duration|
+      log from, to, trigger_event, duration
+    end
+  end
+
+  def log(from, to, trigger_event, duration)
+   # ...
+  end
+end
+```
+
+### Mounting
+
+(using same class A as previous example, minus the `log` method)
+
+```ruby
+class B
+  include StrictMachine::MountStateMachine
+
+  mount_state_machine A
+
+  def log(from, to, trigger_event, duration)
+   # ...
+  end
+end
+```
+
+**NOTE**: when mounting, the methods referenced should always be on the class doing the mounting, not on the state machine one!
+
+### Object extensions
+
+Whether embedding or mounting, an object instance will have the following
+methods added to it:
+
+- `#state` returns the current state's name
+- `#trigger(*transitions)` triggers the given transition(s) by name
+- `#state_attr` the name of the state attribute being used
+- `#states` list of `State` objects in the machine's definition
+
+and an object's class will have:
+
+- `#definition` the DSL evaluation context object
+- `#strict_machine_attr` the name of the attribute to store state in
+- `#strict_machine_class` either the class containing the state machine, when
+mounting, or `self` when embedding
+- `#strict_machine` the DSL hook
+
+### Internals
+
+The gem works by storing, at the object's class level, the state machine's
+definition and the name of the state storage attribute. Every instance of the class embedding or mounting a state machine will have its own state (stored in said attribute (by default `state`), and upon transitions, the current state and the transition requested will be passed to `#change_state` in
+`InstanceMethods` and a new state will be reached (and `true` returned), or
+an exception will be raised. Existing exceptions:
+
+- `StateNotFoundError` tried to transition to a non-existing state
+- `TransitionNotFoundError` the transition requested does not exist
+- `GuardedTransitionError` the guard condition for the transition was not met
+
+You can bypass the guard condition on a transition by adding a bang `!` to the
+transition's name, i.e.,
+
+```ruby
+  obj.trigger('transition!') # bypass guards
+```
+
+## The DSL
+
+Here's a complete example:
+
+```ruby
+strict_machine do
+  state :new do
+    on submit: :awaiting_review
+  end
+
+  state :awaiting_review do
+    on review: :under_review
+  end
+
+  state :under_review do
+    on_entry { |previous, trigger| some_method(previous, trigger) }
+    on accept: :accepted, if: :cool_article?
+    on reject: :rejected, if: :bad_article?
+  end
+
+  state :accepted
+  state :rejected
+
+  on_transition do |from, to, trigger_event, duration|
+    log from, to, trigger_event, duration
+  end
+end
+```
+
+Guards (the `:if`s on `on` calls) must return `true` in order to pass.
+
+When mounting, you can specify the state attribute's name with:
+
+`mount_state_machine SomeClass, state: "meh"`
+
+And when embedding:
+
+`strict_machine("meh") do ....`
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `strict_machine.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/strict_machine.
+Bug reports and pull requests are welcome on GitHub at https://github.com/sardaukar/strict_machine.
 
 
 ## License

data/lib/strict_machine/definition/state.rb

@@ -31,5 +31,11 @@ module StrictMachine
     def add_on_entry(proc)
       @on_entry << proc
     end
+
+    def run_on_entries(instance, current_state_name, trigger)
+      @on_entry.each do |proc|
+        instance.instance_exec(current_state_name, trigger, &proc)
+      end
+    end
   end
 end

data/lib/strict_machine/definition_context.rb

@@ -21,6 +21,14 @@ module StrictMachine
       @states.first.name
     end
 
+    def run_transitions(instance, current_state, new_state, trigger, duration)
+      @transitions.each do |proc|
+        instance.instance_exec(
+          current_state, new_state, trigger, duration, &proc
+        )
+      end
+    end
+
     ### DSL
 
     def state(name, &block)

data/lib/strict_machine/mount_state_machine/instance_methods.rb

@@ -1,8 +1,10 @@
+require "benchmark"
+
 module StrictMachine
   module MountStateMachine
     module InstanceMethods
       def trigger(*transitions)
-        transitions.map {|t| change_state(t, state) }
+        transitions.map { |t| change_state(t, state) }
 
         true
       end
@@ -14,7 +16,7 @@ module StrictMachine
       end
 
       def state_attr
-        self.class.strict_machine_attr.to_s.gsub("@",'')
+        self.class.strict_machine_attr.to_s.delete("@")
       end
 
       def states
@@ -44,31 +46,29 @@ module StrictMachine
       end
 
       def change_state(trigger, current_state_name)
-        dt = Time.now
-        current_state = definition.get_state_by_name(current_state_name)
-        is_bang, transition = current_state.get_transition(trigger)
+        new_state = nil
 
-        if transition.guarded? && !is_bang
-          raise GuardedTransitionError unless self.public_send(
-            transition.guard
-          )
-        end
+        duration = Benchmark.measure do
+          is_bang, transition = current_state_obj.get_transition(trigger)
 
-        new_state = definition.get_state_by_name(transition.to)
-        new_state.on_entry.each do |proc|
-          self.instance_exec(current_state_name, trigger.to_sym, &proc)
-        end
+          if transition.guarded? && !is_bang
+            raise GuardedTransitionError unless public_send(transition.guard)
+          end
 
-        duration = Time.now - dt
+          new_state = definition.get_state_by_name(transition.to)
+          new_state.run_on_entries(self, current_state_name, trigger.to_sym)
+        end.real
 
-        definition.transitions.each do |proc|
-          self.instance_exec(
-            current_state_name, new_state.name, trigger.to_sym, duration, &proc
-          )
-        end
+        definition.run_transitions(
+          self, current_state_name, new_state.name, trigger.to_sym, duration
+        )
 
         write_state(new_state.name)
       end
+
+      def current_state_obj
+        definition.get_state_by_name(current_state_attr_value)
+      end
     end
   end
 end

data/lib/strict_machine.rb

@@ -1,13 +1,12 @@
 require_relative "ext/object"
 
 module StrictMachine
-  VERSION = "0.2.0".freeze
+  VERSION = "0.2.1".freeze
 
   class << self; attr_accessor :list; end
 end
 
 class StateNotFoundError < StandardError; end
-class InvalidTransitionError < StandardError; end
 class TransitionNotFoundError < StandardError; end
 class GuardedTransitionError < StandardError; end
 

data/strict_machine.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["sardaukar.siet@gmail.com"]
 
   spec.summary       = "State machine functionality for Ruby classes"
-  spec.homepage      = "https://not-yet.com"
+  spec.homepage      = "https://github.com/sardaukar/strict_machine"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: strict_machine
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Bruno Antunes
@@ -101,7 +101,7 @@ files:
 - spec/mountable_machine_spec.rb
 - spec/spec_helper.rb
 - strict_machine.gemspec
-homepage: https://not-yet.com
+homepage: https://github.com/sardaukar/strict_machine
 licenses:
 - MIT
 metadata: {}