nanomachine 1.0.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+-Ilib
+--require ./spec/spec_helper

data/.travis.yml

@@ -0,0 +1,8 @@
+rvm:
+  - "1.9.3"
+  - "1.9.2"
+  - "jruby-19mode"
+  - "rbx-19mode"
+  - "1.8.7"
+  - "jruby-18mode"
+  - "rbx-18mode"

data/Gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem "yard"

data/README.md

@@ -0,0 +1,76 @@
+# Nanomachine
+
+A really tiny state machine for ruby. No events, only accepted transitions and transition callbacks.
+
+The difference between Nanomachine, and otherwise known Micromachine (https://rubygems.org/gems/micromachine) is that
+Micromachine transitions to new states in response to events; multiple events can transition between the two same states.
+Nanomachine, on the other hand, does not care about events, and only needs the state you want to be in after successful
+transition.
+
+Nanomachine can be used in any ruby project, and have no runtime dependencies.
+
+## Installation
+
+Install the gem:
+
+```shell
+gem install nanomachine
+```
+
+or add it to your Gemfile, if you are using [Bundler][]:
+
+```ruby
+gem "nanomachine", "~> 1.0"
+```
+
+[Bundler]: http://gembundler.com/
+
+## Example
+
+```ruby
+state_machine = Nanomachine.new("unpublished") do |fsm|
+  fsm.transition("published", %w[unpublished processing removed])
+  fsm.transition("unpublished", %w[published processing removed])
+  fsm.transition("processing", %w[published unpublished])
+  fsm.transition("removed", []) # defined for being explicit
+
+  fsm.on_transition(:to => "processing") do |(previous_state, _), id|
+    Worker.schedule(id, previous_state)
+  end
+
+  fsm.on_transition do |(from_state, to_state)|
+    update_column(:state, to_state)
+  end
+end
+
+if state_machine.transition_to("published")
+  puts "Publish success!"
+else
+  puts "Publish failure! We’re in #{state_machine.state}."
+end
+```
+
+## License
+
+Copyright (c) 2012 Ivan Navarrete and Kim Burgestrand
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,34 @@
+begin
+  require "bundler/gem_tasks"
+rescue LoadError
+  # bundler not required
+end
+
+begin
+  require "yard"
+  YARD::Rake::YardocTask.new("yard:doc") do |task|
+    task.options = ["--no-stats"]
+  end
+
+  desc "List undocumented methods and constants"
+  task "yard:stats" do
+    YARD::CLI::Stats.run("--list-undoc")
+  end
+
+  desc "Generate documentation and show documentation stats"
+  task :yard => ["yard:doc", "yard:stats"]
+rescue LoadError
+  puts "WARN: YARD not available. You may install documentation dependencies via bundler."
+end
+
+desc "Start an IRB session with Nanomachine loaded"
+task :console do
+  exec "irb", "-Ilib", "-rnanomachine"
+end
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new do |spec|
+  spec.ruby_opts = ["-W"]
+end
+
+task :default => :spec

data/lib/nanomachine.rb

@@ -0,0 +1,183 @@
+require "nanomachine/version"
+require "set"
+
+# A minimal state machine where you transition between states, instead
+# of transition by input symbols or events.
+#
+# @example
+#   state_machine = Nanomachine.new("unpublished") do |fsm|
+#     fsm.transition("published", %w[unpublished processing removed])
+#     fsm.transition("unpublished", %w[published processing removed])
+#     fsm.transition("processing", %w[published unpublished])
+#     fsm.transition("removed", []) # defined for being explicit
+#
+#     fsm.on_transition do |(from_state, to_state)|
+#       update_column(:state, to_state)
+#     end
+#   end
+#
+#   if state_machine.transition_to("published")
+#     puts "Publish success!"
+#   else
+#     puts "Publish failure! We’re in #{state_machine.state}."
+#   end
+#
+#
+class Nanomachine
+  # Raised when a transition cannot be performed.
+  InvalidTransitionError = Class.new(StandardError)
+
+  # Raised when a given state cannot be accepted.
+  InvalidStateError = Class.new(StandardError)
+
+  # Construct a Nanomachine with an initial state.
+  #
+  # @example initialization with a block
+  #   machine = Nanomachine.new("initial") do |fsm|
+  #     fsm.transition("initial", %w[green orange])
+  #     fsm.transition("green", %w[orange error])
+  #     fsm.transition("orange", %w[green error])
+  #     # error is a dead state, no transition out of it
+  #     # so not necessary to define the transitions for it
+  #
+  #     fsm.on_transition(to: "error") do |(from_state, to_state), message|
+  #       notifier.notify_error(message)
+  #     end
+  #
+  #     fsm.on_transition do |(from_state, to_state)|
+  #       object.update_state(to_state)
+  #     end
+  #   end
+  #
+  # @param [#to_s] initial_state state the machine is in after initialization
+  # @raise [InvalidStateError] if initial state is nil
+  # @yield [self] yields the machine for easy definition of states
+  # @yieldparam [Nanomachine] self
+  def initialize(initial_state)
+    if initial_state.nil?
+      raise InvalidStateError, "initial state cannot be nil"
+    end
+
+    @state = initial_state.to_s
+    @transitions = Hash.new(Set.new)
+    @callbacks = Hash.new { |h, k| h[k] = [] }
+    yield self if block_given?
+  end
+
+  # @return [String] current state of the state machine.
+  attr_reader :state
+
+  # @example
+  #   {"initial"=>#<Set: {"green", "orange"}>,
+  #    "green"=>#<Set: {"orange", "error"}>,
+  #    "orange"=>#<Set: {"green", "error"}>}
+  #
+  # @return [Hash<String, Set>] mapping of state to possible transition targets
+  attr_reader :transitions
+
+  # Define possible state transitions from the source state.
+  #
+  # @example
+  #   fsm.transition("green", %w[orange red])
+  #   fsm.transition("orange", %w[red])
+  #   fsm.transition(:error, [:nowhere])
+  #
+  # @param [#to_s] from
+  # @param [#each] to each target state must respond to #to_s
+  def transition(from, to)
+    transitions[from.to_s] = Set.new(to).map!(&:to_s)
+  end
+
+  # Define a callback to be executed on transition.
+  #
+  # @example callback executed on any transition
+  #   fsm.on_transition do |(from_state, to_state), *args, &block|
+  #     # executed on any transition
+  #   end
+  #
+  # @example callback executed on transition from a given state only
+  #   fsm.on_transition(from: "green") do |(from_state, to_state), *args, &block|
+  #     # executed only on transitions *from* green state
+  #   end
+  #
+  # @example callback executed on transition to a given state only
+  #   fsm.on_transition(to: "green") do |(from_state, to_state), *args, &block|
+  #     # executed only on transitions *to* green state
+  #   end
+  #
+  # @example callback executed on transition between two states only
+  #   fsm.on_transition(from: "green", to: "red") do |(from_state, to_state), *args, &block|
+  #     # executed only on transitions between green and red
+  #   end
+  #
+  # @param [Hash] options constraint on when callback is to be executed
+  # @option options [#to_s, nil] :from (nil) only match when transitioning from the given state, nil for any
+  # @option options [#to_s, nil] :to (nil) only match when transitioning to the given state, nil for any
+  # @yield [transition, *args, &block] transition states (from, to), and parameters given to {#transition_to} on transition
+  # @yieldparam [Array<from_state, to_state>] transition
+  # @yieldparam *args arguments passed to {#transition_to}
+  # @yieldparam &block block passed to {#transition_to}
+  # @raise [ArgumentError] when given unknown options
+  # @raise [LocalJumpError] when no callback block is supplied
+  def on_transition(options = {}, &block)
+    unless block_given?
+      raise LocalJumpError, "no block given"
+    end
+
+    from = options.delete(:from)
+    from &&= from.to_s
+
+    to = options.delete(:to)
+    to &&= to.to_s
+
+    unless options.empty?
+      raise ArgumentError, "unknown options: #{options.keys.join(", ")}"
+    end
+
+    @callbacks[[from, to]] << block
+  end
+
+  # Transition the state machine from the current state to a target state.
+  #
+  # @example transition to error state with a message given to any callbacks
+  #   if previous_state = fsm.transition_to("error", "something went really wrong")
+  #     puts "Transition from #{previous_state} to #{fsm.state} successful!"
+  #   else
+  #     puts "Transition failed."
+  #   end
+  #
+  # @param [#to_s] other_state new state to transition to
+  # @param args any number of arguments, passed to callbacks defined with {#on_transition}
+  # @param block passed to callbacks defined with {#on_transition}
+  # @return [String, false] state the machine was in before transition, or false if transition is not allowed
+  def transition_to(other_state, *args, &block)
+    other_state &&= other_state.to_s
+    if transitions[state].include?(other_state)
+      previous_state, @state = @state, other_state
+      [[nil, nil], [previous_state, nil], [nil, @state], [previous_state, @state]].each do |combo|
+        @callbacks[combo].each do |callback|
+          callback.call([previous_state, @state], *args, &block)
+        end
+      end
+      previous_state
+    else
+      false
+    end
+  end
+
+  # Same as {#transition_to}, but raises an error if the transition is not allowed.
+  #
+  # @example
+  #   fsm.transition_to!("bogus state") # => InvalidTransitionError
+  #
+  # @param (see #transition_to)
+  # @return [String] the state the state machine was in before transition
+  # @raise [InvalidTransitionError] if the state machine cannot transition from current state to target state
+  def transition_to!(other_state)
+    if previous_state = transition_to(other_state)
+      previous_state
+    else
+      raise InvalidTransitionError, "cannot transition from #{state.inspect} to #{other_state.inspect}"
+    end
+  end
+end

data/lib/nanomachine/version.rb

@@ -0,0 +1,4 @@
+class Nanomachine
+  # @see http://semver.org/
+  VERSION = "1.0.0"
+end

data/nanomachine.gemspec

@@ -0,0 +1,52 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "nanomachine/version"
+
+Gem::Specification.new do |gem|
+  gem.name          = "nanomachine"
+  gem.summary       = "A really tiny state machine for ruby. No events, only acceptable transitions and transition callbacks."
+  gem.description   = <<-DESCRIPTION.gsub(/^ */, "")
+    A really tiny state machine for ruby. No events, only accepted transitions and transition callbacks.
+
+    The difference between Nanomachine, and otherwise known Micromachine (https://rubygems.org/gems/micromachine) is that
+    Micromachine transitions to new states in response to events; multiple events can transition between the two same states.
+    Nanomachine, on the other hand, does not care about events, and only needs the state you want to be in after successful
+    transition.
+
+    Nanomachine can be used in any ruby project, and have no runtime dependencies.
+
+    Example:
+      state_machine = Nanomachine.new("unpublished") do |fsm|
+        fsm.transition("published", %w[unpublished processing removed])
+        fsm.transition("unpublished", %w[published processing removed])
+        fsm.transition("processing", %w[published unpublished])
+        fsm.transition("removed", []) # defined for being explicit
+
+        fsm.on_transition do |(from_state, to_state)|
+          update_column(:state, to_state)
+        end
+      end
+
+      if state_machine.transition_to("published")
+        puts "Publish success!"
+      else
+        puts "Publish failure! We’re in \#{state_machine.state}."
+      end
+  DESCRIPTION
+
+  gem.version       = Nanomachine::VERSION
+
+  gem.homepage      = "https://github.com/elabs/nanomachine"
+  gem.authors       = ["Ivan Navarrete", "Kim Burgestrand"]
+  gem.email         = ["crzivn@gmail.com", "kim@burgestrand.se"]
+  gem.license       = "MIT License"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "rspec", "~> 2.0"
+end

data/spec/nano_machine_spec.rb

@@ -0,0 +1,163 @@
+describe "Nanomachine state machine" do
+  before do
+    @callbacks = []
+  end
+
+  let(:fsm) do
+    Nanomachine.new("A") do |m|
+      m.transition("A", %w[B C E X])
+      m.transition("B", %w[A])
+      m.transition(:C, [:A, :D])
+      m.transition("D", %w[])
+      m.transition("E", %w[B C])
+
+      m.on_transition(:to => "B") do |*args, &block|
+        @callbacks << [:to, args, block]
+      end
+
+      m.on_transition(:from => "A") do |*args, &block|
+        @callbacks << [:from, args, block]
+      end
+
+      m.on_transition(:from => "A", :to => "B") do |*args, &block|
+        @callbacks << [:from_to, args, block]
+      end
+
+      m.on_transition(:from => "E", :to => "C") do |*args, &block|
+        @callbacks << [:from_to_e, args, block]
+      end
+
+      m.on_transition do |*args, &block|
+        @callbacks << [:any, args, block]
+      end
+    end
+  end
+
+  describe "VERSION" do
+    specify { Nanomachine::VERSION.should be_a String }
+  end
+
+  describe "#initialize" do
+    it "raises an error if given an invalid initial state" do
+      expect { Nanomachine.new(nil) }.to raise_error(Nanomachine::InvalidStateError, /initial state/)
+    end
+  end
+
+  describe "#state" do
+    it "returns the current state" do
+      fsm.state.should eq("A")
+    end
+  end
+
+  describe "#transitions" do
+    it "returns the available transitions" do
+      fsm.transitions.should eq({"A" => Set.new(%w[B C E X]),
+                                 "B" => Set.new(%w[A]),
+                                 "C" => Set.new(%w[A D]),
+                                 "D" => Set.new(),
+                                 "E" => Set.new(%w[B C])})
+    end
+  end
+
+  describe "#on_transition" do
+    it "raises an error when given unknown options" do
+      expect { fsm.on_transition(:bad_option => "foo") { } }.to raise_error(ArgumentError, /bad_option/)
+    end
+
+    it "raises an error when given no block" do
+      expect { fsm.on_transition }.to raise_error(LocalJumpError, /no block given/)
+    end
+  end
+
+  describe "#transition_to" do
+    it "transitions to the new state" do
+      expect { fsm.transition_to("B") }.to change { fsm.state }.from("A").to("B")
+    end
+
+    it "does not transition when the transition is undefined" do
+      fsm.transition_to("X")
+      expect { fsm.transition_to("A").should be_false }.to_not change { fsm.state }
+    end
+
+    it "returns the previous state" do
+      fsm.transition_to("B").should eq("A")
+    end
+
+    it "returns false if transition failed" do
+      fsm.transition_to("D").should be_false
+    end
+
+    context "callbacks" do
+      it "executes all callbacks in the correct order, most generic first" do
+        block = proc {}
+        args = [1, [3, 4]]
+
+        fsm.transition_to("B", *args, &block)
+
+        @callbacks.should eq([
+          [:any, [["A", "B"], 1, [3, 4]], block],
+          [:from, [["A", "B"], 1, [3, 4]], block],
+          [:to, [["A", "B"], 1, [3, 4]], block],
+          [:from_to, [["A", "B"], 1, [3, 4]], block]
+        ])
+      end
+
+      it "executes callbacks reacting to any transition" do
+        fsm.transition_to("C")
+        @callbacks.clear
+        fsm.transition_to("D")
+
+        @callbacks.should eq([
+          [:any, [["C", "D"]], nil],
+        ])
+      end
+
+      it "executes callbacks for the from-transition" do
+        fsm.transition_to("C")
+
+        @callbacks.should eq([
+          [:any, [["A", "C"]], nil],
+          [:from, [["A", "C"]], nil],
+        ])
+      end
+
+      it "executes callbacks for the to-transition" do
+        fsm.transition_to("E")
+        @callbacks.clear
+        fsm.transition_to("B")
+
+        @callbacks.should eq([
+          [:any, [["E", "B"]], nil],
+          [:to, [["E", "B"]], nil],
+        ])
+      end
+
+      it "executes callbacks for the from-to-transition" do
+        fsm.transition_to("E")
+        @callbacks.clear
+        fsm.transition_to("C")
+
+        @callbacks.should eq([
+          [:any, [["E", "C"]], nil],
+          [:from_to_e, [["E", "C"]], nil],
+        ])
+      end
+
+      it "executes no callbacks on failed transitions" do
+        fsm.transition_to("D").should be_false
+        @callbacks.should be_empty
+      end
+    end
+  end
+
+  describe "#transition_to!" do
+    it "raises an error on an invalid transition" do
+      fsm.should_receive(:transition_to).and_return(false)
+      expect { fsm.transition_to!("D") }.to raise_error(Nanomachine::InvalidTransitionError, /cannot transition/)
+    end
+
+    it "returns the previous state on success" do
+      fsm.transition_to!("B").should eq "A"
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+require "rspec"
+require "nanomachine"

metadata

@@ -0,0 +1,136 @@
+--- !ruby/object:Gem::Specification
+name: nanomachine
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Ivan Navarrete
+- Kim Burgestrand
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-11-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &2170833800 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *2170833800
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &2170833240 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: *2170833240
+description: ! 'A really tiny state machine for ruby. No events, only accepted transitions
+  and transition callbacks.
+
+
+  The difference between Nanomachine, and otherwise known Micromachine (https://rubygems.org/gems/micromachine)
+  is that
+
+  Micromachine transitions to new states in response to events; multiple events can
+  transition between the two same states.
+
+  Nanomachine, on the other hand, does not care about events, and only needs the state
+  you want to be in after successful
+
+  transition.
+
+
+  Nanomachine can be used in any ruby project, and have no runtime dependencies.
+
+
+  Example:
+
+  state_machine = Nanomachine.new("unpublished") do |fsm|
+
+  fsm.transition("published", %w[unpublished processing removed])
+
+  fsm.transition("unpublished", %w[published processing removed])
+
+  fsm.transition("processing", %w[published unpublished])
+
+  fsm.transition("removed", []) # defined for being explicit
+
+
+  fsm.on_transition do |(from_state, to_state)|
+
+  update_column(:state, to_state)
+
+  end
+
+  end
+
+
+  if state_machine.transition_to("published")
+
+  puts "Publish success!"
+
+  else
+
+  puts "Publish failure! We’re in #{state_machine.state}."
+
+  end
+
+'
+email:
+- crzivn@gmail.com
+- kim@burgestrand.se
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .travis.yml
+- Gemfile
+- README.md
+- Rakefile
+- lib/nanomachine.rb
+- lib/nanomachine/version.rb
+- nanomachine.gemspec
+- spec/nano_machine_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/elabs/nanomachine
+licenses:
+- MIT License
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: A really tiny state machine for ruby. No events, only acceptable transitions
+  and transition callbacks.
+test_files:
+- spec/nano_machine_spec.rb
+- spec/spec_helper.rb
+has_rdoc: