Adding files

History.txt

@@ -0,0 +1,4 @@
+== 0.0.1 2008-11-05
+
+* 1 major enhancement:
+  * Initial release

Manifest.txt

@@ -0,0 +1,18 @@
+History.txt
+Manifest.txt
+PostInstall.txt
+README.rdoc
+Rakefile
+TODO
+assertions.rb
+assertions_spec.rb
+lib/alter_ego.rb
+script/console
+script/destroy
+script/generate
+spec/spec.opts
+spec/spec_helper.rb
+spec/alter_ego_spec.rb
+alter_ego.rb
+alter_ego_spec.rb
+tasks/rspec.rake

PostInstall.txt

@@ -0,0 +1,7 @@
+
+For more information on states, see http://alter-ego.rubyforge.org
+
+NOTE: Change this information in PostInstall.txt 
+You can also delete it if you don't want it.
+
+

README.rdoc

@@ -0,0 +1,149 @@
+= states
+
+* FIX (url)
+
+== DESCRIPTION:
+
+AlterEgo is a Ruby implementation of the State pattern as described by the Gang
+of Four.  It differs from other Ruby state machine libraries in that it focuses
+on providing polymorphic behavior based on object state.  In effect, it makes it
+easy to give an object different personalities depending on the state it is in.
+
+== SYNOPSIS:
+
+  class TrafficLight
+    include AlterEgo
+
+    state :proceed, :default => true do
+      handle :color do
+	"green"
+      end
+      transition :to => :caution, :on => :cycle!
+    end
+
+    state :caution do
+      handle :color do
+	"yellow"
+      end
+      transition :to => :stop, :on => :cycle!
+    end
+
+    state :stop do
+      handle :color do
+	"red"
+      end 
+      transition :to => :proceed, :on => :cycle!
+    end
+  end
+
+  light = TrafficLight.new
+  light.color                     # => "green"
+  light.cycle!
+  light.color                     # => "yellow"
+  light.cycle!
+  light.color                     # => "red"
+  light.cycle!
+  light.color                     # => "green"
+
+
+== FEATURES:
+
+* Implemented as a module which can be included in any Ruby class.
+* Fully tested with literate RSpec
+* Guard clauses may be defined for each transition.
+* Enter/exit actions may be defined for each state.
+* For more advanced scenarios, arbitrary "request filters" may be
+  defined with full control over which requests are filtered.
+* Uses dynamic module generation and delegation instead of method
+  rewriting.
+* Pervasive contract-checking catches mistakes in library usage
+  early.
+* Storing and reading current state is completely customizable,
+  making it easier to add AlterEgo to legacy classes.
+
+== DETAILS:
+
+AlterEgo differs from other Finite State Machine implementations in
+Ruby in that where other libraries focus on describing a set of
+valid state transitions, AlterEgo focuses on varying _behavior_ based
+on state.  In other words, it provides state-based polymorphism.
+
+AlterEgo draws heavily on the State Pattern as published in the book
+Design Patterns[1].  A summary of the pattern can be
+found on Wikipedia[http://en.wikipedia.org/wiki/State_pattern].
+Because AlterEgo uses the terminology set forth in the State Pattern,
+it is useful to have some familiarity with the pattern in order to
+understand the library.
+
+link://State_Design_Pattern_UML_Class_Diagram.png
+
+In the State Pattern, states of an object are represented as
+discrete objects.  At any given time an object with state-based
+behavior has-a state object.  The object with state-based behavior
+delegates certain method calls to its current state.  In this way,
+the implementation of those methods can vary with the state of the
+object.  Or in certain states some methods may not be supported at
+all.
+
+The AlterEgo library provides both an object model for manually
+setting up explicit state classes, and a concise DSL built on top
+of that model which simplifies building classes with state-based
+behavior.
+
+This file only scratches the surface of AlterEgo
+functionality.  For complete tutorial documentation, see the file
+spec/states_spec.rb.  It contains the annotated specification,
+written in the style of a step-by-step tutorial.
+
+=== Terminology:
+
+[Context] The *context* is the class which should have state-based
+          behavior.  In the example above, the +TrafficLight+ class
+          is the context.
+[State] Each *state* the *context* might exist in is represented by a
+        class,  In the example given above, the available states
+        are +caution+, +stop+, and +proceed+.
+[Request] A *request* refers to a message (method) sent to the
+          *context*.  In the example given above, the supported
+          requests are +color+ and +cycle+.
+[Handler] A *handler* is a method on a *state* which implements a
+          *request* for that state.  For instance, in the example
+          above, when the +TrafficLight+ is in the +caution+ state,
+          the handler for the request +color+ returns "yellow".
+
+=== Footnotes:
+
+1. Gamma, Erich; Richard Helm, Ralph Johnson, John M. Vlissides (1995). Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley, 395. ISBN 0201633612.
+
+== REQUIREMENTS:
+
+* ActiveSupport
+
+== INSTALL:
+
+* sudo gem install states
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Avdi Grimm
+
+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.

Rakefile

@@ -0,0 +1,32 @@
+%w[rubygems rake rake/clean fileutils newgem rubigen].each { |f| require f }
+require File.dirname(__FILE__) + '/lib/alter_ego'
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new('alter-ego', AlterEgo::VERSION) do |p|
+  p.developer('Avdi Grimm', 'avdi@avdi.org')
+  p.changes              = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  p.post_install_message = 'PostInstall.txt' # TODO remove if post-install message not required
+  p.rubyforge_name       = p.name # TODO this is default value
+  # p.extra_deps         = [
+  #   ['activesupport','>= 2.0.2'],
+  # ]
+  p.extra_dev_deps = [
+    ['newgem', ">= #{::Newgem::VERSION}"]
+  ]
+
+  p.clean_globs |= %w[**/.DS_Store tmp *.log]
+  path = (p.rubyforge_name == p.name) ? p.rubyforge_name : "\#{p.rubyforge_name}/\#{p.name}"
+  p.remote_rdoc_dir = File.join(path.gsub(/^#{p.rubyforge_name}\/?/,''), 'rdoc')
+  p.rsync_args = '-av --delete --ignore-errors'
+end
+
+require 'newgem/tasks' # load /tasks/*.rake
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+# TODO - want other tests/tasks run by default? Add them to the list
+# task :default => [:spec, :features]
+
+task :docs do |task|
+  cp "State_Design_Pattern_UML_Class_Diagram.png", "doc"
+end

TODO

@@ -0,0 +1,10 @@
+* TODO Factor assertions out into separate library
+* TODO Remove ActiveSupport dependency
+* TODO Nested state support with history
+* TODO Verify full methods/respond_to? integration
+* TODO Composite state support
+  E.g. a Traffic Light could have both green/yellow/red state and "in
+  service"/out of service" state at the same time
+* TODO More natural/Rubyish DSL
+  It would be good to have plain-old "def" work as expected inside of "state"
+  blocks instead of requiring "handle".

config/website.yml

@@ -0,0 +1,2 @@
+host: avdi@rubyforge.org
+remote_dir: /var/www/gforge-projects/alter-ego