allow hooks to be specified during initial construction (instead of tacking them onto the object afterwards) and renamed 'hook' to 'callback' throughout

Author: jakesgordon

README.md

@@ -6,27 +6,6 @@ want to start fading during an `onleavestate` handler, but not trigger the next
 
 Something like
 
-    var fsm = StateMachine.create({
-      initial: 'green',
-      events: [
-        { name: 'play', from: 'menu', to: 'game', async: true },
-        { name: 'lose', from: 'game', to: 'menu'              },
-    ]});
-
-    fsm.onleavemenu = function() {
-      $('menu').fade(function() {
-        fsm.transition();
-      });
-    }
-
-    fsm.onentergame = function() {
-      // this doesn't get called until fsm.transition() is called when the menu has finished fading
-    }
-
-    fsm.play();
-
-Also possible to simply return false from onleavestate hook instead of having to declare event as async:
-
     var fsm = StateMachine.create({
       initial: 'green',
       events: [
@@ -49,7 +28,7 @@ Also possible to simply return false from onleavestate hook instead of having to
 
 Or.... something else ! Have to wait and see how it pans out (without breaking existing synchronous behavior)
 
-Javascript Finite State Machine (v1.3.0)
+Javascript Finite State Machine (v2.0.0)
 ========================================
 
 This standalone javascript micro-framework provides a finite state machine for your pleasure.
@@ -105,24 +84,73 @@ along with the following members:
  * fsm.can(e)    - return true if event `e` can be fired in the current state
  * fsm.cannot(e) - return true if event `e` cannot be fired in the current state
 
-Hooks
-=====
+Multiple 'from' and 'to' states for a single event
+==================================================
+
+If an event is allowed **from** multiple states, and always transitions **to** the same
+state, then simply provide an array of states in the `from` attribute of an event.
+
+If an event is allowed **from** multiple states, but should transition **to** a different
+state depending on the current state, then provide multiple event entries with
+the same name:
+
+    var fsm = StateMachine.create({
+      initial: 'hungry',
+      events: [
+        { name: 'eat',  from: 'hungry',                                to: 'satisfied' },
+        { name: 'eat',  from: 'satisfied',                             to: 'full'      },
+        { name: 'eat',  from: 'full',                                  to: 'sick'      },
+        { name: 'rest', from: ['hungry', 'satisfied', 'full', 'sick'], to: 'hungry'    },
+    ]});
+
+This example will create an object with 2 event methods:
+
+ * fsm.eat()
+ * fsm.rest()
 
->> _NOTE: I'm using the word 'hook' to avoid overloading the word 'event'._
+The `rest` event will always transition to the `hungry` state, while the `eat` event
+will transition to a state that is dependent on the current state.
 
-4 hooks are available if your object has methods using the following naming conventions:
+>> NOTE: The `rest` event in the above example can also be specified as multiple events with
+the same name if you prefer the verbose approach:
+
+    var fsm = StateMachine.create({
+      initial: 'hungry',
+      events: [
+        { name: 'eat',  from: 'hungry',    to: 'satisfied' },
+        { name: 'eat',  from: 'satisfied', to: 'full'      },
+        { name: 'eat',  from: 'full',      to: 'sick'      },
+        { name: 'rest', from: 'hungry',    to: 'hungry'    }, // NOTE: this is a no-op.
+        { name: 'rest', from: 'satisfied', to: 'hungry'    },
+        { name: 'rest', from: 'full',      to: 'hungry'    },
+        { name: 'rest', from: 'sick',      to: 'hungry'    },
+    ]});
+
+Callbacks
+=========
+
+4 callbacks are available if your state machine has methods using the following naming conventions:
 
  * onbefore**event** - fired before an event
  * onafter**event**  - fired after an event
  * onenter**state**  - fired when entering a state
  * onleave**state**  - fired when leaving a state
 
-For convenience, the 2 most useful hooks can be shortened:
+For convenience, the 2 most useful callbacks can be shortened:
 
  * on**event** - convenience shorthand for onafter**event**
  * on**state** - convenience shorthand for onenter**state**
 
-Hooks can be added after the FSM is created:
+In addition, a generic `onchangestate()` callback can be used to call a single function for _all_ state changes:
+
+All callbacks will be passed the same arguments:
+
+ * event name
+ * from state
+ * to state
+ * _(followed by any arguments you passed into the original event method)_
+
+Callbacks can be specified when the state machine is first created:
 
     var fsm = StateMachine.create({
       initial: 'green',
@@ -131,77 +159,48 @@ Hooks can be added after the FSM is created:
         { name: 'panic', from: 'yellow', to: 'red'    },
         { name: 'calm',  from: 'red',    to: 'yellow' },
         { name: 'clear', from: 'yellow', to: 'green'  }
-    ]});
-
-    fsm.onpanic  = function() { alert('panic!'); };
-    fsm.onclear  = function() { alert('all clear!'); };
-    fsm.ongreen  = function() { document.body.className = 'green';  };
-    fsm.onyellow = function() { document.body.className = 'yellow'; };
-    fsm.onred    = function() { document.body.className = 'red';    };
+      ],
+      callbacks: {
+        onpanic:  function(event, from, to) { alert('panic!');                    },
+        onclear:  function(event, from, to) { alert('all clear!');                },
+        ongreen:  function(event, from, to) { document.body.className = 'green';  },
+        onyellow: function(event, from, to) { document.body.className = 'yellow'; },
+        onred:    function(event, from, to) { document.body.className = 'red';    },
+      }
+    });
 
     fsm.panic()
     fsm.clear()
     ...
 
