mutator 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 847fc513438a0e0cc7e5b9843d93a38f99b7366d
+  data.tar.gz: 4da10747a40b0dad72f827f5d70a38b2042aeb11
+SHA512:
+  metadata.gz: 23aee1ed4688d2df18d93766cd72744a860168b1b4a70f9a2b60b11af8214c35de5f718f72b3963a58d2753000c3459d7e063868f370cbac8d03922219d55da3
+  data.tar.gz: 5cf8f1182e50133c991c72b962f6b805c8142f3197483cbc54be8e7a2bed5f801fe9887f65d5ce3f98cdb82b36c129688e04712a25604810c0490eedb1fee991

data/.gitignore

@@ -0,0 +1,24 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+.ruby-version
+.ruby-gemset

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1
+  - ruby-head

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in mutator.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Eric Roberts
+
+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/README.md

@@ -0,0 +1,127 @@
+# Yet another state machine
+
+Ya, this is another state machine gem. Why? Well, among the major state machine gems I found, they didn't quite do what I was looking for. So I wrote my own. Plus, reinventing the wheel is fun!
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'mutator'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install mutator
+
+## Usage
+
+### So how does this thing work?
+
+Well, I'm going to assume you are adding a state machine to a Rails ActiveRecord class. It can be used for other things but I figure this is the most common example and I don't like writing more documentation than I have to.
+
+``` ruby
+class Wonder < ActiveRecord::Base
+  include Mutator::Helpers
+
+  def state
+    super || :signed # Set the default state. Can also be done in the database.
+  end
+end
+
+module Mutator
+  class Wonder < Machine
+    def self.transitions
+      [
+        { to: :sealed, from: [:signed] },
+        { to: :delivered, from: [:sealed] },
+        { to: :yours, from: [:delivered] }
+      ]
+    end
+  end
+end
+```
+
+### So how do I use it?
+
+Transition looks like this:
+
+``` ruby
+wonder = Wonder.new
+wonder.machine.transition to: :sealed   #=> true
+
+# Invalid Transition
+wonder.machine.current_state            #=> :sealed
+wonder.machine.transition to: :yours    #=> false
+```
+
+### How do I make it do things on success or failure?
+
+Good question. Most state machines have you define callbacks. I wanted to do this one a bit differently. Whenever you call a transition, you are able to tell it what to do on success and failure. You do this like so:
+
+``` ruby
+wonder.machine.current_state            #=> :sealed
+
+success = lambda { |t| puts "delivered!" }
+failure = lambda { |t| puts "failed :(" }
+
+wonder.machine.transition to: :delivered,
+                          success: success,
+                          failure: failure
+
+                          #=> "delivered!"
+                          #=> true
+
+# Invalid Transition
+wonder.machine.transition to: :yours,
+                          success: success,
+                          failure: failure
+
+                          #=> "failed :("
+                          #=> false
+```
+
+The lambdas will be called and passed the transition object. The transition object contains the state you are transitioning to, the state you are transitioning from, the machine, and the stateholder.
+
+### OK, but what if I really want to do the same thing on every transition?
+
+I bet back at the part where I defined `Mutator::Wonder`, you were thinking, "why the hell would you define a whole other class just to define your transitions?". I could have just always included an instance of Machine instead of the subclassed version.
+
+This is a thing I'm still debating. The idea for keeping them separate is that it gives you a place for more state related behaviour to go. For example, to answer the question at the top of this heading, you could define a method to run the transition:
+
+``` ruby
+module Mutator
+  class Wonder < Machine
+    [...]
+
+    # Save the activerecord class on success and raise exception on fail.
+    def deliver!
+      success = lambda { |t| t.stateholder.save! }
+      failure = lambda { |t| fail "Cannot transition to #{t.to} from #{t.from}" }
+      transition to: :delivered, success: success, failure: failure
+    end
+  end
+end
+```
+
+Now you can always use `machine.deliver!` to do the transition to delivered.
+
+### That's all folks!
+
+That's more or less it. You may or may not like the way I've done this state machine, but it works for the purposes I need it for. I'm happy to discuss changes or reasoning behind certain things. There isn't a ton of code so feel free to poke around!
+
+## Contributing
+
+If your change is not just about fixing bugs, I would suggest opening an issue first. I think there are still improvements to be made, but I don't feel like making this a kitchen sink for behaviours provided by other state machines. If you think something should be added, an issue is the best way to let me know and we can discuss if functionality will be added to or changed.
+
+That said, I'm pretty open to changing it, so let me know your thoughts!
+
+Standard contributing instructions: (I have no idea if this is useful... I just always leave it here)
+
+1. Fork it ( https://github.com/ericroberts/mutator/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/mutator/helpers.rb

@@ -0,0 +1,21 @@
+module Mutator
+  module Helpers
+    def machine
+      @machine ||= machine_class.new(self)
+    end
+
+    def self.included(base)
+      "Machines::#{base.name}".constantize.states.each do |state|
+        base.send(:define_singleton_method, state) do
+          self.where(state: state)
+        end
+      end
+    end
+
+  protected
+
+    def machine_class
+      "Machines::#{self.class.name}".constantize
+    end
+  end
+end

data/lib/mutator/machine.rb

@@ -0,0 +1,44 @@
+module Mutator
+  class Machine
+    attr_reader :stateholder
+
+    def initialize(stateholder)
+      @stateholder = stateholder
+    end
+
+    def valid?
+      self.class.states.include? current_state
+    end
+
+    def current_state
+      stateholder.state
+    end
+
+    def transition(to:, success: lambda { |_transition| }, failure: lambda { |_transition| })
+      transition = Transition.new(to: to, from: current_state, machine: self)
+
+      if transition.valid?
+        stateholder.state = to
+        success.call(transition)
+        true
+      else
+        failure.call(transition)
+        false
+      end
+    end
+
+    def self.states
+      self.transitions.map do |t|
+        [t[:to], t[:from]]
+      end.flatten.uniq
+    end
+
+    def states
+      self.class.states
+    end
+
+    def transitions
+      self.class.transitions
+    end
+  end
+end

data/lib/mutator/transition.rb

@@ -0,0 +1,25 @@
+module Mutator
+  class Transition
+    attr_reader :to, :from, :machine
+
+    def initialize(to:, from:, machine:)
+      @to, @from, @machine = to, from, machine
+    end
+
+    def valid?
+      transitions.present?
+    end
+
+    def stateholder
+      machine.stateholder
+    end
+
+  protected
+
+    def transitions
+      machine.transitions.select do |t|
+        t[:to] == to && t[:from].include?(from)
+      end
+    end
+  end
+end

data/lib/mutator/version.rb

@@ -0,0 +1,3 @@
+module Mutator
+  VERSION = "0.0.1"
+end

data/lib/mutator.rb

@@ -0,0 +1,4 @@
+require "mutator/helpers"
+require "mutator/machine"
+require "mutator/transition"
+require "mutator/version"

data/mutator.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'mutator/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "mutator"
+  spec.version       = Mutator::VERSION
+  spec.authors       = ["Eric Roberts"]
+  spec.email         = ["ericroberts@gmail.com"]
+  spec.summary       = %q{Mutator is just another state machine gem.}
+  spec.description   = %q{Yet another state machine gem. I didn't find one I liked, so I made one. I probably didn't look hard enough.}
+  spec.homepage      = "https://github.com/ericroberts/mutator"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "coveralls"
+end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+require 'coveralls'
+Coveralls.wear!

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: mutator
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Eric Roberts
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-08-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  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
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  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'
+description: Yet another state machine gem. I didn't find one I liked, so I made one.
+  I probably didn't look hard enough.
+email:
+- ericroberts@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/mutator.rb
+- lib/mutator/helpers.rb
+- lib/mutator/machine.rb
+- lib/mutator/transition.rb
+- lib/mutator/version.rb
+- mutator.gemspec
+- spec/spec_helper.rb
+homepage: https://github.com/ericroberts/mutator
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Mutator is just another state machine gem.
+test_files:
+- spec/spec_helper.rb