Merge pull request jakesgordon#10 from cboone/feature/custom_error_callback

 - Added custom event error callbacks

Author: jakesgordon

README.md

@@ -282,6 +282,24 @@ same as the first example in this section where you simply define your own start
 
 So you have a number of choices available to you when initializing your state machine.
 
+Handling Failures
+======================
+
+By default, if you try to call an event method that is not allowed in the current state, the
+state machine will throw an exception. If you prefer to handle the problem yourself, you can
+define a custom `error` handler, which takes a single event name parameter:
+
+    var fsm = StateMachine.create({
+      initial: 'green',
+      error: function(eventName) {
+        return 'event ' + eventName + ' not allowed in current state ' + this.current;
+      },
+      events: [
+        { name: 'panic', from: 'green', to: 'red'   },
+        { name: 'calm',  from: 'red',   to: 'green' },
+    ]});
+    alert(fsm.calm()); // "event calm not allowed in current state green"
+
 Release Notes
 =============
 

state-machine.js

@@ -31,7 +31,7 @@ StateMachine = {
 
     for(var name in map) {
       if (map.hasOwnProperty(name))
-        fsm[name] = StateMachine.buildEvent(name, map[name]);
+        fsm[name] = StateMachine.buildEvent(name, map[name], cfg.error);
     }
 
     for(var name in callbacks) {
@@ -83,14 +83,19 @@ StateMachine = {
       return func.apply(this, [name, from, to].concat(args));
   },
 
-  buildEvent: function(name, map) {
+  buildEvent: function(name, map, errorHandler) {
     return function() {
 
       if (this.transition)
         throw "event " + name + " inappropriate because previous transition did not complete"
 
-      if (this.cannot(name))
-        throw "event " + name + " inappropriate in current state " + this.current;
+      if (this.cannot(name)) {
+        if (errorHandler) {
+          return errorHandler.call(this, name);
+        } else {
+          throw "event " + name + " inappropriate in current state " + this.current;
+        }
+      }
 
       var from  = this.current;
       var to    = map[from];

state-machine.min.js

@@ -148,6 +148,38 @@ test("inappropriate events", function() {
 
 //-----------------------------------------------------------------------------
 
+test("inappropriate event handling can be customized", function() {
+
+  var fsm = StateMachine.create({
+    error: function(eventName) {
+      return 'event ' + eventName + ' inappropriate in current state ' + this.current;
+    },
+    initial: 'green',
+    events: [
+      { name: 'warn',  from: 'green',  to: 'yellow' },
+      { name: 'panic', from: 'yellow', to: 'red'    },
+      { name: 'calm',  from: 'red',    to: 'yellow' }
+  ]});
+
+  equals(fsm.current, 'green', "initial state should be green");
+
+  equals(fsm.panic(), 'event panic inappropriate in current state green');
+  equals(fsm.calm(),  'event calm inappropriate in current state green');
+
+  fsm.warn();
+  equals(fsm.current, 'yellow', "current state should be yellow");
+  equals(fsm.warn(), 'event warn inappropriate in current state yellow');
+  equals(fsm.calm(), 'event calm inappropriate in current state yellow');
+  
+  fsm.panic();
+  equals(fsm.current, 'red', "current state should be red");
+  equals(fsm.warn(),  'event warn inappropriate in current state red');
+  equals(fsm.panic(), 'event panic inappropriate in current state red');
+
+});
+
+//-----------------------------------------------------------------------------
+
 test("event is cancelable", function() {
 
   var fsm = StateMachine.create({