-*NEW in v1.3.0* is a generic `onchangestate(from,to)` hook was added to allow a single function
-to be called on all state changes:
-
-    fsm.onchangestate = function(from, to) { document.body.className = to; };
-
-
-Multiple 'from' states for a single event
-=========================================
+Additionally, they can be added and removed from the state machine at any time:
 
-If an event is allowed **from** multiple states, and always transitions **to** the same
-state, then simply provide an array of states in the `from` attribute of an event:
+    fsm.ongreen       = null;
+    fsm.onyellow      = null;
+    fsm.onred         = null;
+    fsm.onchangestate = function(event, from, to) { document.body.className = to; };
 
-    var fsm = StateMachine.create({
-      initial: 'green',
-      events: [
-        { name: 'warn',  from: ['green'],           to: 'yellow' },
-        { name: 'panic', from: ['green', 'yellow'], to: 'red'    },
-        { name: 'calm',  from: ['red'],             to: 'yellow' },
-        { name: 'clear', from: ['red', 'yellow'],   to: 'green'  }
-    ]});
-
-Multiple 'to' states for a single event
-=======================================
-
-If an event is allowed **from** multiple states, but should transition **to** a different
-state depending on the current state, then provide multiple event entries with
-the same name:
-
-    var fsm = StateMachine.create({
-      initial: 'hungry',
-      events: [
-        { name: 'eat',  from: 'hungry',                                to: 'satisfied' },
-        { name: 'eat',  from: 'satisfied',                             to: 'full'      },
-        { name: 'eat',  from: 'full',                                  to: 'sick'      },
-        { name: 'rest', from: ['hungry', 'satisfied', 'full', 'sick'], to: 'hungry'    },
-    ]});
-
-This example will create an object with 2 event methods:
-
- * fsm.eat()
- * fsm.rest()
+Asynchronous State Transitions
+==============================
 
-The `rest` event will always transition to the `hungry` state, while the `eat` event will transition to a state that is dependent on the current state.
+ * **TODO**
 
 State Machine Classes
 =====================
 
 You can also turn all instances of a  _class_ into an FSM by applying
