Skip to content
Browse files

markdown

  • Loading branch information...
1 parent 645264c commit d9df433d9263683c5fd737f3398f11155c71c3cc @banister committed Dec 13, 2008
Showing with 0 additions and 154 deletions.
  1. +0 −154 README
View
154 README
@@ -1,154 +0,0 @@
-Clean and fast Object state transitions in Ruby using the Mixology C extension.
-
-Supports:
-* Dynamic switching between states (mixing and unmixing modules)
-* Clean DSL-style syntax
-* Optional state_entry() and state_exit() hooks for each state (automatically called upon state entry and exit)
-* support for subclassing of classes that include Stateology (see below)
-* support for nested states, i.e states defined within other states
-
-Use as in the following:
-
-class Sample
- include Stateology
-
- state(:Happy) {
- def state_entry
- puts "entering Happy state"
- end
-
- def do_something
- puts "Pets a puppy"
- end
-
- def state_exit
- puts "exiting Happy state"
- end
- }
-
- state(:Angry) {
- def state_entry
- puts "entering Angry state"
- end
-
- def do_something
- puts "Kicks a puppy"
- end
-
- def state_exit
- puts "exiting Angry state"
- end
- }
-
- # methods declared outside a 'state' are not part of any state
-
- def state_entry
- puts "entering Default state"
- end
-
- def do_something
- puts "stares at the ceiling"
- end
-
- def state_exit
- puts "exiting Default state"
- end
-
- # if we want the state_entry to run on instantiation
- # we must call it from the initialize method
- def initialize
- state_entry
- end
-
-end
-
-s = Sample.new
-
-# in no state
-s.do_something #=> "stares at the ceiling"
-
-# now switch to Happy state
-s.state :Happy
-s.do_something #=> "Pets a puppy"
-
-# now switch to Angry state
-s.state :Angry
-s.do_something #=> "Kicks a puppy"
-
-# now switch back to no state
-s.state nil
-s.do_something #=> "stares at the ceiling"
-
-UPDATE:
-* made it so subclasses can inherit states from their superclasses e.g
-class A
- include Stateology
-
- state(:Happy) {
- def state_entry
- puts "entering Happy state"
- end
-
- def hello
- puts "hello from A"
- end
- }
-end
-
-class B < A
- state(:Happy) {
- def hello
- puts "hello from B"
- end
- }
-end
-
-b = B.new
-
-b.state :Happy
-#=> "entering Happy state"
-
-b.hello
-#=> "hello from B"
-
-* prior behaviour was for state_entry not to exist in class B as Happy module from class A was overwritten by the new Happy module in B
-* how does this fix work? the Happy module in B just includes any extant Happy module accessible in B
-
-
-
-
----=A FEW THINGS TO NOTE=---
-
-* When an object is instantiated it begins life in no state and only ordinary instance methods are accessible (The ordinary instance methods are those defined outside of any state() {} block)
-
-* The ordinary instance methods are available to any state so long as they are not overridden by the state.
-
-* To change from any given state to 'no state' pass nil as a parameter to the state method
-e.g s.state nil
-
-* 'no state', while not a state, may nonetheless have state_entry() and state_exit() methods; and these methods will be invoked on 'entry' and exit from 'no state'
-
-* The state_entry method for 'no state' is not automatically called on object instantiation. If you wish state_entry to run when the object is instantiated invoke it in the initialize() method.
-
-* The state_entry method can also accept parameters:
-e.g s.state :Happy, "hello"
-In the above the string "hello" is passed as a parameter to the state_entry() method of the Happy state.
-
-* The #state method can accept either a Symbol (e.g :Happy) or a Module (e.g Happy or Sample::Happy). The following are equivalent:
-s.state :Happy #=> change state to Happy
-
-* The #state method can take a block; the block will be executed after the successful change of state:
-e.g s.state(:Happy) { s.hello } #=> hello method invoked immediately after change of state as it's in the block
-
-s.state Sample::Happy #=> equivalent to above (note the fully qualified name; as Happy is a module defined under the Sample class)
-
-* alternatively; if the #state method is invoked internally by another instance method of the Sample class then a fully qualified module name is not required:
-state Happy #=> Fully qualified module name not required when #state invoked in an instance method
-
-* The #state method can also act as a 'getter' method when invoked with no parameters. It will return the current state name in Symbol form (e.g :Happy)
-
-* The #state_mod method works similarly to the #state 'getter' except it returns the Module representing the current state (e.g Sample::Happy)
-
-* The #state?(state_name) returns boolean true if the current state is equal to state_name, and false if not. state_name can be either a Module or a Symbol
-
-

0 comments on commit d9df433

Please sign in to comment.
Something went wrong with that request. Please try again.