finity 0.0.1

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2012 Martin Donath
+
+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/README.md

@@ -0,0 +1,106 @@
+# Finity
+
+**Finity** tries to be an extremly lightweight state machine implementation with an easily readable syntax
+which is essential if you have tens or hundreds of transitions. It is inspired by [transitions][], 
+a great state machine implementation tightly integrated with ActiveRecord by Jakub Kuźma and Timo Rößner.
+
+[https://github.com/troessner/transitions][transitions]
+
+The goal of **Finity** is to provide a state machine implementation which is as slim and fast as possible
+while maintaining a beautiful and readable syntax. If you need ActiveModel/ActiveRecord integration,
+[transitions][] is your weapon of choice. However, if you only need a plain state machine implementation
+which is optimized for readability and efficiency, give **Finity** a spin.
+
+## Installation
+
+If you use Rails, include this into your Gemfile and run `bundle install` via command line:
+
+```
+gem 'finity'
+```
+
+If you're not using Rails, you can install **Finity** with `gem` via command line:
+
+```
+gem install finity
+```
+
+## Usage
+
+**Finity** can transform any class into a state machine. The only thing you have to do is to include it
+and define some transitions. For example, consider a state machine modelling the different states of reading
+the contents of a file:
+
+```
+class Readfile
+  include Finity
+
+  finity :init => :opened do
+
+    state :opened,
+      :enter => proc { @file = File.open '...' }
+
+    state :reading,
+      :enter => proc { process @file.readline }
+
+    state :closed,
+      :enter => proc { @file.close '...' }
+
+    event :read do
+      transitions :from => [:opened, :reading], :to => :reading,
+        :if => proc { not @file.eof? }
+        :do => proc { log 'Reading next line of file' }
+
+      transitions :from => [:opened, :reading], :to => :reading,
+        :do => proc { log 'Reached end of file' }
+    end
+
+    event :close do
+      transitions :from => [:opened, :reading], :to => :closed,
+        :do => proc { log 'Closing file handle' }
+    end
+  end
+end
+```
+
+## States
+
+A state is defined by its name and can define transition functions upon entering and leaving the state.
+These functions can be either referenced as Symbols, Strings, Procs or Lambda:
+
+```
+state :some_state,
+  :enter => proc { do_something and some_other_thing },
+  :leave => :execute_leave_action!
+```
+
+## Events and Transitions
+
+Events are like states defined by their names and can trigger several transitions from several states 
+to other states. The transitions are evaluated in the order they are defined. If a valid transition is
+found, the execution is stopped and the transition performed:
+
+```
+event :some_event do
+  transitions :from => [:some_state, :another_state], :to => :another_state,
+    :if => proc { is_some_condition_true? },
+    :do => :execute_something_upon_transition
+
+  transitions :from => [:some_state], :to => :another_state,
+    :do => :execute_something_else
+end
+```
+
+Transitions can be guarded by decision functions (`:if`) and execute another function upon successful
+matching (`:do`). Transitions are triggered by the method `event!` which is defined for the including
+object. Many other state machine implementations define one method for each event and for each state,
+however, **Finity** tries to be as minimally invasive as possible:
+
+```
+  object = SomeClassIncludingFinity.new
+  if object.state? :some_state
+    object.event! :some_event
+  end
+```
+
+[transitions]: https://github.com/troessner/transitions

data/finity.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path("../lib/finity/version", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = 'finity'
+  s.version     = Finity::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ['Martin Donath']
+  s.email       = 'md@struct.cc'
+  s.homepage    = 'http://github.com/squidfunk/finity'
+  s.summary     = 'Slim and more readable state machine for Ruby'
+  s.description = 'Extremly lightweight implementation with an easily readable syntax, ' +
+                  'which is essential if you have tens or hundreds of transitions'
+
+  s.required_rubygems_version = '>= 1.3.6'
+  s.add_development_dependency 'bundler', '~> 1'
+
+  s.files        = `git ls-files`.split("\n")
+  s.executables  = `git ls-files`.split("\n").map{|f| f =~ /^bin\/(.*)/ ? $1 : nil}.compact
+  s.require_path = 'lib'
+end

data/lib/finity.rb

@@ -0,0 +1,65 @@
+# Copyright (c) 2012 Martin Donath
+
+# 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.
+
+require 'finity/event'
+require 'finity/machine'
+require 'finity/state'
+require 'finity/transition'
+require 'finity/version'
+
+module Finity
+  class InvalidCallback < StandardError; end
+  class MissingCallback < StandardError; end
+  class InvalidState    < StandardError; end
+
+  # Class methods to be injected into the including class upon inclusion.
+  module ClassMethods
+    attr_accessor :machine
+
+    # When inheriting this module, pass the registered machines to the
+    # inheriting class after executing potential parent inheritance logic.
+    def inherited klass
+      super and klass.machine = machine
+    end
+
+    # Instantiate a new state machine for the including class by accepting a
+    # block with state and event (and subsequent transition) definitions.
+    def finity options = {}, &block
+      @machine = Machine.new self, options, &block
+    end
+
+    # Return the names of all registered states.
+    def states
+      @machine.states.map { |name, _| name }
+    end
+
+    # Return the names of all registered events.
+    def events
+      @machine.events.map { |name, _| name }
+    end
+  end
+
+  # Inject methods into the including class upon inclusion.
+  def self.included base
+    base.extend ClassMethods
+  end
+end

data/lib/finity/event.rb

@@ -0,0 +1,51 @@
+# Copyright (c) 2012 Martin Donath
+
+# 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.
+
+module Finity
+  class Event
+    attr_accessor :name
+
+    # Initialize a new event and execute the block which holds the
+    # transition definitions.
+    def initialize name, options = {}, &block
+      @name, @transitions = name, {}
+      instance_eval &block if block_given?
+    end
+
+    # Add a transition to the event.
+    def transitions options = {}
+      transition = Transition.new options
+      [options[:from]].flatten.each do |from|
+        @transitions[from] ||= []
+        @transitions[from] << transition
+      end
+    end
+
+    # Handle the current state and execute the first allowed transition.
+    def handle object, state
+      @transitions[state.name].find do |transition|
+        name = transition.handle object
+        return name unless name.nil?
+      end
+    end
+  end
+end

data/lib/finity/machine.rb

@@ -0,0 +1,69 @@
+# Copyright (c) 2012 Martin Donath
+
+# 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.
+
+module Finity
+  class Machine
+    attr_accessor :states, :events, :current
+
+    # Initialize a new state machine within the provided class and define
+    # methods for querying the current state and initiating transitions.
+    def initialize klass, options = {}, &block
+      @klass, @states, @events, @init = klass, {}, {}, options.delete(:init)
+      @klass.send :define_method, :event! do |*args|
+        klass.machine.update self, *args
+      end
+      @klass.send :define_method, :state? do |*args|
+        klass.machine.current.name.eql? *args
+      end
+      instance_eval &block if block_given?
+    end
+
+    # Return the name of the initial state.
+    def init
+      @init ||= @states.keys.first unless @states.first.nil?
+    end
+
+    # Register a state.
+    def state name, options = {}
+      @states[name] = State.new name, options
+    end
+
+    # Register an event and evaluate the block for transitions.
+    def event name, options = {}, &block
+      @events[name] = Event.new name, options, &block
+    end
+
+    # An event occured, so update the state machine by evaluating the
+    # transition functions and notify the left and entered state.
+    def update object, event
+      @current ||= @states[init]
+      if (state = @events[event].handle object, @current)
+        if @states[state].nil?
+          raise InvalidState, "Invalid state '#{state}'"
+        end
+        @current.leave object
+        @current = @states[state]
+        @current.enter object
+      end
+    end
+  end
+end

data/lib/finity/state.rb

@@ -0,0 +1,59 @@
+# Copyright (c) 2012 Martin Donath
+
+# 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.
+
+module Finity
+  class State
+    attr_accessor :name
+
+    # Initialize a new state for the state machine with callbacks.
+    def initialize name, options = {}
+      @name, @enter, @leave = name, *options.values_at(:enter, :leave)
+      instance_eval &block if block_given?
+    end
+
+    # Executed when the current state is entered.
+    def enter object
+      execute object, @enter unless @enter.nil?
+    end
+
+    # Executed when the current state is left.
+    def leave object
+      execute object, @leave unless @leave.nil?
+    end
+
+    private
+
+    # Internal method to execute a provided action on a given object. The
+    # action can be a symbol, string, proc or lambda function.
+    def execute object, action
+      case action
+      when Symbol, String
+        object.send action
+      when Proc
+        action.lambda? and action.call object or object.instance_eval &action
+      else
+        raise InvalidCallback, 'Only symbols, strings, procs and lambdas may ' +
+                               'be passed as callbacks'
+      end
+    end
+  end
+end

data/lib/finity/transition.rb

@@ -0,0 +1,60 @@
+# Copyright (c) 2012 Martin Donath
+
+# 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.
+
+module Finity
+  class Transition
+
+    # A transition must define at least one original state (:from) and
+    # a state it transitions to (:to).
+    def initialize options
+      @from, @to, @if, @do = options.values_at(:from, :to, :if, :do)
+      if @from.nil? or @to.nil?
+        raise MissingCallback, 'A transition demands states at least one original ' +
+                               'state (:from) and a state it transitions to (:to)'
+      end
+    end
+
+    # Check, whether the current transition is allowed and execute it.
+    def handle object
+      if @if.nil? or execute object, @if
+        execute object, @do unless @do.nil?
+        @to
+      end
+    end
+
+    private
+
+    # Internal method to execute a provided action on a given object. The
+    # action can be a symbol, string, proc or lambda function.
+    def execute object, action
+      case action
+      when Symbol, String
+        object.send action
+      when Proc
+        action.lambda? and action.call object or object.instance_eval &action
+      else
+        raise InvalidCallback, 'Only symbols, strings, procs and lambdas may ' +
+                               'be passed as callbacks'
+      end
+    end
+  end
+end

data/lib/finity/version.rb

@@ -0,0 +1,3 @@
+module Finity
+  VERSION = '0.0.1'
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: finity
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Martin Donath
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-06-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1'
+description: Extremly lightweight implementation with an easily readable syntax, which
+  is essential if you have tens or hundreds of transitions
+email: md@struct.cc
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- finity.gemspec
+- lib/finity.rb
+- lib/finity/event.rb
+- lib/finity/machine.rb
+- lib/finity/state.rb
+- lib/finity/transition.rb
+- lib/finity/version.rb
+homepage: http://github.com/squidfunk/finity
+licenses: []
+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: 1.3.6
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Slim and more readable state machine for Ruby
+test_files: []