-the state machine functionality to the prototype object and providing
-a `startup` event for use when constructing instances:
+the state machine functionality to the prototype, including your callbacks
+in your prototype, and providing a `startup` event for use when constructing
+instances:
 
     MyFSM = function() {         // my constructor function
       this.startup();
     };
 
     MyFSM.prototype = {
 
-      onpanic: function() { alert('panic'); },
-      onclear: function() { alert('all is clear'); },
+      onpanic: function(event, from, to) { alert('panic');        },
+      onclear: function(event, from, to) { alert('all is clear'); },
 
       // other prototype methods
 
@@ -250,7 +249,7 @@ implicit `startup` event will be created for you and fired when the state machin
     ]});
     alert(fsm.current); // "green"
 
-If your object already has a `startup` method you can change the name of the initial event
+If your object already has a `startup` method you can use a different name for the initial event
 
     var fsm = StateMachine.create({
       initial: { state: 'green', event: 'init' },

RELEASE_NOTES.md

@@ -1,8 +1,10 @@
 
 Version 2.0.0 (unreleased)
 --------------------------
+
+ * consistent arguments for ALL callbacks, first 3 args are ALWAYS event name, from state and to state, followed by whatever arguments the user passed to the original event method.
  * adding support for `async` event transitions (see README)
- * added a generic `onchangestate(from,to)` hook to detect all state changes with a single callback.
+ * added a generic `onchangestate(event,from,to)` callback to detect all state changes with a single function
 
 Version 1.2.0 (June 21st 2011)
 ------------------------------

demo/demo.js

@@ -1,71 +1,78 @@
-Demo = {
+Demo = function() {
 
-  run: function() {
-    StateMachine.create({
-      target: this,
-      initial: 'green',
-      events: [
-        { name: 'warn',  from: ['green'],           to: 'yellow' },
-        { name: 'panic', from: ['green', 'yellow'], to: 'red'    },
-        { name: 'calm',  from: ['red'],             to: 'yellow' },
-        { name: 'clear', from: ['red',   'yellow'], to: 'green'  },
-    ]});
-  },
+  var output = document.getElementById('output'),
+      demo   = document.getElementById('demo'),
+      panic  = document.getElementById('panic'),
+      warn   = document.getElementById('warn'),
+      calm   = document.getElementById('calm'),
+      clear  = document.getElementById('clear'),
+      count  = 0;
 
-  onbeforestartup: function(event, from, to) { this.log("STARTING UP"); },
-  onafterstartup:  function(event, from, to) { this.log("READY");       },
+  var log = function(msg, separate) {
+    count = count + (separate ? 1 : 0);
+    output.value = count + ": " + msg + "\n" + (separate ? "\n" : "") + output.value;
+    demo.className = fsm.current;
+    panic.disabled = fsm.cannot('panic');
+    warn.disabled  = fsm.cannot('warn');
+    calm.disabled  = fsm.cannot('calm');
+    clear.disabled = fsm.cannot('clear');
+  };
 
-  onbeforewarn:    function(event, from, to) { this.log("START   EVENT: warn!",  true);  },
-  onbeforepanic:   function(event, from, to) { this.log("START   EVENT: panic!", true);  },
-  onbeforecalm:    function(event, from, to) { this.log("START   EVENT: calm!",  true);  },
-  onbeforeclear:   function(event, from, to) { this.log("START   EVENT: clear!", true);  },
+  var fsm = StateMachine.create({
 
-  onwarn:          function(event, from, to) { this.log("FINISH  EVENT: warn!");    },
-  onpanic:         function(event, from, to) { this.log("FINISH  EVENT: panic!");   },
-  oncalm:          function(event, from, to) { this.log("FINISH  EVENT: calm!");    },
-  onclear:         function(event, from, to) { this.log("FINISH  EVENT: clear!");   },
+    events: [
+      { name: 'start', from: 'none',   to: 'green'  },
+      { name: 'warn',  from: 'green',  to: 'yellow' },
+      { name: 'panic', from: 'green',  to: 'red'    },
+      { name: 'panic', from: 'yellow', to: 'red'    },
+      { name: 'calm',  from: 'red',    to: 'yellow' },
+      { name: 'clear', from: 'red',    to: 'green'  },
+      { name: 'clear', from: 'yellow', to: 'green'  },
+    ],
 
-  onleavegreen:    function(event, from, to) { this.log("LEAVE   STATE: green");  },
-  onleaveyellow:   function(event, from, to) { this.log("LEAVE   STATE: yellow"); },
-  onleavered:      function(event, from, to) { this.log("LEAVE   STATE: red");    this.asyncTransition(); return false; },
+    callbacks: {
+      onbeforestart: function(event, from, to) { log("STARTING UP"); },
+      onstart:       function(event, from, to) { log("READY");       },
 
-  ongreen:         function(event, from, to) { this.log("ENTER   STATE: green");  },
-  onyellow:        function(event, from, to) { this.log("ENTER   STATE: yellow"); },
-  onred:           function(event, from, to) { this.log("ENTER   STATE: red");    },
+      onbeforewarn:  function(event, from, to) { log("START   EVENT: warn!",  true);  },
+      onbeforepanic: function(event, from, to) { log("START   EVENT: panic!", true);  },
+      onbeforecalm:  function(event, from, to) { log("START   EVENT: calm!",  true);  },
+      onbeforeclear: function(event, from, to) { log("START   EVENT: clear!", true);  },
 
-  onchangestate:   function(event, from, to) { this.log("CHANGED STATE: " + from + " to " + to); },
+      onwarn:        function(event, from, to) { log("FINISH  EVENT: warn!");         },
+      onpanic:       function(event, from, to) { log("FINISH  EVENT: panic!");        },
+      oncalm:        function(event, from, to) { log("FINISH  EVENT: calm!");         },
+      onclear:       function(event, from, to) { log("FINISH  EVENT: clear!");        },
 
-  asyncTransition: function() {
-    var self = this;
-    self.logTransition(3);
+      onleavegreen:  function(event, from, to) { log("LEAVE   STATE: green");  },
+      onleaveyellow: function(event, from, to) { log("LEAVE   STATE: yellow"); },
+      onleavered:    function(event, from, to) { log("LEAVE   STATE: red");    async(to); return false; },
+
+      ongreen:       function(event, from, to) { log("ENTER   STATE: green");  },
+      onyellow:      function(event, from, to) { log("ENTER   STATE: yellow"); },
+      onred:         function(event, from, to) { log("ENTER   STATE: red");    },
+
+      onchangestate: function(event, from, to) { log("CHANGED STATE: " + from + " to " + to); }
+    }
+  });
+
+  var async = function(to) {
+    pending(to, 3);
     setTimeout(function() {
-      self.logTransition(2);
+      pending(to, 2);
       setTimeout(function() {
-        self.logTransition(1);
+        pending(to, 1);
         setTimeout(function() {
-          self.logTransition(0);
-          self.transition();
+          fsm.transition(); // trigger deferred state transition
         }, 1000);
       }, 1000);
     }, 1000);
-  },
-
-  logTransition: function(n) {
-    if (n)
-      this.log("PENDING STATE: " + this.transition.to + " in ..." + n);
-  },
+  };
 
-  log: function(msg, separate) {
-    this.count = (this.count || 0) + (separate ? 1 : 0);
+  var pending = function(to, n) { log("PENDING STATE: " + to + " in ..." + n); };
 
-    var output = document.getElementById('output');
-    output.value = this.count + ": " + msg + "\n" + (separate ? "\n" : "") + output.value;
+  fsm.start();
+  return fsm;
 
-    document.getElementById('demo').className = this.current;
-    document.getElementById('panic').disabled = this.cannot('panic');
-    document.getElementById('warn').disabled  = this.cannot('warn');
-    document.getElementById('calm').disabled  = this.cannot('calm');
-    document.getElementById('clear').disabled = this.cannot('clear');
-  }
+}();
 
-};

index.html

@@ -34,9 +34,6 @@ <h1> Finite State Machine </h1>
 
   <script src="state-machine.js"></script>
   <script src="demo/demo.js"></script>
-  <script>
-    Demo.run();
-  </script>
 
 </body> 
 </html>