stateful_controller 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f889a5a37194f712695ca0f064fe3db76e98eee0
+  data.tar.gz: 10c06ed4d4820194456212d79c99049efff5e96d
+SHA512:
+  metadata.gz: d1a710a2d2abe2633ad30799ab5964cdfc66ffd24ddb82e8c648d65f6b5a3dda49e0bedc5546611bedd5d420c99d31ecee40fca067d2dc9817281883f61ed0e5
+  data.tar.gz: 3645e3ea5d77dd54d9d376fd350ff8b25a23888dfc90e10e6b4eaa5eff9476701c0236cb02dbcee364b5e6a63348f02cfedcba806ddec8d112a9ff72281d4232

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# ignore local rvm config
+.ruby-*

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.1.7
+before_install: gem install bundler -v 1.10.6

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

@@ -0,0 +1,52 @@
+source 'https://rubygems.org'
+
+# for local testing only!
+
+  gem 'rails', '3.2.22'
+
+  # Bundle edge Rails instead:
+  # gem 'rails', :git => 'git://github.com/rails/rails.git'
+
+  gem 'sqlite3'
+
+
+  # Gems used only for assets and not required
+  # in production environments by default.
+  group :assets do
+    gem 'sass-rails',   '~> 3.2.3'
+    gem 'coffee-rails', '~> 3.2.1'
+
+    # See https://github.com/sstephenson/execjs#readme for more supported runtimes
+    # gem 'therubyracer', :platforms => :ruby
+
+    gem 'uglifier', '>= 1.0.3'
+  end
+
+  gem 'jquery-rails'
+
+  # To use ActiveModel has_secure_password
+  # gem 'bcrypt-ruby', '~> 3.0.0'
+
+  # To use Jbuilder templates for JSON
+  # gem 'jbuilder'
+
+  # Use unicorn as the app server
+  # gem 'unicorn'
+
+  # Deploy with Capistrano
+  # gem 'capistrano'
+
+  # To use debugger
+  # gem 'debugger'
+
+# end local
+
+# Specify your gem's dependencies in stateful_controller.gemspec
+gemspec
+
+
+# keep personal choice development dependencies here (others should be in the gemspec)
+group :development, :test do
+  gem 'pry'
+  gem 'pry-stack_explorer'
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Larry Kyrala
+
+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,156 @@
+# StatefulController
+
+StatefulController combines the idea of a Rails controller with a [state machine](https://en.wikipedia.org/wiki/Finite-state_machine) 
+that controls navigation through a sequence of views and actions (i.e. a user 'flow').
+
+StatefulController uses the [aasm gem](https://github.com/aasm/aasm) to implement the state machine part of things, so we use its
+terminology to define the state machine. A state machine can be thought of as a graph of states (vertices) connected by event transitions (edges). 
+A StatefulController treats states as Rails' views and events as Rails' actions.  A StatefulController is a Rails controller, so you can call actions directly. But, more interestingly, you can call two special actions: *start* and *next*.
+
+## Example
+
+Start with a simple controller in your Rails app:
+
+```ruby
+class ExampleController < ApplicationController
+  include StatefulController
+
+  class ExampleState < StatefulController::State
+  end
+
+  # states are 'views' and events are 'actions'
+  aasm do 
+    state :sleeping, initial: true
+    state :running
+    state :cleaning
+    
+    event :run do
+      transitions from: :sleeping, to: :running
+    end
+
+    event :clean do 
+      transitions from: :running, to: :cleaning
+    end
+
+    event :sleep do 
+      transitions from: [:running, :cleaning], to: :sleeping
+    end
+  end
+
+  # controller actions here: (same names as events)
+  # do anything here that you need to do for your views, i.e. modify state
+  # load auxillary objects, etc, just like regular Rails controller actions,
+  # the corresponding view (state) will be automatically rendered for you.
+
+  def run
+  end
+
+  def clean
+  end
+
+  def sleep
+  end
+
+  private
+
+  def load_state
+    session[:state] || ExampleState.new
+  end
+
+  def save_state(s)
+    session[:state] = s
+  end
+
+end
+```
+
+Add some views:
+(note that views are not named the same as your actions, but should match your event names!)
+
+```
+app/
+  views/
+    example/
+      cleaning.html.erb
+      running.html.erb
+      sleeping.html.erb
+```
+
+
+Add some routes:
+
+```ruby
+  
+  # don't forget to add the two special routes!
+  get "example/start"
+  get "example/next"
+
+  # and your defined routes:
+  get "example/run"
+  get "example/clean"
+  get "example/sleep"
+```
+
+
+### What does that get us?
+
+Try the following:
+
+```
+http://localhost:3000/example/start   # resets ExampleState, sets current_state to the aasm intial (:sleeping) and shows sleeping.html.erb
+http://localhost:3000/example/next    # checks the permitted events from :sleeping, fires it (:run) and shows running.html.erb
+http://localhost:3000/example/next    # checks the permitted events from :running, fires it (:clean) and shows cleaning.html.erb
+http://localhost:3000/example/next    # checks the permitted events from :cleaning, fires it (:sleep) and shows sleeping.html.erb
+
+```
+
+So, the special *next* action dispatches whatever the next permitted action is (according to the state machine definition above).
+
+What if we don't follow the rules?
+
+```
+http://localhost:3000/example/start   # resets ExampleState, sets current_state to the aasm intial (:sleeping) and shows sleeping.html.erb
+http://localhost:3000/example/clean   # tries to send event :clean, but raises: 
+                                        AASM::InvalidTransition in ExampleController#clean
+                                        Event 'clean' cannot transition from 'sleeping'
+```
+
+### Summary 
+
+You can define the legal transitions in your user flow in the state machine and StatefulController will enforce that flow for you, which 
+greatly simplifies the Rails controller logic for complex flows.  See the source for the dummy Rails application which has more detail and
+interactive examples.
+
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'stateful_controller'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install stateful_controller
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` 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).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/coldnebo/stateful_controller. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/*_test.rb']
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "stateful_controller"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/stateful_controller/version.rb

@@ -0,0 +1,3 @@
+module StatefulController
+  VERSION = "0.1.0"
+end

data/lib/stateful_controller.rb

@@ -0,0 +1,125 @@
+require 'stateful_controller/version'
+require 'active_support/concern'
+require 'aasm'
+require 'ostruct'
+
+module StatefulController
+  extend ActiveSupport::Concern
+
+  class State
+    attr_accessor :current_state
+  end
+
+  included do
+    include AASM
+    attr_reader :state
+    helper_method :state
+    before_filter :__load_and_process, except: :start
+    after_filter :__finish
+    
+    # this section removes the event methods that aasm normally adds to the including object.
+    #   # because this object is meant to be a controller, the events (actions) should obey Rails
+    #   # behavior, so we remove the methods and manage the state transitions internally.
+    class << self
+      alias_method :aasm_orig, :aasm
+
+      def aasm(*args, &block)
+        ret = aasm_orig(*args, &block)  # first process the state machine DSL normally
+        if block
+          # then this is a DSL call, so remove the event methods it normally makes on the the object.
+          methods_to_remove = aasm.events.map(&:name)
+          methods_to_remove.each {|method|
+            remove_method(method)
+          }
+       end
+        ret
+      end
+    end
+  end
+
+  # StatefulController always defines a special action called 'next' that goes to the next available transition.
+  def next
+    # this may rely on events having exactly one transition... otherwise, we may need an argument? (TBD) 
+    next_events = aasm.events(permitted: true).map(&:name)
+    __debug("choosing first from next events: #{next_events.inspect}")
+    next_event = next_events.first
+    __process(next_event)
+    self.send(next_event)
+  end
+
+  # SC also has a special action called "start" which clears state and reloads it (defaulting back to the initial state)
+  def start
+    save_state(nil)
+    __load
+  end
+
+  protected
+
+  def initialize
+    super
+  end
+
+  def default_render(*args)
+    render aasm.current_state
+  end
+
+  # before filter for setup
+  def __load_and_process
+    __load
+
+    # rails action should always be something convertible to a symbol
+    event = params[:action].to_sym
+
+    # next is a special action, don't try to send the event.
+    return if event == :next
+
+    __process(event)
+  end
+
+  def __load
+    @state = load_state
+    __debug("load_state returned #{@state.inspect}")
+    raise ArgumentError, "load_state() must return a StatefulController::State or subclass." unless @state.kind_of?(State)
+
+    # allow the StatefulController to retain it's current state across requests (since controller instances are created per request in Rails)
+    if state.current_state.nil?
+      state.current_state = aasm.current_state  # if load_state didn't recover a current_state, then use the aasm initial.
+    else
+      aasm.current_state = state.current_state  # otherwise, set the aasm.current_state to the loaded current_state.
+    end
+  end
+
+  def __process(event)
+    # manually trigger the event (while we consider the aasm events as "actions", we reserve the methods in the 
+    # controller as actual actions instead of aasm event triggering sugar.)
+    # adapted from ./lib/aasm/base.rb:85
+
+    # while the aasm gem supports multiple state machines per class, StatefulController always uses only one state machine, the default.
+    # so we may substitute :default for @name in the DSL impl:
+    # original line:  aasm(:#{@name}).current_event = :#{name}
+    aasm.current_event = event
+
+    # also, aasm supports arguments for events, but because StatefulController models Rails controller actions, no arguments or blocks are supported.
+    # original line:  aasm_fire_event(:#{@name}, :#{name}, {:persist => false}, *args, &block)
+    aasm_fire_event(:default, event, {persist: false}, [])
+  end
+
+  def __finish
+    state.current_state = aasm.current_state
+    __debug("calling save_state with #{state.inspect}")
+    save_state(state)
+  end
+
+  def load_state
+    raise NotImplementedError, "Controllers that include StatefulController should define the load_state() method."
+  end
+
+  def save_state
+    raise NotImplementedError, "Controllers that include StatefulController should define the save_state() method."
+  end    
+
+  def __debug(msg)
+    Rails.logger.debug("DEBUG [StatefulController]: #{msg}")
+  end
+
+end

data/stateful_controller.gemspec

@@ -0,0 +1,38 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'stateful_controller/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "stateful_controller"
+  spec.version       = StatefulController::VERSION
+  spec.authors       = ["Larry Kyrala"]
+  spec.email         = ["larry.kyrala@gmail.com"]
+
+  spec.summary       = %q{A StatefulController for Rails that uses a state machine to manage transitions between views.}
+  #spec.description   = %q{TODO: Write a longer description or delete this line.}
+  spec.homepage      = "https://github.com/coldnebo/stateful_controller"
+  spec.license       = "MIT"
+
+  # Prevent pushing this gem to RubyGems.org by setting 'allowed_push_host', or
+  # delete this section to allow pushing this gem to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata['allowed_push_host'] = "https://rubygems.org"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
+  end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "rails"
+  spec.add_dependency "aasm"
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest"
+
+  spec.add_development_dependency "yard"
+end

metadata

@@ -0,0 +1,143 @@
+--- !ruby/object:Gem::Specification
+name: stateful_controller
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Larry Kyrala
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-12-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: aasm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  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: 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'
+description: 
+email:
+- larry.kyrala@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/stateful_controller.rb
+- lib/stateful_controller/version.rb
+- stateful_controller.gemspec
+homepage: https://github.com/coldnebo/stateful_controller
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+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.4.8
+signing_key: 
+specification_version: 4
+summary: A StatefulController for Rails that uses a state machine to manage transitions
+  between views.
+test_files: []
+has_rdoc: