branston 0.3.6 → 0.4.0

data/lib/branston/vendor/plugins/state_machine/README.rdoc

@@ -0,0 +1,466 @@
+== state_machine
+
++state_machine+ adds support for creating state machines for attributes on any
+Ruby class.
+
+== Resources
+
+API
+
+* http://api.pluginaweek.org/state_machine
+
+Bugs
+
+* http://pluginaweek.lighthouseapp.com/projects/13288-state_machine
+
+Development
+
+* http://github.com/pluginaweek/state_machine
+
+Source
+
+* git://github.com/pluginaweek/state_machine.git
+
+== Description
+
+State machines make it dead-simple to manage the behavior of a class.  Too often,
+the state of an object is kept by creating multiple boolean attributes and
+deciding how to behave based on the values.  This can become cumbersome and
+difficult to maintain when the complexity of your class starts to increase.
+
++state_machine+ simplifies this design by introducing the various parts of a real
+state machine, including states, events, transitions, and callbacks.  However,
+the api is designed to be so simple you don't even need to know what a
+state machine is :)
+
+Some brief, high-level features include:
+* Defining state machines on any Ruby class
+* Multiple state machines on a single class
+* Namespaced state machines
+* before/after transition hooks with explicit transition requirements
+* ActiveRecord integration
+* DataMapper integration
+* Sequel integration
+* State predicates
+* State-driven instance / class behavior
+* State values of any data type
+* Dynamically-generated state values
+* Event parallelization
+* Attribute-based event transitions
+* Inheritance
+* Internationalization
+* GraphViz visualization creator
+
+Examples of the usage patterns for some of the above features are shown below.
+You can find much more detailed documentation in the actual API.
+
+== Usage
+
+=== Example
+
+Below is an example of many of the features offered by this plugin, including:
+* Initial states
+* Namespaced states
+* Transition callbacks
+* Conditional transitions
+* State-driven instance behavior
+* Customized state values
+* Parallel events
+
+Class definition:
+
+  class Vehicle
+    attr_accessor :seatbelt_on
+    
+    state_machine :state, :initial => :parked do
+      before_transition :parked => any - :parked, :do => :put_on_seatbelt
+      
+      after_transition :on => :crash, :do => :tow
+      after_transition :on => :repair, :do => :fix
+      after_transition any => :parked do |vehicle, transition|
+        vehicle.seatbelt_on = false
+      end
+      
+      event :park do
+        transition [:idling, :first_gear] => :parked
+      end
+      
+      event :ignite do
+        transition :stalled => same, :parked => :idling
+      end
+      
+      event :idle do
+        transition :first_gear => :idling
+      end
+      
+      event :shift_up do
+        transition :idling => :first_gear, :first_gear => :second_gear, :second_gear => :third_gear
+      end
+      
+      event :shift_down do
+        transition :third_gear => :second_gear, :second_gear => :first_gear
+      end
+      
+      event :crash do
+        transition all - [:parked, :stalled] => :stalled, :unless => :auto_shop_busy?
+      end
+      
+      event :repair do
+        transition :stalled => :parked, :if => :auto_shop_busy?
+      end
+      
+      state :parked do
+        def speed
+          0
+        end
+      end
+      
+      state :idling, :first_gear do
+        def speed
+          10
+        end
+      end
+      
+      state :second_gear do
+        def speed
+          20
+        end
+      end
+    end
+    
+    state_machine :alarm_state, :initial => :active, :namespace => 'alarm' do
+      event :enable do
+        transition all => :active
+      end
+      
+      event :disable do
+        transition all => :off
+      end
+      
+      state :active, :value => 1
+      state :off, :value => 0
+    end
+    
+    def initialize
+      @seatbelt_on = false
+      super() # NOTE: This *must* be called, otherwise states won't get initialized
+    end
+    
+    def put_on_seatbelt
+      @seatbelt_on = true
+    end
+    
+    def auto_shop_busy?
+      false
+    end
+    
+    def tow
+      # tow the vehicle
+    end
+    
+    def fix
+      # get the vehicle fixed by a mechanic
+    end
+  end
+
+*Note* the comment made on the +initialize+ method in the class.  In order for
+state machine attributes to be properly initialized, <tt>super()</tt> must be called.
+See StateMachine::MacroMethods for more information about this.
+
+Using the above class as an example, you can interact with the state machine
+like so:
+
+  vehicle = Vehicle.new           # => #<Vehicle:0xb7cf4eac @state="parked", @seatbelt_on=false>
+  vehicle.state                   # => "parked"
+  vehicle.state_name              # => :parked
+  vehicle.parked?                 # => true
+  vehicle.can_ignite?             # => true
+  vehicle.ignite_transition       # => #<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>
+  vehicle.state_events            # => [:ignite]
+  vehicle.state_transitions       # => [#<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
+  vehicle.speed                   # => 0
+  
+  vehicle.ignite                  # => true
+  vehicle.parked?                 # => false
+  vehicle.idling?                 # => true
+  vehicle.speed                   # => 10
+  vehicle                         # => #<Vehicle:0xb7cf4eac @state="idling", @seatbelt_on=true>
+  
+  vehicle.shift_up                # => true
+  vehicle.speed                   # => 10
+  vehicle                         # => #<Vehicle:0xb7cf4eac @state="first_gear", @seatbelt_on=true>
+  
+  vehicle.shift_up                # => true
+  vehicle.speed                   # => 20
+  vehicle                         # => #<Vehicle:0xb7cf4eac @state="second_gear", @seatbelt_on=true>
+  
+  # The bang (!) operator can raise exceptions if the event fails
+  vehicle.park!                   # => StateMachine::InvalidTransition: Cannot transition state via :park from :second_gear
+  
+  # Generic state predicates can raise exceptions if the value does not exist
+  vehicle.state?(:parked)         # => false
+  vehicle.state?(:invalid)        # => IndexError: :invalid is an invalid name
+  
+  # Namespaced machines have uniquely-generated methods
+  vehicle.alarm_state             # => 1
+  vehicle.alarm_state_name        # => :active
+  
+  vehicle.can_disable_alarm?      # => true
+  vehicle.disable_alarm           # => true
+  vehicle.alarm_state             # => 0
+  vehicle.alarm_state_name        # => :off
+  vehicle.can_enable_alarm?       # => true
+  
+  vehicle.alarm_off?              # => true
+  vehicle.alarm_active?           # => false
+  
+  # Events can be fired in parallel
+  vehicle.fire_events(:shift_down, :enable_alarm) # => true
+  vehicle.state_name                              # => :first_gear
+  vehicle.alarm_state_name                        # => :active
+  
+  vehicle.fire_events!(:ignite, :enable_alarm)    # => StateMachine::InvalidTransition: Cannot run events in parallel: ignite, enable_alarm
+
+== Integrations
+
+In addition to being able to define state machines on all Ruby classes, a set of
+out-of-the-box integrations are available for some of the more popular Ruby
+libraries.  These integrations add library-specific behavior, allowing for state
+machines to work more tightly with the conventions defined by those libraries.
+
+The integrations currently available include:
+* ActiveRecord models
+* DataMapper resources
+* Sequel models
+
+A brief overview of these integrations is described below.
+
+=== ActiveRecord
+
+The ActiveRecord integration adds support for database transactions, automatically
+saving the record, named scopes, validation errors, and observers.  For example,
+
+  class Vehicle < ActiveRecord::Base
+    state_machine :initial => :parked do
+      before_transition :parked => any - :parked, :do => :put_on_seatbelt
+      after_transition any => :parked do |vehicle, transition|
+        vehicle.seatbelt = 'off'
+      end
+      
+      event :ignite do
+        transition :parked => :idling
+      end
+      
+      state :first_gear, :second_gear do
+        validates_presence_of :seatbelt_on
+      end
+    end
+    
+    def put_on_seatbelt
+      ...
+    end
+  end
+  
+  class VehicleObserver < ActiveRecord::Observer
+    # Callback for :ignite event *before* the transition is performed
+    def before_ignite(vehicle, transition)
+      # log message
+    end
+    
+    # Generic transition callback *after* the transition is performed
+    def after_transition(vehicle, transition)
+      Audit.log(vehicle, transition)
+    end
+  end
+
+For more information about the various behaviors added for ActiveRecord state
+machines, see StateMachine::Integrations::ActiveRecord.
+
+=== DataMapper
+
+Like the ActiveRecord integration, the DataMapper integration adds support for
+database transactions, automatically saving the record, named scopes, Extlib-like
+callbacks, validation errors, and observers.  For example,
+
+  class Vehicle
+    include DataMapper::Resource
+    
+    property :id, Serial
+    property :state, String
+    
+    state_machine :initial => :parked do
+      before_transition :parked => any - :parked, :do => :put_on_seatbelt
+      after_transition any => :parked do |transition|
+        self.seatbelt = 'off' # self is the record
+      end
+      
+      event :ignite do
+        transition :parked => :idling
+      end
+      
+      state :first_gear, :second_gear do
+        validates_present :seatbelt_on
+      end
+    end
+    
+    def put_on_seatbelt
+      ...
+    end
+  end
+  
+  class VehicleObserver
+    include DataMapper::Observer
+    
+    observe Vehicle
+    
+    # Callback for :ignite event *before* the transition is performed
+    before_transition :on => :ignite do |transition|
+      # log message (self is the record)
+    end
+    
+    # Generic transition callback *after* the transition is performed
+    after_transition do |transition|
+      Audit.log(self, transition) # self is the record
+    end
+  end
+
+*Note* that the DataMapper::Observer integration is optional and only available
+when the dm-observer library is installed.
+
+For more information about the various behaviors added for DataMapper state
+machines, see StateMachine::Integrations::DataMapper.
+
+=== Sequel
+
+Like the ActiveRecord integration, the Sequel integration adds support for
+database transactions, automatically saving the record, named scopes, validation
+errors and callbacks.  For example,
+
+  class Vehicle < Sequel::Model
+    state_machine :initial => :parked do
+      before_transition :parked => any - :parked, :do => :put_on_seatbelt
+      after_transition any => :parked do |transition|
+        self.seatbelt = 'off' # self is the record
+      end
+      
+      event :ignite do
+        transition :parked => :idling
+      end
+      
+      state :first_gear, :second_gear do
+        validates_presence_of :seatbelt_on
+      end
+    end
+    
+    def put_on_seatbelt
+      ...
+    end
+  end
+
+For more information about the various behaviors added for Sequel state
+machines, see StateMachine::Integrations::Sequel.
+
+== Compatibility
+
+Although state_machine introduces a simplified syntax, it still remains
+backwards compatible with previous versions and other state-related libraries.
+For example, transitions and callbacks can continue to be defined like so:
+
+  class Vehicle
+    state_machine :initial => :parked do
+      before_transition :from => :parked, :except_to => :parked, :do => :put_on_seatbelt
+      after_transition :to => :parked do |transition|
+        self.seatbelt = 'off' # self is the record
+      end
+      
+      event :ignite do
+        transition :from => :parked, :to => :idling
+      end
+    end
+  end
+
+Although this verbose syntax will most likely always be supported, it is
+recommended that any state machines eventually migrate to the syntax introduced
+in version 0.6.0.
+
+== Tools
+
+=== Generating graphs
+
+This library comes with built-in support for generating di-graphs based on the
+events, states, and transitions defined for a state machine using GraphViz[http://www.graphviz.org].
+This requires that both the <tt>ruby-graphviz</tt> gem and graphviz library be
+installed on the system.
+
+==== Examples
+
+To generate a graph for a specific file / class:
+
+  rake state_machine:draw FILE=vehicle.rb CLASS=Vehicle
+
+To save files to a specific path:
+
+  rake state_machine:draw FILE=vehicle.rb CLASS=Vehicle TARGET=files
+
+To customize the image format / orientation:
+
+  rake state_machine:draw FILE=vehicle.rb CLASS=Vehicle FORMAT=jpg ORIENTATION=landscape
+
+To generate multiple state machine graphs:
+
+  rake state_machine:draw FILE=vehicle.rb,car.rb CLASS=Vehicle,Car
+
+*Note* that this will generate a different file for every state machine defined
+in the class.  The generated files will use an output filename of the format
+#{class_name}_#{machine_name}.#{format}.
+
+For examples of actual images generated using this task, see those under the
+examples folder.
+
+==== Ruby on Rails Integration
+
+There is a special integration Rake task for generating state machines for
+classes used in a Ruby on Rails application.  This task will load the application
+environment, meaning that it's unnecessary to specify the actual file to load.
+
+For example,
+
+  rake state_machine:draw:rails CLASS=Vehicle
+
+==== Merb Integration
+
+Like Ruby on Rails, there is a special integration Rake task for generating
+state machines for classes used in a Merb application.  This task will load the
+application environment, meaning that it's unnecessary to specify the actual
+files to load.
+
+For example,
+
+  rake state_machine:draw:merb CLASS=Vehicle
+
+=== Interactive graphs
+
+Jean Bovet - {Visual Automata Simulator}[http://www.cs.usfca.edu/~jbovet/vas.html].
+This is a great tool for "simulating, visualizing and transforming finite state
+automata and Turing Machines".  This tool can help in the creation of states and
+events for your models.  It is cross-platform, written in Java.
+
+== Testing
+
+To run the entire test suite (will test ActiveRecord, DataMapper, and Sequel
+integrations if the proper dependencies are available):
+
+  rake test
+
+Target specific versions of integrations like so:
+
+  rake test AR_VERSION=2.0.0 DM_VERSION=0.9.4 SEQUEL_VERSION=2.8.0
+
+== Dependencies
+
+By default, there are no dependencies.  If using specific integrations, those
+dependencies are listed below.
+
+* ActiveRecord[http://rubyonrails.org] integration: 2.0.0 or later
+* DataMapper[http://datamapper.org] integration: 0.9.4 or later
+* Sequel[http://sequel.rubyforge.org] integration: 2.8.0 or later

data/lib/branston/vendor/plugins/state_machine/Rakefile

@@ -0,0 +1,98 @@
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rake/contrib/sshpublisher'
+
+spec = Gem::Specification.new do |s|
+  s.name              = 'state_machine'
+  s.version           = '0.8.0'
+  s.platform          = Gem::Platform::RUBY
+  s.summary           = 'Adds support for creating state machines for attributes on any Ruby class'
+  s.description       = s.summary
+  
+  s.files             = FileList['{examples,lib,tasks,test}/**/*'] + %w(CHANGELOG.rdoc init.rb LICENSE Rakefile README.rdoc) - FileList['test/*.log']
+  s.require_path      = 'lib'
+  s.has_rdoc          = true
+  s.test_files        = Dir['test/**/*_test.rb']
+  
+  s.author            = 'Aaron Pfeifer'
+  s.email             = 'aaron@pluginaweek.org'
+  s.homepage          = 'http://www.pluginaweek.org'
+  s.rubyforge_project = 'pluginaweek'
+end
+
+desc 'Default: run all tests.'
+task :default => :test
+
+desc "Test the #{spec.name} plugin."
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.test_files = spec.test_files
+  t.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  namespace :test do
+    desc "Test the #{spec.name} plugin with Rcov."
+    Rcov::RcovTask.new(:rcov) do |t|
+      t.libs << 'lib'
+      t.test_files = spec.test_files
+      t.rcov_opts << '--exclude="^(?!lib/)"'
+      t.verbose = true
+    end
+  end
+rescue LoadError
+end
+
+desc "Generate documentation for the #{spec.name} plugin."
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = spec.name
+  rdoc.template = '../rdoc_template.rb'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc', 'CHANGELOG.rdoc', 'LICENSE', 'lib/**/*.rb')
+end
+
+desc 'Generate a gemspec file.'
+task :gemspec do
+  File.open("#{spec.name}.gemspec", 'w') do |f|
+    f.write spec.to_ruby
+  end
+end
+
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+  p.need_tar = true
+  p.need_zip = true
+end
+
+desc 'Publish the beta gem.'
+task :pgem => [:package] do
+  Rake::SshFilePublisher.new('aaron@pluginaweek.org', '/home/aaron/gems.pluginaweek.org/public/gems', 'pkg', "#{spec.name}-#{spec.version}.gem").upload
+end
+
+desc 'Publish the API documentation.'
+task :pdoc => [:rdoc] do
+  Rake::SshDirPublisher.new('aaron@pluginaweek.org', "/home/aaron/api.pluginaweek.org/public/#{spec.name}", 'rdoc').upload
+end
+
+desc 'Publish the API docs and gem'
+task :publish => [:pgem, :pdoc, :release]
+
+desc 'Publish the release files to RubyForge.'
+task :release => [:gem, :package] do
+  require 'rubyforge'
+  
+  ruby_forge = RubyForge.new.configure
+  ruby_forge.login
+  
+  %w(gem tgz zip).each do |ext|
+    file = "pkg/#{spec.name}-#{spec.version}.#{ext}"
+    puts "Releasing #{File.basename(file)}..."
+    
+    ruby_forge.add_release(spec.rubyforge_project, spec.name, spec.version, file)
+  end
+end
+
+Dir['tasks/**/*.rake'].each {|rake| load rake}

data/lib/branston/vendor/plugins/state_machine/examples/auto_shop.rb

@@ -0,0 +1,11 @@
+class AutoShop
+  state_machine :initial => :available do
+    event :tow_vehicle do
+      transition :available => :busy
+    end
+    
+    event :fix_vehicle do
+      transition :busy => :available 
+    end
+  end
+end

data/lib/branston/vendor/plugins/state_machine/examples/car.rb

@@ -0,0 +1,19 @@
+class Car < Vehicle
+  state_machine do
+    event :reverse do
+      transition [:parked, :idling, :first_gear] => :backing_up
+    end
+    
+    event :park do
+      transition :backing_up => :parked
+    end
+    
+    event :idle do
+      transition :backing_up => :idling
+    end
+    
+    event :shift_up do
+      transition :backing_up => :first_gear
+    end
+  end
+end

data/lib/branston/vendor/plugins/state_machine/examples/merb-rest/controller.rb

@@ -0,0 +1,51 @@
+class Users < Application
+  # GET /users
+  def index
+    @users = User.all
+    display @users
+  end
+  
+  # GET /users/1
+  def show(id)
+    @user = User.get(id)
+    raise NotFound unless @user
+    display @user
+  end
+  
+  # GET /users/new
+  def new
+    only_provides :html
+    @user = User.new
+    display @user
+  end
+  
+  # GET /users/1/edit
+  def edit(id)
+    only_provides :html
+    @user = User.get(id)
+    raise NotFound unless @user
+    display @user
+  end
+  
+  # POST /users
+  def create(user)
+    @user = User.new(user)
+    if @user.save
+      redirect resource(@user), :message => {:notice => "User was successfully created"}
+    else
+      message[:error] = "User failed to be created"
+      render :new
+    end
+  end
+  
+  # PUT /users/1
+  def update(id, user)
+    @user = User.get(id)
+    raise NotFound unless @user
+    if @user.update_attributes(user)
+       redirect resource(@user)
+    else
+      display @user, :edit
+    end
+  end
+end

data/lib/branston/vendor/plugins/state_machine/examples/merb-rest/model.rb

@@ -0,0 +1,28 @@
+class User
+  include DataMapper::Resource
+  
+  property :id, Serial
+  property :name, String
+  
+  validates_present :name, :state, :access_state
+  
+  state_machine :initial => :unregistered do
+    event :register do
+      transition :unregistered => :registered
+    end
+    
+    event :unregister do
+      transition :registered => :unregistered
+    end
+  end
+  
+  state_machine :access_state, :initial => :enabled do
+    event :enable do
+      transition all => :enabled
+    end
+    
+    event :disable do
+      transition all => :disabled
+    end
+  end
+end